Installing

Add the BOM for the version, the umbrella artifact for the toolkit, and one natives jar per platform you run on.

Every artifact is published under the group dev.goldberry (ADR-0510). Versions are calendar versions: 2026.1, 2026.2, 2026.2.1 (ADR-0333).

Note

No release has been cut yet. Every push to master publishes a -SNAPSHOT of the next version to the Central Portal’s snapshot repository, so until the first tag the coordinates below end in -SNAPSHOT and the build needs the snapshot repository.

Gradle

repositories {
    mavenCentral()
    maven { url = 'https://central.sonatype.com/repository/maven-snapshots/' }   // snapshots only
}

dependencies {
    implementation platform('dev.goldberry:goldberry-bom:2026.1-SNAPSHOT')
    implementation 'dev.goldberry:goldberry'                 // common, natives, core and widgets

    // The native library, one classifier per platform you run on.
    runtimeOnly 'dev.goldberry:goldberry-natives::linux-x64'
    runtimeOnly 'dev.goldberry:goldberry-natives::linux-aarch64'
    runtimeOnly 'dev.goldberry:goldberry-natives::macos-aarch64'
    runtimeOnly 'dev.goldberry:goldberry-natives::windows-x64'
}

Maven

<repositories>
  <repository>
    <id>central-snapshots</id>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
  </repository>
</repositories>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.goldberry</groupId>
      <artifactId>goldberry-bom</artifactId>
      <version>2026.1-SNAPSHOT</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>dev.goldberry</groupId>
    <artifactId>goldberry</artifactId>
  </dependency>
  <dependency>
    <groupId>dev.goldberry</groupId>
    <artifactId>goldberry-natives</artifactId>
    <classifier>linux-x64</classifier>
    <scope>runtime</scope>
  </dependency>
</dependencies>

Which natives jars to add

The BOM knows versions and not platforms. A POM has no notion of an operating system, so the umbrella depends on the bindings jar without a classifier and the platform jars are yours to add (ADR-0438).

Add all four. NativeLibrary picks the right one at run time from os.name and os.arch, so the application runs on every machine it is built or run on. The one-platform form is the one that goes wrong quietly, on a developer building on macOS for an application that ships to Linux.

Optional modules

Each is one more line under the BOM. Nothing in the core knows they exist until they are on the path (ADR-0190).

implementation 'dev.goldberry:goldberry-html'
implementation 'dev.goldberry:goldberry-media'
runtimeOnly 'dev.goldberry:goldberry-media::ffmpeg-linux-x64'

Logging

The toolkit logs through SLF4J and binds no implementation. Add one and the toolkit’s diagnostics appear. Add none and you get silence, SLF4J’s own no-provider warning included (ADR-0023).

runtimeOnly 'ch.qos.logback:logback-classic:1.6.3'

The module path

Goldberry’s modules are named: dev.goldberry.core, dev.goldberry.widgets, dev.goldberry.natives, and dev.goldberry.html, dev.goldberry.emoji, dev.goldberry.media and dev.goldberry.gpu for the optional ones. An application on the module path requires the two it uses and opens the packages the toolkit reads at run time:

module com.example.app {
    requires dev.goldberry.core;
    requires dev.goldberry.widgets;

    // The reflective binder reads @Bind fields here, and the parser reads the
    // .kdl and .css resources beside them.
    opens com.example.app to dev.goldberry.core;
}

Native access is granted to the one module that touches native code:

java --enable-native-access=dev.goldberry.natives --module-path lib --module com.example.app/com.example.app.Hello

An application on the class path needs no opens and grants --enable-native-access=ALL-UNNAMED instead. The showcase runs modular, which is what catches an unexported package before a user does (ADR-0023, ADR-0395).

Read next