Java targets and configuration

The target types, configuration properties, and flags contributed by the @fabr-build/java plugin (plugin @fabr-build/java;). They cover compiling, testing, running and packaging Java. Core definitions (like script and generate) are in Core targets and configuration.

This page is generated from fabr list-all, so it never drifts from the code.

More target types are in the plugin’s optional libraries; see Java optional libraries.

Global properties

Property	Default	Description
JACOCO	@mvn:org.jacoco:org.jacoco.core:0.8.14	The JaCoCo analysis library that converts what the agent records into the coverage report, of the same JaCoCo release as JACOCO_AGENT.
JACOCO_AGENT	@mvn:org.jacoco:org.jacoco.agent/runtime:0.8.14	The JaCoCo agent a test JVM runs with under COVERAGE=on: the org.jacoco.agent package’s runtime jar, of the same JaCoCo release as JACOCO.
JAVA	JDK:java	The Java runtime programs run on: a java, by default the JDK release’s.
JAVA_TEST_RUNNER	@fabr-build/java:fabr-junit-runner.jar	The jar that runs a jar_package‘s tests on the JUnit Platform and reports what happened: fabr’s own, by default. It runs with the JUnit Platform launcher the tests’ own test_deps name.
JAVAC	JDK:javac	The Java compiler: a javac, by default the JDK release’s.
JAVADOC	JDK:javadoc	The Java documentation generator: a javadoc, by default the JDK release’s.
JDK	@jdk:21.0.12.1+1	The JDK release the Java tools come from: @jdk:21.0.12.1+1, or any release fabr ls @jdk lists.
JVM_TARGET	jvm21	The Java release compiled classes run on, written jvm<release>: jvm17, jvm21. Sources declared with a java<release> flag compile for that release instead, which must not be later.
MAVEN_REPOSITORY_URL	https://repo1.maven.org/maven2	The Maven repository that @mvn refers to. Set it to use a mirror for every package.

Flags

List a flag in a target’s deps to switch its behaviour for that target.

Flag	Description
java/no_parameters	The compiled classes don’t record their methods’ parameter names, which they otherwise do (javac -parameters) for code that reads them by reflection.
java11	The sources are written for Java 11. See java8.
java17	The sources are written for Java 17. See java8.
java21	The sources are written for Java 21. See java8.
java25	The sources are written for Java 25. See java8.
java8	The sources are written for Java 8: using a later language feature or API is a compile error, whatever release JVM_TARGET names.

Targets

jar_package

Operations: build, doc, run, sources, test

targetdef jar_package {
  srcs                   = FILES;
  deps                   = PACKAGES;
  provided_deps          = PACKAGES;
  optional_provided_deps = PACKAGES;
  compile_deps           = PACKAGES;
  compile_api_deps       = PACKAGES;
  runtime_deps           = PACKAGES;
  processors             = PACKAGES;
  resources              = FILES;
  main_class             = STRING;
  agents                 = PACKAGES;
  manifest               = MAP;
  metadata               = MAP;
  tests                  = FILES;
  test_deps              = PACKAGES;
  test_resources         = FILES;
}

Build a jar from Java sources and resources:

jar_package com.example/app {
  srcs = src/main/java:**/*.java;
  resources = src/main/resources:**;
  deps = @mvn:org.slf4j:slf4j-api:1.7.36;
  main_class = com.example.Main;
  tests = src/test/java:**/*.java;
  test_deps = @mvn:org.junit:junit-bom:5.11.4
              @mvn:org.junit.jupiter:junit-jupiter
              @mvn:org.junit.platform:junit-platform-launcher;
}

fabr run runs its main_class with the jar and everything it requires on the classpath, and fabr test runs the tests its tests compile to on the JUnit Platform, with the test engines and the platform’s launcher in its test_deps. fabr doc generates its javadoc, and fabr sources gives its sources.

