Skip to content
jenesisPublic

About

A modern Java build tool: Java-native config, with module-info.java treated as a feature, not an afterthought.

Topics

Resources

Stars

103 stars

Watchers

4 watching

Forks

Repository files navigation

Jenesis

release build

Jenesis - a modern Java build tool

Java-native config, everything the JDK provides built in, with module-info.java treated as a feature, not an afterthought.

A build tool for Java, written in Java. The engine ships with your project as plain source under build/jenesis/ and is launched by the JDK directly, so there is no wrapper binary, and nothing runs between builds unless you ask for it. Everything the JDK provides is built in; a tool the build has to download anyway, such as a linter, a code generator or another language's compiler, is an official plugin that only a project using it fetches. Modules declared with module-info.java drive the build, every step is content-hashed so unchanged work is reused, and every dependency can be pinned by version and by the checksum of the artifact. It needs a JDK 25 or newer, and nothing else. This repository also holds jpx, which runs an already-published module or Maven artifact with one command - npx for Java.

📖 The user documentation lives at jenesis.build. Everything about using the tool - layouts, dependencies, pinning, packaging, publishing, and the jpx command - is there. What follows is for people working on this repository.

Getting Jenesis

Pick whichever fits how you want to manage versions; all three land at the same on-disk state.

sdk install jenesis && jenesis-init      # SDKMAN, then initialise a project
curl -fsSL https://get.jenesis.build | bash   # bootstrap into the current project
curl -fsSL https://get.jenesis.build | JENESIS_MODE=submodule bash   # ... as a git submodule

jpx is its own SDKMAN candidate, installed on its own where only the module runner is wanted:

sdk install jpx

Then, from the project root:

java build/jenesis/Make.java                        # build
java build/jenesis/Jpx.java org.junit.platform.console --version   # run a published module

See jenesis.build/tool/getting-started for the details.

What is in this repository

Path Contents
sources/ The build tool itself, module build.jenesis - Make, Execute and Jpx are the entry points, and the jenesis-make, jenesis-exec and jpx ToolProviders are the same three inside another program's JVM; Project is the configuration API they run and has no main.
tests/ Its tests, module build.jenesis.test.
demo/ 66 self-contained example projects, one per feature, indexed by demo/README.md.
sdk/ The SDKMAN distribution layout and its shell-script tests (sdk/jenesis, sdk/jpx). jenesis-unsafe reads the version recorded in a project's build/jenesis/jenesis.version, installs it where the package manager can, verifies the vendored sources against the published ones and runs the compiled engine - a tree that does not match is refused, so no unreviewed build code is ever executed. jenesis is that launcher behind a floor: a recorded version the floor covers is no longer considered safe, and is refused with jenesis-unsafe named for the builds that have to run it all the same. jenesis-make runs the installed version as it stands, and jenesis-switch moves the shell to the recorded one. Both stay on the released engine, so a refused project still builds as a standard build; only running the vendored sources yourself - in source mode, or off classes compiled once with javac - executes the vendored engine. jenesis-jdk installs a JDK for a jenesis.toolchain.version with SDKMAN, mise or Scoop, once a user names it as jenesis.toolchain.installer.
distribution/ Packager templates that override JReleaser's own, per distribution: the Homebrew formulae, which wrap each command rather than symlinking it so a script still finds its own installation, and the Scoop manifest that describes jpx rather than the build tool. JReleaser would look for these under src/jreleaser/distributions/, so each packager in jreleaser.yml names its templateDirectory here instead - this project has no src/ tree.
build/jenesis A symlink to sources/build/jenesis, so the project builds itself with itself.
benchmark/ The performance harness and its methodology, see benchmark/README.md.
installation/ install.sh, the script served at get.jenesis.build, and install.test.sh, its tests: each mode is installed into a throwaway project and built, run by CI on every platform. worker.js is the Cloudflare Worker that serves that script from the default branch, with worker.test.js covering it on Node's built-in runner.
pom.xml A plain Maven build of the same sources, kept as a fallback (below).

Building it

The project builds itself. Because build/jenesis is a symlink into sources/, the engine you just edited is the engine that runs:

java build/jenesis/Make.java          # compile, test, package
java build/jenesis/Make.java stage    # also lay out the release tree under target/stage/

A root pom.xml is present, so the layout auto-detects as MAVEN; the CI builds it under all four layouts. Delete target/ for a clean run.

When the build tool is broken

The tool builds itself, so a defect in it can leave you unable to build - or, worse, able to build but not to trust the result. The root pom.xml exists for exactly that: it compiles sources/ and tests/ and runs the same test suite with no Jenesis involvement at all.

mvn test

Reach for it to bisect a regression, to check whether a failure is in the tool or in the code under test, and to validate a change before trusting the self-hosted build again. It is a validation path only - it produces no release tree, no pinning, no staging - so a green mvn test means the sources and tests are sound, not that the build tool works.

When Maven Central rate-limits the build

The build fetches Maven artifacts from the remotes MAVEN_REPOSITORY_URI names, or -Djenesis.maven.uri, which outranks it: a comma-separated list asked left to right, where a remote is asked only for what the one before it answers 404 to. Central answers an address that fetches a lot with 429, so a machine that builds often can name Google's mirror of Central first and Central itself second, the pair the workflows of this repository use:

export MAVEN_REPOSITORY_URI=https://maven-central.storage-download.googleapis.com/maven2/,https://repo1.maven.org/maven2/

The mirror syncs some hours behind Central, so Central still serves a release the mirror lacks, also for an official plugin or other module/ name: where the remote the module index redirects to answers 404, the build asks the index again, naming the next remote. A maven-metadata.xml stays with the first remote that has one, so a version range or a pin proposal sees the mirror's list of versions.

Build performance

Measured on the main branch, 67 commits after v0.15.2, by the on-demand benchmark workflow on a GitHub ubuntu-latest runner, with GraalVM JDK 25.0.4 and Maven 3.9.9 (run 36336605019). Both tools compile the same 188 main and 183 test sources with the tests compiled but not executed, from warm dependency caches; wall clock comes from /usr/bin/time rather than from either tool's own report, as the median of five cold runs and of three for the rest.

Scenario Maven 3 Jenesis + daemon native image
cold, empty target/ 14.50 s 13.51 s 7.98 s 8.92 s
warm no-op 1.59 s 0.67 s 0.41 s 0.12 s
one-line edit to a test source 12.02 s 11.40 s 7.09 s 6.87 s
one-line edit to a main source 14.25 s 13.62 s 7.73 s 8.94 s
spurious touch, content identical 14.37 s 0.65 s 0.37 s 0.13 s

The Jenesis column is the javac-precompiled engine. Running it from source costs the launcher's own compile on top - 0.94 s of launch overhead against 0.15 s, and a full engine rebuild whenever the edited file is an engine source, as every main source is in this repository.

The table says two different things. An ordinary edit costs about what Maven costs, because in a single-module project a changed main class invalidates nearly every step below it; the daemon and the native launcher are where the difference comes from. What the content-addressed cache buys is the last two rows - a rebuild that changes nothing costs 0.67 s against 1.59 s, and a file whose timestamp moved while its bytes did not costs 0.65 s against a full 14.37 s Maven rebuild.

With the whole test suite executed, the two tools are level on a cold build - 394.61 s against 402.38 s - because the tests dominate. A warm no-op is where they part: Maven runs the suite again in 387.62 s, Jenesis finds nothing changed in 0.68 s, and in 0.43 s with the daemon.

From an empty machine, Maven transfers up to 18.9 MB for its distribution before it can start and then up to 65.8 MB into an empty repository for a 21.54 s first build. The engine is vendored source: it downloads nothing, compiles itself in 5.01 s, fetches 111 KB and builds in 14.49 s.

The same run measured macos-latest and windows-latest, where every Jenesis column is ahead of Maven in every row as well; both tools are about twice as slow on Windows. Two settings do not pay off on this project: jenesis.make.mode=aot is no faster than the precompiled engine alone (0.77 s against 0.66 s for a no-op, after a 1.90 s training build), and stripping checksums with jenesis.dependency.pin=versions saves nothing measurable (13.35 s against 13.49 s cold).

