Tell the operating system (and Java) where to find the library libcue on your computer:

$ export LD_LIBRARY_PATH=/usr/local/lib/

If you have installed libcue into a different directory than /usr/local/lib/ then adapt the command to refer to that directory instead.

Tell Java where to find the library cue-api-java on your computer:

$ export CLASSPATH='/usr/local/share/java/*'

If you have installed cue-api-java into a different directory than /usr/local/share/java/ then adapt the command to refer to that directory instead.

Cross-check the value of this important variable:

$ echo "$CLASSPATH"
/usr/local/share/java/*

Java’s requirements mean that we need the value of the CLASSPATH variable to end with an asterisk – make sure you see the trailing *.

If this value ends with a filename instead of an asterisk (for example: /usr/local/share/java/CUE.jar) then you need to fix this. Repeat the previous step while making sure that you surround the value of the variable with quotes (') when you export it.

Check that this tutorial’s prerequisites are present:

$ javac --version
javac 22.0.2
$ ls $LD_LIBRARY_PATH | grep libcue.so || echo 'fail!'
libcue.so
$ ls $CLASSPATH | grep /CUE.*jar$ || echo 'fail!'
/usr/local/share/java/CUE.jar

If any of these commands fail then your computer doesn’t have the related prerequisite installed as expected and this is a problem that you need to fix before continuing with this tutorial.

Create a directory to hold some files, and change into it:

$ mkdir -p cue-java-api-tutorials
$ cd cue-java-api-tutorials

Place this Java program in the file GetStarted.java:

import org.cuelang.cue.*;

public class GetStarted {
    public static void main(String[] args) throws Exception {
        // Begin by creating a context. Every CUE value must come from a
        // context, and every CUE operation must use CUE values that come from
        // the *same* context.
        var ctx = new CueContext();

        // The compile() method loads CUE passed as a string and evaluates it.
        var a1 = ctx.compile("x: true");
        var b1 = ctx.compile("y: 42");

        // The equals() method checks concrete values for equality.
        var a2 = ctx.compile("x: false");
        var b2 = ctx.compile("y: 42");
        System.out.println("a1 equals a2:\t\t\t" + a1.equals(a2));
        System.out.println("b1 equals b2:\t\t\t" + b1.equals(b2));

        // The unify() method unifies CUE values, returning a new CUE value.
        var c1 = ctx.compile("a: int");
        var c2 = ctx.compile("a: 5");
        var c3 = ctx.compile("b: true");
        var c = c1.unify(c2).unify(c3);
        var d = ctx.compile("{ a: 5, b: true }");
        System.out.println("c equals d:\t\t\t\t" + c.equals(d));

        // The lookup() method extracts a CUE value from a struct.
        var s = ctx.compile("""
            A: {
                val: 1
                B: {
                    val: 1
                }
            }
        """);
        var sAval  = s.lookup("A").lookup("val");
        var sABval = s.lookup("A.B.val");
        System.out.println("A.val equals A.B.val:\t" + sAval.equals(sABval));
    }
}

Compile the Java program:

$ javac GetStarted.java

The Java compiler automatically uses the value of the CLASSPATH environment variable to locate the JAR file containing cue-api-java.

Run the Java program:

$ java --enable-native-access=ALL-UNNAMED -cp .:$CLASSPATH GetStarted
a1 equals a2:			false
b1 equals b2:			true
c equals d:				true
A.val equals A.B.val:	true

The Java runtime must be told about a slightly different classpath from the compiler, through the -cp flag, because it needs to locate both the cue-api-java JAR and your compiled code. The --enable-native-access flag avoids a runtime warning that the Foreign Function & Memory API is being used by cue-api-java.