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.
| Library | Link Flag | Description |
|---|---|---|
| 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.
| Library | Link Flag | Description |
|---|---|---|
| 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.
| Library | Link Flag | Description |
|---|---|---|
| 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:
| Library | Link Flag | Description |
|---|---|---|
| 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 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 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
};