You are reading GraphMaquina 2.0.1. The latest version is 2.0.6.

The Maven adapter

Two plugins are required, and neither works without the other.

The repositories of where the artifacts come from are assumed; graphmaquina-core, graphmaquina-processor and graphmaquina-maven-plugin, with the generator the plugin depends on, must be resolvable, which for Maven Central means nothing further to declare.

<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <lombok.version>1.18.48</lombok.version>
  <graphmaquina.version>x.y.z</graphmaquina.version>
</properties>

<dependencies>
  <dependency>
    <groupId>io.github.graphmaquina</groupId>
    <artifactId>graphmaquina-core</artifactId>
    <version>${graphmaquina.version}</version>
  </dependency>
  <dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>${lombok.version}</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.15.0</version>
      <configuration>
        <annotationProcessorPaths>
          <!-- Lombok first: the GraphMaquina processor reads the accessors Lombok generates. -->
          <path>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
          </path>
          <path>
            <groupId>io.github.graphmaquina</groupId>
            <artifactId>graphmaquina-processor</artifactId>
            <version>${graphmaquina.version}</version>
          </path>
        </annotationProcessorPaths>
      </configuration>
      <executions>
        <!-- Each compilation reads the manifest the generation that precedes it wrote. -->
        <execution>
          <id>default-compile</id>
          <configuration>
            <compilerArgs>
              <arg>-Agraphmaquina.annotationManifest=${project.build.directory}/graphmaquina/main/annotation-manifest.json</arg>
            </compilerArgs>
          </configuration>
        </execution>
        <execution>
          <id>default-testCompile</id>
          <configuration>
            <compilerArgs>
              <arg>-Agraphmaquina.annotationManifest=${project.build.directory}/graphmaquina/test/annotation-manifest.json</arg>
            </compilerArgs>
          </configuration>
        </execution>
      </executions>
    </plugin>
    <plugin>
      <groupId>io.github.graphmaquina</groupId>
      <artifactId>graphmaquina-maven-plugin</artifactId>
      <version>${graphmaquina.version}</version>
      <executions>
        <execution>
          <id>sg-generate</id>
          <phase>generate-sources</phase>
          <goals><goal>generate</goal></goals>
        </execution>
        <execution>
          <id>sg-prepare</id>
          <phase>process-sources</phase>
          <goals><goal>prepare</goal></goals>
        </execution>
        <execution>
          <id>sg-complete</id>
          <phase>compile</phase>
          <goals><goal>complete</goal></goals>
        </execution>
        <execution>
          <id>sg-generate-test</id>
          <phase>generate-test-sources</phase>
          <goals><goal>generate-test</goal></goals>
        </execution>
        <execution>
          <id>sg-prepare-test</id>
          <phase>process-test-sources</phase>
          <goals><goal>prepare-test</goal></goals>
        </execution>
        <execution>
          <id>sg-complete-test</id>
          <phase>test-compile</phase>
          <goals><goal>complete-test</goal></goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

The release does not have to be written out when a parent already sets it — the Spring Boot parent, for instance, derives maven.compiler.release from java.version, and the plugin resolves the setting the way Maven resolves a parameter. The checks below read the compiler's configuration as maven-compiler-plugin 3.15.0 passes it to javac, the version this snippet pins. What matters is that the effective release is 21 or later. The test compilation reads <testRelease>, <testSource> and <testTarget>, or their maven.compiler.test* properties, in place of <release>, <source> and <target> wherever they are set, as maven-compiler-plugin does.

Contents

The six goals

Goal Phase What it does
generate generate-sources checks the compiler configuration, runs the generator, adds target/generated-sources/graphmaquina as a compile source root
prepare process-sources retires the outputs the previous compilation owned, the published index among them, and dates the generated carrier past the newest file the class output held before that retirement; maven-compiler-plugin 3.15.0 recompiles without that date, since the carrier has no class file by then
complete compile publishes the index of what javac accepted and seals the inventory
generate-test generate-test-sources the same for the test source set, into target/generated-test-sources/graphmaquina
prepare-test process-test-sources the same for the test source set
complete-test test-compile the same for the test source set

The goal prefix is graphmaquina, so a goal can also be invoked directly, for example mvn graphmaquina:generate.

