The library libcue provides a mechanism to use CUE in C and C-like languages. This guide demonstrates how it can be compiled as a shared library, which is a required step before using it with languages such as Java.

Prerequisites

Set up the build environment

1

Enable cgo:

TERMINAL
$ export CGO_ENABLED=1
2

Check that the Go prerequisites are met:

TERMINAL
$ go version
go version go1.23.2 linux/amd64
$ go env CGO_ENABLED
1

Check that other prerequisites are met:

TERMINAL
$ cc --version
cc (Debian 12.2.0-14) 12.2.0
...
$ git --version
git version 2.39.5
3

Clone the libcue repository and change into its directory:

TERMINAL
$ git clone https://github.com/cue-lang/libcue libcue-source
...
$ cd libcue-source
4

Select a specific commit to build:

TERMINAL
$ git checkout 1c861cc9cdc5584f5d26b0a7112aa2afee74d4cf
Note: switching to '1c861cc9cdc5584f5d26b0a7112aa2afee74d4cf'.
...

libcue is not currently versioned, so this step uses a specific commit reference.

Build the library

5

Build libcue as a shared library:

TERMINAL
$ go build -buildmode=c-shared -o libcue.so
...

The value passed to the -o flag is the filename that will contain the compiled output. This value will vary, depending on your operating system.

The value shown above (libcue.so) is appropriate for most Unix systems, such as Linux. On macOS you should use libcue.dylib, and Windows requires cue.dll (without a “lib” prefix).

Store the shared library

6

To use the shared library built in the previous step the compiler, the runtime loader, and potentially the language runtime will need to know the location of the library on your computer, at the appropriate time. The compiler will need to know this at the point that you compile code, with the language runtime or runtime loader needing the location every time you execute a program that uses libcue.

Some compilers and runtimes expect you to specify locations explicitly; some check predefined lists of locations; and some can be controlled through environment variables and settings. The location where you store the shared library will depend on your operating system, the permissions you have on your computer, and the specific compiler and build system that you intend to use libcue with.

On a Unix system such as Linux the value of the environment variable LD_LIBRARY_PATH and the contents of the file /etc/ld.so.conf are commonly used to control the behaviour of the runtime loader, as explained in The Linux Documentation Project’s Program Library guide. Documentation for Windows also exists.

Here is an example of how to make libcue available to compilers and runtimes, system-wide, under Linux:

TERMINAL
$ cp libcue.so /usr/local/lib/

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