This is one project on one runner class. The run's summary holds the tables for all three runners, and benchmark/README.md describes the method and what the figures do and do not support.

A native image of the engine

jenesis.make.mode=native runs the build as a native image of the engine. It is kept to follow what GraalVM makes of the engine, not to make a build faster. Make has to run on the java of a GraalVM 25.5 or newer, whose native-image compiles the image:

$GRAALVM_HOME/bin/java -Djenesis.make.mode=native build/jenesis/Make.java

The first build runs on that GraalVM's JVM under its tracing agent, which records what the engine needs in jenesis.aot.folder, and then compiles the image, which takes some minutes. Later builds run the image, with javac inside it and every tool the image does not hold forked from the GraalVM. A compilation with annotation processors or compiler plugins forks javac as well, so that they run on a JVM.

A build that loads no plugin gets an image of the engine alone, of about 75 MB. Where a build the agent watched loaded one, the image is built with GraalVM's experimental runtime class loading instead, so it loads a plugin from its jars as a JVM does, each in a loader of its own and with its own copy of build.jenesis, and interprets it. A plugin then needs nothing recorded, and one added later loads without a new image. That image keeps the whole of java.base, java.xml, java.compiler and jdk.compiler, the modules build.jenesis reads, which makes it about 320 MB; a plugin reaching another module of the JDK ends it with a fatal error. A build loading a plugin in an image of the engine alone fails, and the next build trains an image that loads plugins.

A build reaching what the agent never recorded fails as any build does. The image is compiled again once the engine changes, or after the native folder of jenesis.aot.folder is deleted, from a build that runs on the JVM under the agent once more.

Demos

Every feature has a runnable project under demo/, each with its own build/jenesis symlink, so it runs in isolation from inside its own directory:

cd demo/demo-01-java-pom && java build/jenesis/Make.java

Most are driven by the shipped Make.java; the ones that customise or drive the build themselves ship a build/Demo.java instead. demo/README.md is a guided tour and says which is which. A new feature is expected to arrive with a demo, because CI runs them all.

Continuous integration

  • .github/workflows/build.yml ("Test Jenesis Tool") runs on every push to main and every pull request, across Linux, macOS and Windows:

    • demos-ubuntu, demos-macos, demos-windows - every demo, each with a verification command asserting what it should have produced. The demo list lives in .github/workflows/demos.yml, which each of the three jobs calls once, because one job's matrix may hold only 256 configurations;
    • project - this project itself, under each of the four layouts, with stage;
    • native-image - the GraalVM demo, on a GraalVM runner, executing the produced binary;
    • sdk - stages the jar, populates the SDKMAN layout and runs the sdk/jenesis and sdk/jpx script tests.

    Every build runs under -Djenesis.dependency.pin=strict, so an unpinned dependency fails CI: run pin and commit the result when you change one. Each job uploads its target/ on failure. Every workflow names MAVEN_REPOSITORY_URI in its file as Google's mirror of Central followed by Central itself, as described under When Maven Central rate-limits the build.

  • .github/workflows/benchmark.yml is on-demand (workflow_dispatch) and runs benchmark/benchmark.sh unattended on all three runners. It is where the performance figures come from: the tables land in the run summary and as a per-runner artifact, so re-triggering it is the whole reproduction recipe; the Build performance table above is one such run.

  • .github/workflows/release.yml runs after a successful build on main - see below.

Releasing

A release is triggered by running the Release Jenesis workflow from the Actions tab. Both of its inputs are optional:

  • sha releases that commit; left empty, the head of the branch the workflow runs on is released.
  • tag releases under that tag (v1.2.3 or 1.2.3); left empty, the highest vX.Y.Z tag is taken and the minor bumped (v0.9.0 → 0.10.0). A tag that is not vX.Y.Z is rejected.

The floor jenesis refuses through is the UNSAFE_THROUGH constant in sdk/jenesis/bin/jenesis and the same line in sdk/jenesis/bin/jenesis.bat: it names the newest version that is no longer considered safe to run, so every version up to and including it is refused and only a newer one is executed. Raising it is a deliberate step, taken in both scripts at once, in the release that supersedes the version it names.