Property	Type	Required	Description
srcs	FILES		The Java sources.
deps	PACKAGES		The packages the sources use, and java<release> flags. A BOM here gives the versions of the packages it manages, which may then be written without one.
provided_deps	PACKAGES		Packages the sources use that whatever runs the jar must provide, such as the servlet API a container supplies. The jar does not carry them.
optional_provided_deps	PACKAGES		As provided_deps, for packages whatever runs the jar may leave out: the jar uses them where they are present.
compile_deps	PACKAGES		Packages the sources are compiled against that nothing needs when the jar runs, such as an annotations-only jar. They are not passed on.
compile_api_deps	PACKAGES		As compile_deps, for packages the jar’s own API names, such as the annotations on its public classes: passed on to what compiles against the jar, never installed.
runtime_deps	PACKAGES		Packages the jar needs only when it runs, such as a JDBC driver: not compiled against, and passed on to what runs the jar.
processors	PACKAGES		The annotation processors the compiler runs, such as lombok: packages, resolved apart from the ones the sources use.
resources	FILES		Files to put in the jar as they are, named as they are found on the classpath (application.properties). A jar or zip among them is stored uncompressed.
main_class	STRING		The class the program starts in (com.example.Main), which the jar’s manifest names as its Main-Class: one of the jar’s, or of a package it requires.
agents	PACKAGES		Java agents fabr run runs the jar with: each package’s jar is given the JVM as a -javaagent, and what it requires joins the classpath.
manifest	MAP		Further attributes of the jar’s manifest (Implementation-Version, Automatic-Module-Name), each a string.
metadata	MAP		What the POM a sync publishes the jar with says about it beyond its coordinate and dependencies (name, description, url, licenses, developers, scm), each a POM element: a string, or a block.
tests	FILES		The test sources, compiled against the jar. The test engines on the classpath find the tests among the classes they compile to.
test_deps	PACKAGES		Packages only the tests use: JUnit’s API, its test engines and the JUnit Platform launcher they run on, of one JUnit release.
test_resources	FILES		Files on the classpath the tests run with, as resources are.

java_program

Operations: run

targetdef java_program {
  srcs       = FILES;
  deps       = PACKAGES;
  processors = PACKAGES;
  main_class = STRING;
  args       = STRING;
  jvm_args   = STRING;
  agents     = PACKAGES;
}

A Java program, made to run: its sources compiled and the packages it requires, started in its main class. fabr run runs it, and a generate command may use it as a tool:

java_program spotbugs {
  deps = @mvn:com.github.spotbugs:spotbugs:4.8.6;
  args = -textui;
}

Property	Type	Required	Description
srcs	FILES		The program’s own Java sources, compiled against deps.
deps	PACKAGES		The packages the program runs with, and java<release> flags.
processors	PACKAGES		The annotation processors the compiler runs on srcs: packages, resolved apart from deps.
main_class	STRING		The class the program starts in (com.example.Main). Where it is not given, the class of the sole source, or with no sources, the Main-Class of the sole package’s jar.
args	STRING		Arguments given the program, before any its caller gives.
jvm_args	STRING		Arguments given the JVM, before the program: -Xmx2g, "-Dname=value".
agents	PACKAGES		Java agents the program runs with: each package’s jar is given the JVM as a -javaagent, and what it requires joins the classpath.

war_package

Operations: build, doc, sources

targetdef war_package {
  srcs          = FILES;
  deps          = PACKAGES;
  provided_deps = PACKAGES;
  processors    = PACKAGES;
  resources     = FILES;
  webapp        = FILES;
}

A web application archive: the classes its sources compile to and its resources under WEB-INF/classes, the installation of its deps under WEB-INF/lib, and its webapp files at the root, packed as <name>.war:

