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 command-line script, but need to be specified when building with Xcode.

SDK Libraries

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

LibraryLink FlagDescription
iconv -l iconv Used for character encoding and decoding. Required for all J2ObjC usage.
zip -l z Used by java.util.zip. You need to link this if you are linking jre_zip.
Security -framework Security Required if linking 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 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:

LibraryLink FlagDescription
libjre_core.a -l jre_core The minimum set of classes required for J2ObjC's JRE emulation, referenced by all generated source files. Using this If your translated Java sources reference JRE support for things like networking, XML, SQL, etc., then additional libraries will need to be linked in.
libjre_beans.a -l jre_beans Contains the classes 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 The classes from the `java.nio.channels` and `java.nio.channels.spi` packages. The main `java.nio` classes are in the `jre_core` library, so only apps that explicitly use `java.nio.channels` need to link this library.
libjre_concurrent.a -l jre_concurrent The classes in the `java.util.concurrent`, `java.util.concurrent.atomic` and `java.util.concurrent.locks` packages.
libjre_io.a -l jre_io Several classes in the `java.io` package. Many `java.io` classes are in `jre_core`, though, so only include this library if there are unresolved JavaIo* symbol errors.
libjre_net.a -l jre_net The classes in the `java.net` package. 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 in the `java.security` package (a few are in `jre_core`), as well as the classes in `java.security.*`, `javax.crypto.*`, and `javax.security.*`. If you link this you will also need to link the iOS Security framework. (see SDK Libraries)
libjre_sql.a -l jre_sql The classes in the `java.sql` package.
libjre_ssl.a -l jre_ssl The classes in the `javax.net` and `javax.net.ssl` packages.
libjre_util.a -l jre_util Several classes 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 The classes from the XML-related packages, including `javax.xml.*`, `org.w3c.dom.*`, and `org.xml.sax.*`.
libjre_zip.a -l jre_zip The classes 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)

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 are popular Java libraries and Android util classes, which are included in the J2ObjC distribution:

LibraryLink FlagDescription
libguava.a -l guava Guava: Google Core Libraries for Java
libjavax_inject.a -l javax_inject The JSR-330 dependency injection annotation library.
libjsr305.a -l jsr305 The JSR-305 annotations for software defect detection library.
libjunit.a -l junit -ObjC The JUnit test framework.
libmockito.a -l mockito -ObjC The Mockito mocking framework for unit tests in Java.
libprotobuf_runtime.a -l protobuf_runtime A Google Protocol Buffer 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 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 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
  };