The workflow builds with jenesis.project.version set, then hands target/stage/maven/output/ to JReleaser (jreleaser.yml), which signs and uploads to Maven Central, publishes the sdk/jenesis-<version>.zip and sdk/jpx-<version>.zip distributions to Homebrew and Scoop, and cuts the matching v<version> tag. The GitHub release carries the jar and its POM beside the archives, each with its signature and its own .sha256, so the maven template that https://jenesis.build/.well-known/java-repository.properties publishes can name the release as the artifact's location; GitHub adds the source code itself. project.properties carries the POM metadata that a module declaration cannot express. A further step publishes both archives to SDKMAN itself, against the vendor API at state.sdkman.io: it logs in with SDKMAN_EMAIL and SDKMAN_PASSWORD for a ten-minute token, then posts each candidate with its download URL, its SHA-256 and the lts and latest tags that make it the version sdk install resolves. The token expires quickly and the archives must already be attached to the release, so the step runs after JReleaser, never before it.

That step exists only because JReleaser cannot reach the new API: it hardcodes https://vendors.sdkman.io, authenticates with Consumer-Key and Consumer-Token headers, and exposes no property to repoint the host, so a vendor account issued as an email and password cannot be used through it. When JReleaser gains support, the way back is to uncomment the three sdkman blocks in jreleaser.yml, delete the Publish the SDKMAN candidates step, and hand JReleaser the vendor credentials through whatever environment variables it then defines. Nothing else in the release depends on the choice.

The last two steps make both archives installable with mise, for which JReleaser has no packager. The packslip action attests each archive's build provenance, signs a release manifest for it with the job's own GitHub identity (hence id-token: write and attestations: write, and no secret) and attaches the bundle to the release: packslip.sigstore.json backs mise use packslip:jenesis/jenesis, packslip.jpx.sigstore.json backs mise use packslip:jenesis/jenesis/jpx. Each manifest names the commands mise puts on the path and requires Java 25; jenesis-switch is left out, because mise switches versions from mise.toml itself. mise links those commands where Homebrew wraps them, which is why every script follows a link back to its installation. mise remembers the signer as this workflow's file, so signing from any other workflow is a signer change that each user has to accept before mise installs again - the steps stay in release.yml. mise holds a new release back for 24 hours by default.

Credentials never enter the build: it stops at the unsigned, validated bundle.

Working on the code

Read jenesis.build first: the concepts a contributor needs - the step graph, layouts, incremental change detection, the extension points - are documented there rather than duplicated here. Beyond that the source is the reference, every public type under sources/build/jenesis/ being small enough to read end to end, with the tests as executable documentation of the API. java build/jenesis/Make.java skill/start prints the same material as an agent briefing, an overview with a page per topic, as skill/tags. A user hands an agent the move of a Maven or Gradle build by entering ! java build/jenesis/Make.java prompt/migrate in its prompt, which prints that task, or by pasting what the command prints.

Two conventions govern the code here:

  • Steps talk through folders, never through step names. A step finds its input at a well-known path inside each predecessor's output - sources/, classes/, artifacts/ - and writes its own output under the names its consumers look up the same way. Never inspect a predecessor's name to decide what an input is: that rule is what lets a step be spliced between two others without either noticing.
  • Anything that should trigger a rebuild belongs in a serialized field. A step's cache key is a hash of its serialized state, so a knob in a non-transient field re-runs the step when it changes while a value hard-coded in a method body does not - changing a step's logic invalidates nothing on its own.

A plugin's steps follow its code

A step a plugin defines - an InternalModule compiled from a folder, or an ExternalModule resolved by name - is keyed as well by a digest of the jars its module layer is loaded from: the plugin, its dependencies and the build.jenesis it runs on. Editing a plugin, moving it to another version or changing what it depends on therefore runs its steps again, without a serialVersionUID to bump. The engine's own steps are keyed by their serialized state alone, as above.

Bugs, questions and design discussion belong in the issue tracker.

License

Apache License 2.0 - see LICENSE.

About

A modern Java build tool: Java-native config, with module-info.java treated as a feature, not an afterthought.

Topics

Resources

Stars

103 stars

Watchers

4 watching

Forks

Releases

Packages

Contributors

Languages