# Required Link Settings

The link build step (Xcode's "Link Binary With Libraries" build phase) needs J2ObjC-specific flags,
which vary depending on how your application uses translated Java classes. The core flags are set by
the [j2objcc](https://developers.google.com/j2objc/reference/j2objcc) command-line script, but need to be specified when building
with Xcode.

## SDK Libraries

This library is **required** by J2ObjC's JRE implementation. Failure to include this
library will result in undefined symbol errors with names that start with `_iconv`.

| Library | Link Flag | Description |
|---|---|---|
| iconv | -l iconv | Used by [jre_core](https://developers.google.com/j2objc/guides/required-link-flags#jre_core) for character encoding and decoding. |

These libraries are used by J2ObjC's JRE implementation and may need to be linked into your app.

| Library | Link Flag | Description |
|---|---|---|
| zip | -l z | Used by java.util.zip. You need to include this if you are linking [jre_zip](https://developers.google.com/j2objc/guides/required-link-flags#jre_zip). |
| Security | -framework Security | Required if linking [jre_security](https://developers.google.com/j2objc/guides/required-link-flags#jre_security). |

## Library Search Path

J2ObjC's distribution includes several static libraries; to use them, your project needs to tell
the linker where to find them.

Generally, the library search path needs to include _$(j2objc*distribution)/lib* , where the
_$(j2objc*distribution)* variable is the path to your local copy of J2ObjC. For example, if you
unzipped a [J2ObjC release archive file](https://github.com/google/j2objc/releases) to
"/usr/local/", this path would be "/usr/local/j2objc".

**Important** : Do not actually use _$(j2objc*distribution)* in your project; always specify the
actual path where you installed J2ObjC.

If you build J2ObjC from a copy of its source code, then _$(j2objc*distribution)* is your copy's
"j2objc/dist/" directory. This directory will not exist until you build J2ObjC with `make dist`.

### Xcode: Library Search Paths

Update the app target's Library Search Paths by adding _$(j2objc*distribution)/lib* (again, use
the real path).

## JRE Libraries

These libraries implement classes defined by J2ObjC's JRE emulation.

**Note:** the `libjre_core.a` library contains classes from most of the other subset
libraries. The recommended way to reduce app size is to start linking the app
with `-l jre_core`, then add the subset libraries which resolve any missing symbols.
For example, the most commonly used `java.io` classes are in `libjre_core.a`,
so only include the `libjre_io.a` library if there are unresolved symbol errors
whose names begin with `JavaIo`.

| Library | Link Flag | Description |
|---|---|---|
| libjre_core.a | -l jre_core | [The minimum set of classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L76) required for J2ObjC's JRE emulation, referenced by all generated source files. If your translated Java sources reference JRE support for things like networking, XML, SQL, etc., then additional libraries (below) will need to also be linked. |
| libjre_beans.a | -l jre_beans | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1946) from the `java.beans` package. Not all Java Beans classes are included, since many are only used by Swing and AWT apps. |
| libjre_channels.a | -l jre_channels | [Several classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L955) from the `java.nio.channels` and `java.nio.channels.spi` packages. |
| libjre_concurrent.a | -l jre_concurrent | [Several classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L918) from the `java.util.concurrent`, `java.util.concurrent.atomic` and `java.util.concurrent.locks` packages. |
| libjre_icu.a | -l jre_icu | [Several classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L2048) from `android.icu` to support time zones (mainly to enable `java.time`). |
| libjre_io.a | -l jre_io | [Several (less frequently used) classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L751) from the `java.io` package. |
| libjre_net.a | -l jre_net | [Several classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L772) in the `java.net` package. However, the `java.net.URLClassLoader` class is in `jre_security`, while the `javax.net` and `javax.net.ssl` classes are in `jre_ssl`. |
| libjre_security.a | -l jre_security | [Most classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1234) in the `java.security` package (a few are in `jre_core`), as well as the classes in the `java.security.*`, `javax.crypto.*`, and `javax.security.*` packages. If you link this you will also need to link the iOS Security framework. (see [SDK Libraries](https://developers.google.com/j2objc/guides/required-link-flags#sdk_libraries)) |
| libjre_sql.a | -l jre_sql | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1879) in the `java.sql` package. |
| libjre_ssl.a | -l jre_ssl | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1606) in the `javax.net` and `javax.net.ssl` packages. |
| libjre_time.a | -l jre_time | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1973) in the `java.time` package. |
| libjre_util.a | -l jre_util | [Several classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L895) from the `java.util` package, as well as the `java.util.logging` package. Most `java.util` classes are in `jre_core`, though, so only include this library if there are unresolved `JavaUtil*` symbol errors (`JavaUtilConcurrent*` symbols are in the `jre_concurrent` library). |
| libjre_xml.a | -l jre_xml | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1653) from the XML-related packages, including `javax.xml.*`, `org.w3c.dom.*`, and `org.xml.sax.*`. |
| libjre_zip.a | -l jre_zip | [All classes](https://github.com/google/j2objc/blob/master/jre_emul/jre_sources.mk#L1831) from the `java.util.zip` and `java.util.jar` packages. If you link this you will also need to link the SDK zip library. (see [SDK Libraries](https://developers.google.com/j2objc/guides/required-link-flags#sdk_libraries)) |

### libjre_emul.a (**-l jre_emul**)

The `jre_emul` library contains all the classes included in J2ObjC's JRE emulation. If an app is
linked with `jre_emul`, none of the other jre_\* libraries should be included, or the linker will
report duplicate symbol errors. That is because `jre_emul` includes all classes defined in those
other libraries.

## Other J2ObjC Libraries

These Java libraries and Android util classes are included in the J2ObjC
distribution as static libraries:

| Library | Link Flag | Description |
|---|---|---|
| libguava.a | -l guava | [Guava: Google Core Libraries for Java](https://github.com/google/guava) |
| libjavax_inject.a | -l javax_inject | The [JSR-330](https://jcp.org/en/jsr/detail?id=330) dependency injection annotation library. |
| libjson.a | -l json | The [JSON](https://www.json.org/json-en.html) data interchange library. This is the [Android version of JSON](https://android.googlesource.com/platform/libcore/+/refs/heads/master/json/), which differs slightly from other implementations. |
| libjsr305.a | -l jsr305 | The [JSR-305](https://jcp.org/en/jsr/detail?id=305) annotations for software defect detection library. |
| libjunit.a | -l junit -ObjC | The [JUnit](http://junit.org/) test framework. |
| libmockito.a | -l mockito -ObjC | The [Mockito](http://mockito.org/) mocking framework for unit tests in Java. |
| libprotobuf_runtime.a | -l protobuf_runtime | A [Google Protocol Buffer](https://developers.google.com/protocol-buffers/) runtime, optimized for J2ObjC apps. Apps using J2ObjC protobufs should compile their proto files with j2objc_protoc. |
| libandroid_util.a | -l android_util | The \`android_util\` library contains a small subset of the Android API utility classes. It is not intended to provide emulation for an Android environment, but just a way to share useful classes like \`android.util.Log\`. |

## The -ObjC Link Flag

The **-ObjC** flag is frequently used when linking iOS apps, but it is only required when Objective
C classes and categories need to be dynamically loaded from static libraries. This flag causes all
classes in all linked static libraries to be included in the app, whether or not they are actually
used. It's therefore recommended that apps that use J2ObjC only link with the **-ObjC** flag when
classes fail to load at runtime (one symptom is when `JavaLangClassNotFoundException` is thrown).

The JUnit and Mockito test frameworks rely heavily on reflection, so test apps that use them should
link with **-ObjC**.

An alternative to linking in a whole static library so a few classes can be dynamically loaded is
to instead statically reference those classes. In Java, this can be done in a static initializer
block; here's an example from J2ObjC's
[IosSecurityProvider](https://github.com/google/j2objc/blob/master/jre_emul/Classes/com/google/j2objc/security/IosSecurityProvider.java) class:

      // Reference all dynamically loaded classes, so they are linked into apps.
      @SuppressWarnings("unused")
      private static final Class<?>[] unused = {
        IosCertificateFactory.class,
        IosMD5MessageDigest.class,
        IosRSAKeyFactory.class,
        IosRSAKeyPairGenerator.class,
        IosRSASignature.class,
        IosSecureRandomImpl.class,
        IosSHAMessageDigest.class
      };