Jenesis - a modern Java build tool
Java-native config, everything the JDK provides built in, with
module-info.javatreated 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.
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 submodulejpx is its own SDKMAN candidate, installed on its own where only the module runner is wanted:
sdk install jpxThen, from the project root:
java build/jenesis/Make.java # build
java build/jenesis/Jpx.java org.junit.platform.console --version # run a published moduleSee jenesis.build/tool/getting-started for the details.
| 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). |
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.
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 testReach 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.
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.
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.
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.javaThe 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.
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.javaMost 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.
-
.github/workflows/build.yml("Test Jenesis Tool") runs on every push tomainand 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, withstage;native-image- the GraalVM demo, on a GraalVM runner, executing the produced binary;sdk- stages the jar, populates the SDKMAN layout and runs thesdk/jenesisandsdk/jpxscript tests.
Every build runs under
-Djenesis.dependency.pin=strict, so an unpinned dependency fails CI: runpinand commit the result when you change one. Each job uploads itstarget/on failure. Every workflow namesMAVEN_REPOSITORY_URIin 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.ymlis on-demand (workflow_dispatch) and runsbenchmark/benchmark.shunattended 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.ymlruns after a successful build onmain- see below.
A release is triggered by running the Release Jenesis workflow from the Actions tab. Both of its inputs are optional:
shareleases that commit; left empty, the head of the branch the workflow runs on is released.tagreleases under that tag (v1.2.3or1.2.3); left empty, the highestvX.Y.Ztag is taken and the minor bumped (v0.9.0→0.10.0). A tag that is notvX.Y.Zis 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.
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-
transientfield 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 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.
Apache License 2.0 - see LICENSE.