war_package shop {
  srcs = src/main/java:**/*.java;
  webapp = src/main/webapp:**;
  deps = @mvn:org.apache.commons:commons-text:1.11.0;
  provided_deps = @mvn:jakarta.servlet:jakarta.servlet-api:6.0.0;
}

Property	Type	Required	Description
srcs	FILES		The Java sources.
deps	PACKAGES		The packages the sources use, and java<release> flags.
provided_deps	PACKAGES		Packages the sources use that the container supplies, such as the servlet API. The archive does not carry them, nor anything they require.
processors	PACKAGES		The annotation processors the compiler runs: packages, resolved apart from the ones the sources use.
resources	FILES		Files on the application’s classpath, under WEB-INF/classes.
webapp	FILES		The web content, at the archive’s root: pages, WEB-INF/web.xml.

ear_package

Operations: build

targetdef ear_package {
  modules   = FILES;
  deps      = PACKAGES;
  resources = FILES;
}

An enterprise application archive: its modules (the wars and jars it deploys) and resources at the root, and the installation of its deps under lib, packed as <name>.ear:

ear_package store {
  modules = shop;
  deps = @mvn:org.apache.commons:commons-lang3:3.14.0;
}

Property	Type	Required	Description
modules	FILES		The modules the application deploys: war_package and jar_package archives.
deps	PACKAGES		The packages the modules share, under lib.
resources	FILES		Files at the archive’s root, such as META-INF/application.xml.

java_compile

Operations: build

targetdef java_compile {
  srcs       = FILES;
  deps       = PACKAGES;
  processors = PACKAGES;
}

Compile Java sources to classes: the classes under classes/, and the sources its annotation processors generate under generated/. A jar_package does this for its own sources.

Property	Type	Required	Description
srcs	FILES		The Java sources.
deps	PACKAGES		The packages the sources use, and java<release> flags.
processors	PACKAGES		The annotation processors the compiler runs: packages, resolved apart from deps.

javadoc

Operations: build

targetdef javadoc {
  srcs = FILES;
  deps = PACKAGES;
}

Generate the javadoc of Java sources: HTML documentation of their API. A jar_package does this for its own sources under doc.

Property	Type	Required	Description
srcs	FILES		The Java sources.
deps	PACKAGES		The packages the sources use, and java<release> flags.

java_installation

Operations: build

targetdef java_installation {
  deps          = PACKAGES;
  provided_deps = PACKAGES;
}

The installation of packages: the jars of every package deps hold or reach, each by its own file name, with the loose files among deps as they are. A package reached only as a provided requirement is not installed.

Property	Type	Required	Description
deps	PACKAGES		The packages installed, and loose files.
provided_deps	PACKAGES		Packages that whatever runs the installation supplies. They are resolved with deps, and left out with everything they require.

maven_repository

targetdef maven_repository {
  url         = REQUIRED STRING;
  id          = STRING;
  auto_attach = STRING;
}

A Maven repository, laid out as Maven Central is.

Property	Type	Required	Description
url	REQUIRED STRING	yes	The URL the repository is published under.
id	STRING		The id of the <server> in ~/.m2/settings.xml whose credentials the repository uses. By default, the repository’s own name (@corp).
auto_attach	STRING		The jars a sync publishes beside each artifact it publishes here, by classifier: sources, javadoc, or both. A target with no sources or doc rule has none.

jdk_distribution

targetdef jdk_distribution {
  url = REQUIRED STRING;
}

Eclipse Temurin JDK releases, from the Adoptium API: @jdk:21.0.12.1+1 is that release for the target platform, and @jdk:21.0.12.1+1:javac its compiler. A release is named as Adoptium names it, less its jdk- prefix (@jdk:8u302-b08 for Java 8); fabr ls @jdk lists them. fabr declares @jdk for you; declaring it yourself points it at a mirror of the API:

jdk_distribution @jdk { url = "https://adoptium.example.com"; }

Property	Type	Required	Description
url	REQUIRED STRING	yes	The URL the Adoptium API is served under.

Provided targets

Ready-made targets declared by these libraries, usable by name in any project.

@mvn

maven_repository @mvn {
  url = ${MAVEN_REPOSITORY_URL};
}

Maven Central, or the repository MAVEN_REPOSITORY_URL names.

@jdk

jdk_distribution @jdk {
  url = https://api.adoptium.net;
}

JDK releases, from the Adoptium API.