Setup instructions

JDK and JAVA_HOME

You'll need to have a modern JDK installed. We recommend JDK17 or higher. Any JDK distribution will work. Here are some recommended options:

  • Ubuntu: Install one of the following packages...
    • java-20-amazon-corretto-jdk/stable
    • openjdk-17-jre/stable-security
    • openjdk-17-jdk-headless
  • Other:

You'll need the javap tool from the JDK to build with Duchess. You'll want to configure the JAVA_HOME environment variable to point to your JDK installation. Duchess will use it to locate javap. Otherwise, Duchess will search for it on your PATH. You can configure the environment variables used at build time via Cargo by creating a .cargo/config.toml file (see this example from duchess itself).

Duchess relies on javap to reflect Java type information at build time. It will not be invoked at runtime.

Configuring the CLASSPATH

You will likely want to configure the CLASSPATH for your Rust project as well. Like with JAVA_HOME, you can do that via Cargo by creating a .cargo/config.toml file.

If your Rust project uses external JAR files, you may want to configure it to download them as part of the build. The viper test crate gives an example of how to do that. It uses a build.rs file.

Libjvm and linking

By default, the dylibjvm feature is enabled and Duchess will dynamically load and link libjvm at runtime. Like with javap, it will first search for libjvm in JAVA_HOME if set. Otherwise it will look for java on your PATH to locate the JRE installation. Non-standard installations can also be configured using JvmBuilder.

Without dylibjvm, libjvm must be statically linked.

JNI Versions

By default, we attempt to load JNI 1.6 when compiling for Android, and JNI 1.8 in all other cases. The JNI version can be selected by using the feature jni_ and the JNI version concatenated, for any supported JNI version, with underscores replacing periods. Duchess currently only supports JNI versions 1.6 and 1.8, and only supports 1.6 on Android (the compile will fail if JNI > 1.6 is attempted on Android). Duchess sets the version to the newest version specified by features if features are specified. If you want Duchess to support a newer JNI API version or locking behavior, cut an issue with your use case, and it may be added to Duchess's next release.