How to build Jolt JNI from source

Jolt JNI is free, open-source software.

While pre-built library artifacts (including AARs and JARs) can be downloaded from the Maven Central Repository, some people prefer to build them from source.

You can also build a local copy of the documentation website (including HTML). This is useful if you are editing the documentation, or if your Internet access is limited or unreliable.

Libraries

For desktop platforms

Here’s the recommended procedure for building desktop libraries:

  1. Install build software:

    1. a Java Development Kit (JDK), version 11 or higher, and

    2. one of the supported C++ compilers:

      1. for Linux: the GNU Compiler Collection or Clang

      2. for macOS: Xcode

      3. for Windows: Microsoft Visual Studio

    3. If you use GCC, you might also need to install the "g++-multilib" package:

      1. sudo apt install g++-multilib

  2. Point the JAVA_HOME environment variable to your JDK installation: (That path might look something like "C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot" or "/usr/lib/jvm/java-17-openjdk-amd64/" or "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home".)

    1. using Bash or Zsh: export JAVA_HOME=" path to installation "

    2. using Fish: set -g JAVA_HOME " path to installation "

    3. using PowerShell: $env:JAVA_HOME = ' path to installation '

    4. using Windows Command Prompt: set JAVA_HOME=" path to installation "

  3. Download and extract the Jolt-JNI source code from GitHub:

    1. using Git:

      1. git clone https://github.com/stephengold/jolt-jni.git

      2. cd jolt-jni

      3. git checkout -b latest 0.9.9

    2. using a web browser:

      1. browse to https://github.com/stephengold/jolt-jni/releases/latest

      2. follow the "Source code (zip)" link at the bottom of the page

      3. save the ZIP file

      4. extract the contents of the saved ZIP file

      5. cd to the extracted directory

  4. Edit the "gradle.properties" file to configure the build.

  5. Run the Gradle wrapper:

    1. using Bash or Fish or PowerShell or Zsh: ./gradlew build

    2. using Windows Command Prompt: .\gradlew build

After a successful build, desktop library artifacts will be found in "build/libs".

Translated examples

Once you’ve built a desktop library for your current platform, you can test it by running example apps that have been translated from C++.

The "hello world" example app:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew runHelloWorld

  • using Windows Command Prompt: .\gradlew runHelloWorld

Various scenes in the "performance test" example app:

  1. the ConvexVsMesh scene:

    1. using Bash or Fish or PowerShell or Zsh: ./gradlew runConvexVsMesh

    2. using Windows Command Prompt: .\gradlew runConvexVsMesh

  2. the Pyramid scene:

    1. using Bash or Fish or PowerShell or Zsh: ./gradlew runPyramid

    2. using Windows Command Prompt: .\gradlew runPyramid

  3. the Ragdoll scene:

    1. using Bash or Fish or PowerShell or Zsh: ./gradlew runRagdoll

    2. using Windows Command Prompt: .\gradlew runRagdoll

For Androids

Once you’ve successfully built one or more desktop libraries, you can build Android libraries.

  1. You’ll need to install Android Studio and point the ANDROID_HOME environment variable to that installation.

  2. Run the Gradle wrapper:

    1. using Bash or Fish or PowerShell or Zsh: ./gradlew -b android.gradle build

    2. using Windows Command Prompt: .\gradlew -b android.gradle build

After a successful build, Android library artifacts will be found "build/outputs/aar".

Local installation

Once you’ve successfully built one or more libraries, You can install them to your local Maven repository.

  1. using Bash or Fish or PowerShell or Zsh: ./gradlew install;./gradlew -b android.gradle install

  2. using Windows Command Prompt:

    1. .\gradlew install

    2. .\gradlew -b android.gradle install

Website

  1. Download and extract the jolt-jni-docs source code from GitHub:

    1. using Git:

      1. git clone https://github.com/stephengold/jolt-jni-docs.git

      2. cd jolt-jni

    2. using a web browser:

      1. browse to https://github.com/stephengold/jolt-jni-docs/archive/refs/heads/master.zip

      2. extract the contents of the downloaded ZIP file

      3. cd to the extracted directory

  2. Edit "docs/playbook.yml" and replace "/home/sgold/NetBeansProjects/jolt-jni-docs" with an absolute path to your extracted directory (2 places).

  3. Install Node.js

  4. Install Antora: npm i -D -E @antora/cli@3.1

  5. Run Antora: npx antora docs/playbook.yml

After a successful build, your local site copy will be found in the "docs/build/site" directory.

Cleanup

At any time, you can restore the project to a pristine state:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew clean;./gradlew -b android.gradle clean

  • using Windows Command Prompt:

    • .\gradlew clean

    • .\gradlew -b android.gradle clean