# Building J2ObjC

## Requirements

- Apple Mac OS X system
- Latest version of [Xcode](https://developer.apple.com/xcode/index.php)
- JDK 21 installed
- Apache Maven
- (Recommended but not required) Google Protocol Buffer source

## Mac Setup

- Install Xcode command line tools by running:

    sudo xcode-select --install

- Add to your `.bash_profile`:

    export JAVA_HOME=`/usr/libexec/java_home -v 21`

- If Maven isn't installed (try `mvn -version` in a terminal), use Homebrew:

    brew install maven

## Create a Fork of the J2ObjC project

To fork the J2ObjC project,
[open its main page](https://github.com/google/j2objc)
and click the Fork button:

![Fork](https://developers.google.com/j2objc/images/j2objc-fork.png)

Select your GitHub account name, and the fork will be created in a few seconds.

Next, clone a copy of your fork to your local system for development. First,
click the \[Clone or download button\], then click the Copy to Clipboard button:

![Clone](https://developers.google.com/j2objc/images/j2objc-clone.png)

Then clone into a local directory:

    git clone (Command-V)  # Paste the copied URL

### Install protobuf and abseil

You need to have protobuf C++ installed before you can build J2ObjC.

To install the protobuf binary package, use Homebrew:

    brew install protobuf

The Protobuf C++ build now depends upon the Abseil library,
so install that as well:

    brew install abseil

You need to set `PROTOBUF_ROOT_DIR` to the root where protobuf is installed.
Normally, that's the Homebrew default `/usr/local`. Add the following to your
`.bash_profile`:

    export PROTOBUF_ROOT_DIR=/usr/local # or your custom Homebrew dir

To verify, run `$PROTOBUF_ROOT_DIR/bin/protoc --version`.

## Building J2ObjC

To build from a command-line in a Terminal window, run:

    # Build just the translator and libraries
    make dist

    # Build the protocol buffer compiler and runtime for J2ObjC
    make protobuf_dist

    # Build everything that is included in the project's
    distribution bundles
    make all_dist

## Testing J2ObjC

To test from a command-line in a Terminal window, run:

    # Run translator and library unit tests
    make test

    # Run all unit tests, including for protocol buffers
    make test_all

## Cleaning a Build

    # Remove all files generated by the build
    make clean

## Parallel Builds

The J2ObjC build supports parallel builds, which are specified using the
`-j<n>` flag, where *n* is the maximum number of concurrent tasks. The maximum
depends on how fast your system is; we suggest starting with `-j4`.
Increase the number to shorten build times if your system can handle
it, and decrease it if make fails with system errors.

## Building 32-bit iOS Architectures

The 32-bit iOS architectures ("iphone" and "simulator") are not built by
default. You can build j2objc with these by first specifying them
in the J2OBJC_ARCHS environment variable:

    $ export J2OBJC_ARCHS="iphone simulator"
    $ make -j8 all_dist

Specifying a subset of supported architectures can generally be used to speed
up local builds, by only specifying the architectures your app needs.
To only build the 64-bit iOS ("iphone64") and its associated simulator
("simulator64"), for example, define `J2OBJC_ARCHS="iphone64 simulator64"`
before running make.

## Building the Full Distribution

Although the j2objc team doesn't post prebuilt distributions to GitHub anymore
due to its file size limitations, the "build everything in one step" script can
still be used:

    $ scripts/build_distribution.sh HEAD-<current-date> $PROTOBUF_ROOT_DIR

This script takes a long time to run because every architecture for every
j2objc package is built. However, it's very useful if there are general build
failures, as it builds with only the minimum set of environment variables.
If the build_distribution script succeeds but the normal build steps don't,
review whether any local environment variables are set incorrectly.