Check that the executable prerequisites are met:

$ javac --version
javac 22.0.2
$ mvn --version
...
$ git --version
git version 2.39.5

Teach Java and the operating system how to locate your libcue installation:

$ export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

This guide builds on the process documented in Building libcue as a shared library. That guide installs libcue into the /usr/local/lib/ directory, and so the build process needs to be instructed to search this directory for shared libraries. Here, we choose to use the LD_LIBRARY_PATH environment variable to achieve this because of how the Maven build process works. We don’t use other mechanisms here, such as invoking Java with the parameter -Djava.library.path=..., because they may not work as expected with Maven.

Whatever mechanism you choose, if you have installed libcue into a different directory then be sure to teach the loader about the appropriate directory for your system.

Clone the cue-api-java repository and change into its directory:

$ git clone https://github.com/cue-lang/cue-api-java cue-api-java-source
...
$ cd cue-api-java-source

Select a specific commit to build:

$ git checkout 3c12bb9e9ea203d4de8308b4145e876e4b60207e
Note: switching to '3c12bb9e9ea203d4de8308b4145e876e4b60207e'.
...

cue-api-java is not currently versioned, so this step uses a specific commit reference.

Use Maven to build cue-api-java:

$ mvn package
...

The build log output from Maven will include the library’s dependencies being downloaded, its tests being run, a summary of the test results, and the final build being performed. If the output does not contain a line matching “BUILD SUCCESS”, you will need to debug and fix the issues with your build.

Create a program to test that Java can load the CUE API successfully:

import org.cuelang.cue.*;

public class TestLoad {
  public static void main(String[] args) throws Exception {
    var ctx = new CueContext();
    System.out.println("CUE loaded successfully!");
  }
}

Compile the test program, after making sure the CUE JAR can be found under a predictable filename:

$ mv target/CUE*.jar CUE.jar
$ javac -cp CUE.jar TestLoad.java

Execute the test program:

$ java --enable-native-access=ALL-UNNAMED -cp CUE.jar:. TestLoad
CUE loaded successfully!

The --enable-native-access flag avoids a runtime warning from Java that the Foreign Function & Memory API is used by cue-api-java to access libcue.

To use the JAR file you built in the previous step multiple tools will need to know the locations of the JAR and the libcue shared library on your computer. The Java compiler, the runtime loader, and the language runtime will need to know these locations every time you compile or run a Java program that uses CUE.

As discussed above, the location of the libcue shared library can be identified using the LD_LIBRARY_PATH environment variable, or other mechanisms such as Java’s -Djava.library.path=... parameter.

You can place the JAR anywhere on your system, and tell Java about that location using one of the various mechanisms that it supports. Java guides on cuelang.org assume that the JAR is available in the directory /usr/local/share/java/, which you can set up as follows:

$ mkdir -p /usr/local/share/java/
$ cp CUE.jar /usr/local/share/java/

On a Linux system your user probably won’t have write access to the /usr/local/share/java/ directory. If so, you will need to run these commands as a more privileged user – possibly the root user, accessed via sudo or su.