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

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.

LibraryLink FlagDescription
iconv -l iconv Used by 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.

LibraryLink FlagDescription
zip -l z Used by java.util.zip. You need to include 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 _$(j2objcdistribution)/lib, where the _$(j2objcdistribution) 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 _$(j2objcdistribution) in your project; always specify the actual path where you installed J2ObjC.

If you build J2ObjC from a copy of its source code, then _$(j2objcdistribution) 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 _$(j2objcdistribution)/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.

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. 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 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 from the java.nio.channels and java.nio.channels.spi packages.
libjre_concurrent.a -l jre_concurrent Several classes from the java.util.concurrent, java.util.concurrent.atomic and java.util.concurrent.locks packages.
libjre_icu.a -l jre_icu Several classes from android.icu to support time zones (mainly to enable java.time).
libjre_io.a -l jre_io Several (less frequently used) classes from the java.io package.
libjre_net.a -l jre_net Several classes 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 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)
libjre_sql.a -l jre_sql All classes in the java.sql package.
libjre_ssl.a -l jre_ssl All classes in the javax.net and javax.net.ssl packages.
libjre_time.a -l jre_time All classes in the java.time package.
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 All classes from the XML-related packages, including javax.xml.*, org.w3c.dom.*, and org.xml.sax.*.
libjre_zip.a -l jre_zip All 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 Java libraries and Android util classes are included in the J2ObjC distribution as static libraries:

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.
libjson.a -l json The JSON data interchange library. This is the Android version of JSON, which differs slightly from other implementations.
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
  };