A goal does nothing, and says so at info level (StateGraph skips <compilationId>: …), for a compilation the build switches off the way maven-compiler-plugin skips its own goal: maven.main.skip or <skipMain> for the three main goals, maven.test.skip or <skip> for the three test goals. So does it for a compilation the default lifecycle runs no execution of the compiler's goal for, as when default-compile is bound to the phase none, or to a phase of another lifecycle such as pre-site, and nothing else compiles the main sources. Nothing is generated, retired or published then. All six do nothing in a project packaged as pom, such as the parent of a multi-module build whose modules inherit the executions.

The six goals across the default lifecycle's phases:

Test compilation

Main compilation

generate-sources
graphmaquina:generate

process-sources
graphmaquina:prepare

compile
javac in default-compile,
then graphmaquina:complete

generate-test-sources
graphmaquina:generate-test

process-test-sources
graphmaquina:prepare-test

test-compile
javac in default-testCompile,
then graphmaquina:complete-test

Test compilation

Main compilation

generate-sources
graphmaquina:generate

process-sources
graphmaquina:prepare

compile
javac in default-compile,
then graphmaquina:complete

generate-test-sources
graphmaquina:generate-test

process-test-sources
graphmaquina:prepare-test

test-compile
javac in default-testCompile,
then graphmaquina:complete-test

The observed order of a mvn test-compile; the plugin's own suite checks, from real Maven output, that each GraphMaquina goal runs in this order around its compiler execution:

graphmaquina:generate (sg-generate)
graphmaquina:prepare (sg-prepare)
resources:resources
compiler:compile (default-compile)
graphmaquina:complete (sg-complete)
graphmaquina:generate-test (sg-generate-test)
graphmaquina:prepare-test (sg-prepare-test)
resources:testResources
compiler:testCompile (default-testCompile)
graphmaquina:complete-test (sg-complete-test)

Declaration order in the POM does not matter for default-compile and default-testCompile: Maven runs the executions the lifecycle binds before those a POM adds to the same phase. An execution of the compiler a POM adds itself, as below, runs among the others of its phase in the order their plugins are declared, so declare maven-compiler-plugin before graphmaquina-maven-plugin: otherwise complete would run before that javac, and generate refuses the build before anything is retired, naming both executions.

The compiler execution the goals read

The checks and the request read the execution of the compile goal of maven-compiler-plugin, testCompile for the test goals, that the default lifecycle runs and that compiles the vocabulary the generator writes, whatever its id. An execution runs there when it is bound to a phase of the default lifecycle, the one the StateGraph goals run in: the phase it declares, else the default phase of its goal, compile or test-compile. One bound to anything else is never read: one bound to none never runs, and one bound to a phase of another lifecycle, such as pre-site or clean, runs only when the build invokes that lifecycle, never between the preparation and the completion. So a build may bind default-compile and default-testCompile to none and compile its Java sources through executions of its own, as kotlin-maven-plugin asks a mixed Kotlin and Java build to do; the manifest argument and every setting the adapter checks then belong to those executions. An execution compiles the vocabulary unless its own <compileSourceRoots> leave out the directory the generator writes into; one that compiles another source root into a multi-release jar, with <multiReleaseOutput> and roots of its own, runs untouched beside the main compilation. When no execution of the goal runs, the compilation is skipped, as above. Two running executions that both compile the vocabulary are refused, naming both: javac would compile it twice into one class output, and the later run fails on the classes of the earlier one.

Every setting the goals read from that execution, or from the property the setting is bound to, is read as Maven evaluates it for the compiler, through Maven's own evaluator of plugin parameters. An expression the effective model leaves for that evaluator, such as ${session.executionRootDirectory} or ${settings.localRepository}, is completed first, so an <outputDirectory> or <compileSourceRoots> spelled with one is checked, and passed to the generator, as the compiler gets it. A value that is one expression naming an object Maven does not take for that setting, such as ${project.file} for a text, counts as unset, and an expression that cannot be completed yet stays as it is written, as the compiler arguments do.

Outputs

Path Content
target/generated-sources/graphmaquina the generated vocabulary of the main compilation
target/generated-test-sources/graphmaquina the same for the test compilation
target/graphmaquina/main/{request,annotation-manifest,owned-outputs,processor-inventory}.json the main cycle's request, manifest, sealed inventory and the processor's own inventory
target/graphmaquina/main/annotation-manifest.pending.json the generation's recovery ownership; not a manifest javac may consume
target/graphmaquina/main/owned-outputs.pending.json the pending inventory: what the preparation is retiring; left behind by a compilation javac rejects, and consumed by the next preparation
target/graphmaquina/test/… the same for the test compilation
target/classes/META-INF/graphmaquina/exports.json the published index, packaged into the jar
target/classes/META-INF/graphmaquina/pending-exports.json the provisional index the processor writes during javac, which complete promotes to exports.json

The compilation carrier, io/github/graphmaquina/generated/bootstrap/GraphCompilation<digest>.java, is tool-internal: complete removes its class file, so the jar never carries it. This plugin configures no other plugin, and generate adds target/generated-sources/graphmaquina to the compile source roots, which maven-source-plugin and maven-javadoc-plugin read: the carrier's source lands in the sources jar and its page in the javadoc unless their configuration leaves it out. In the <configuration> of maven-javadoc-plugin 3.12.0, either of these settings leaves it out, except that sourceFileExcludes is ignored when <subpackages> is set:

<sourceFileExcludes>
  <sourceFileExclude>io/github/graphmaquina/generated/bootstrap/**</sourceFileExclude>
</sourceFileExcludes>
<!-- or -->
<excludePackageNames>io.github.graphmaquina.generated.bootstrap</excludePackageNames>

In the <configuration> of maven-source-plugin 3.4.0, this one does:

<excludes>
  <exclude>io/github/graphmaquina/generated/bootstrap/**</exclude>
</excludes>

Sources, release and encoding

The source roots are the compiler's own <compileSourceRoots> when the execution declares them, a relative one resolved against the directory Maven was started in, as maven-compiler-plugin resolves it, and the project's otherwise; an empty <compileSourceRoots/> stands for the project's. A source root the execution does not narrow is passed to the generator whole, but for the case below; one its <includes> or <excludes> narrow (<testIncludes>, <testExcludes> or <testIncrementalExcludes> for the tests) is passed as the files they select, with the patterns matched as the compiler's plexus-utils scanner matches them on the platform the build runs on, %ant[...] and %regex[...] included, and without the files that scanner excludes by default, the list of plexus-utils, which leaves out ._* copies and the directories of version control systems among others. That scanner spells a path with the file separator of the platform, / or \, and rewrites the separators of a %regex[...] pattern for it: every pair of backslashes becomes / where the separator is /, and every / becomes a pair of backslashes, an escaped backslash, where it is \. So / and an escaped backslash stand for the separator on either platform, while an expression that escapes a /, such as fx\/drafts\/.*, selects the drafts only where the separator is /. Directories are entered as that scanner enters them: only when an include matches the directory and no exclude does, or when an include could match a path below it. Where the separator is /, an include that starts with a separator never can: it matches a path as if it had no leading separator, so /fx/** selects the sources under fx, a directory it matches, while /io/github/graphmaquina/generated/** alone selects nothing, since the scanner never enters io. Where the separator is \, as on Windows, plexus-utils also lets the scanner in for such an include as if it had no leading separator, so /io/github/graphmaquina/generated/** selects the sources under io/github/graphmaquina/generated. A directory that cannot be listed is read as an empty one, as that scanner reads it.

The generator walks a whole root as Gradle walks a source directory, with Ant's shorter default list: it leaves out every directory a default exclude names, with everything inside it. The compiler's scanner leaves out what is inside a directory only when an exclude ending in /** names it, as one names each directory of a version control system, so a root under which javac compiles a source inside a directory named like an excluded file, old~ or .gitignore for instance, is passed as the files the compiler selects, as a narrowed one is. So is a root that holds a directory the generator's walk would open but cannot list: the walk would fail on it, while the compiler's scanner, and so the files passed in its place, read it as an empty one. Under a root passed whole, a .java file inside an RCS, BitKeeper, ChangeSet, _darcs, .metadata, .arch-ids or .darcsrepo directory, or one named -darcs-backup*, is read by the generator although javac never compiles it. Symbolic links are followed, and a link that leads back into a directory being walked is skipped.

The request also carries the release javac compiles at, <release>, else <target>, or their properties, with the test settings for the test compilation. javac takes the last --release it is given, and maven-compiler-plugin passes a release that is set ahead of the compiler arguments, so the last --release compiler argument, spelled --release N or --release=N, wins over that release; without a release, the compiler passes -source and -target, which javac refuses beside a --release. The request also carries the encoding javac reads the sources in. The configured encoding is <encoding>, else project.build.sourceEncoding. A javac that compiles inside Maven through the javax.tools API, as it does by default, reads the sources through a file manager maven-compiler-plugin opens in the configured encoding, which wins over every -encoding compiler argument: the encoding is the configured one, else the last -encoding compiler argument. A javac the compiler forks, as it does when <fork> is true and when it compiles with a jdk toolchain, or runs inside Maven through com.sun.tools.javac.Main, as it does when <forceLegacyJavacApi>, <forceJavacCompilerUse> or their maven.compiler.* property is true, gets the configured encoding as an -encoding ahead of the compiler arguments and takes the last one: the encoding is the last -encoding compiler argument, else the configured one. The generator parses at that release, reads in that encoding and writes the generated sources in it; without an encoding, it reads and writes UTF-8. The companions the annotation processor generates hold ASCII only, every other character written as a \uXXXX escape, so javac writes them alike in any encoding. A javac that compiles inside Maven through the javax.tools API still writes them in the last -encoding compiler argument and reads them back in the configured encoding, so generate refuses an -encoding compiler argument that names another charset than the configured one, as listed below.

Configuration parameters

Parameter Property Default
javaExecutable graphmaquina.javaExecutable the java of the jdk toolchain selected for the build, else the java of the JVM running Maven; whichever it is must belong to a JDK 21 or later, the one javac compiles with
compilationId graphmaquina.compilationId groupId:artifactId:main, and groupId:artifactId:test for the test source set; a value that is set, as through -Dgraphmaquina.compilationId, applies to the main and the test compilation alike

Both parameters can also be set in the <configuration> of one execution, which is how the main and the test compilation get distinct identities of your choice. Each goal binds to its default phase, the one in the table of the six goals, so an execution may leave <phase> out. The goals are thread-safe, so a parallel build (mvn -T) can run them, and the plugin requires Maven to run on Java 21 or later. The generator is a dependency of the plugin, at the plugin's own version, which Maven resolves with the plugin from the plugin repositories. mvn -X logs the generator's command line, and anything the generator writes to its error stream while it succeeds is logged as a warning.

What the Maven adapter requires, and refuses

Every requirement below is checked by generate, and by generate-test for the test compilation, before anything is written or retired, on the compiler execution the goals read, and every failure names what to change.

Lifecycle order

Release, processor path and processor list

Class output, sources and manifest

JDK, generated sources and encoding

How the checks read paths and compiler arguments

Paths are compared once their symbolic links are resolved, as javac resolves the directories it writes into, so naming the project through a link, as mvn -f <link>/pom.xml does, or a link inside a configured path, makes no two names of one directory differ.

The checks read the compiler arguments as maven-compiler-plugin 3.15.0 passes them to javac: the entries of the deprecated <compilerArguments> map, sorted by key, each key once with its last value, as Maven converts that map; then <compilerArgument>; then the values of <compilerArgs>. The test compilation takes <testCompilerArguments> and <testCompilerArgument> over the first two when they are set. Each argument is evaluated as Maven evaluates a String parameter it hands the compiler, as far as that can be told when the checks run: ${settings.localRepository} or ${session.executionRootDirectory} is completed, and $$ becomes $ in a value that holds no ${…}, or after the last ${…} of one that does. An argument that is one expression naming an object Maven does not take for a String, such as ${project.file}, or that evaluates to an empty text, is left out, as javac never gets it, and a <compilerArguments> value that does so leaves its key alone. An expression that cannot be completed yet stays as it is written: one about the running goal or its plugin, or a property not set when the checks run, which a plugin bound to a later phase may still set. A list parameter written as comma-separated text, such as <compilerArgs>-Xlint:all,-Werror</compilerArgs>, is evaluated, then split on every comma, as Maven splits it, each part evaluated again, and so are <annotationProcessors>, <compileSourceRoots> and every list of patterns, for these checks and, for the roots and the patterns that select sources, for the sources passed to the generator. <annotationProcessors> can therefore name its processors as text, <annotationProcessors>p.First,p.Second</annotationProcessors>, or in one element that holds a comma list, <annotationProcessor>p.First,p.Second</annotationProcessor>, as well as one name per element: javac gets the names joined by commas and splits them on every comma again.

The processor-list check refuses only a list that leaves out the StateGraph processor or holds a name that is not a valid qualified class name. Other mistakes in a processor list are javac's to report, such as a well-formed name of a class that is on no processor path, a misspelt one for instance, a name of a class that is no annotation processor, or a -processor argument with nothing after it: the compilation then fails after the preparation, like any compilation javac rejects, and the next preparation cleans up after it from the pending inventory it left.


Next: Build troubleshooting and limits. Back to the documentation index.