Apache Maven Build Cache Extension

BuildCacheConfig

Maven Incremental Build and Cache configuration, stored in .mvn/maven-build-cache-config.xml

<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
  <configuration>
    <enabled/>
    <hashAlgorithm/>
    <validateXml/>
    <mandatoryClean/>
    <multiModule>
      <discovery>
        <scanProfiles/>
      </discovery>
    </multiModule>
    <projectVersioning adjustMetaInf=.. calculateProjectVersionChecksum=.. />
    <remote enabled=.. saveToRemote=.. transport=.. id=.. >
      <url/>
    </remote>
    <attachedOutputs>
      <dirNames>
        <dirName glob=.. />
      </dirNames>
    </attachedOutputs>
    <local>
      <location/>
      <maxBuildsCached/>
    </local>
    <debugs/>
  </configuration>
  <input>
    <global>
      <glob/>
      <includes>
        <include recursive=.. glob=.. />
      </includes>
      <excludes>
        <exclude glob=.. entryType=.. matcherType=.. />
      </excludes>
    </global>
    <plugins>
      <plugin groupId=.. artifactId=.. >
        <effectivePom>
          <excludeProperties/>
        </effectivePom>
        <dirScan ignoreParent=.. mode=.. >
          <includes>
            <include recursive=.. glob=.. tagName=.. />
          </includes>
          <excludes>
            <exclude tagName=.. />
          </excludes>
          <tagScanConfigs>
            <tagScanConfig recursive=.. glob=.. tagName=.. />
          </tagScanConfigs>
        </dirScan>
        <executions>
          <execution ignoreParentConfig=.. >
            <execIds/>
            <dirScan ignoreParent=.. mode=.. >
              <includes>
                <include recursive=.. glob=.. tagName=.. />
              </includes>
              <excludes>
                <exclude tagName=.. />
              </excludes>
              <tagScanConfigs>
                <tagScanConfig recursive=.. glob=.. tagName=.. />
              </tagScanConfigs>
            </dirScan>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </input>
  <output>
    <exclude>
      <patterns/>
    </exclude>
  </output>
  <executionControl>
    <runAlways>
      <plugins>
        <plugin groupId=.. artifactId=.. />
      </plugins>
      <executions>
        <execution groupId=.. artifactId=.. >
          <execIds/>
        </execution>
      </executions>
      <goalsLists>
        <goalsList groupId=.. artifactId=.. >
          <goals/>
        </goalsList>
      </goalsLists>
    </runAlways>
    <ignoreMissing>
      <plugins>
        <plugin groupId=.. artifactId=.. />
      </plugins>
      <executions>
        <execution groupId=.. artifactId=.. >
          <execIds/>
        </execution>
      </executions>
      <goalsLists>
        <goalsList groupId=.. artifactId=.. >
          <goals/>
        </goalsList>
      </goalsLists>
    </ignoreMissing>
    <reconcile logAllProperties=.. >
      <plugins>
        <plugin goal=.. groupId=.. artifactId=.. >
          <reconciles>
            <reconcile propertyName=.. skipValue=.. defaultValue=.. />
          </reconciles>
          <logs>
            <log propertyName=.. />
          </logs>
          <nologs>
            <nolog propertyName=.. />
          </nologs>
          <logAll/>
        </plugin>
      </plugins>
    </reconcile>
  </executionControl>
</cache>

cache

Cache build metadata

Element	Type	Description
`configuration`	`Configuration`	Configuration of main cache properties
`input`	`Input`	Configuration for source code input files participating in checksum calculation
`output`	`Output`	Configuration for output artifacts, it's needed if you want to explicitly include/exclude something from caching
`executionControl`	`ExecutionControl`	Execution rules for plugins in cached mode. Defines which plugins should run always

configuration

No description.

Element	Type	Description
`enabled`	`boolean`	No description. Default value is: `true` .
`hashAlgorithm`	`String`	One of XX, XXMM, METRO, METRO+MM, SHA-1, SHA-256, SHA-384, SHA-512 Default value is: `XX` .
`validateXml`	`boolean`	Validate cache config and builds metadata against xsd. TODO: not implemented Default value is: `false` .
`mandatoryClean`	`boolean`	Enable the cache storing ability only if a build went through the clean lifecycle. Default value is: `false` .
`multiModule`	`MultiModule`	Specifies related to multi module projects configuration.
`projectVersioning`	`ProjectVersioning`	Specifies parameters to handle project version changes.
`remote`	`Remote`	No description.
`attachedOutputs`	`AttachedOutputs`	No description.
`local`	`Local`	No description.
`debugs/debug*`	`List<String>`	(Many) FileHash (causes file hash is saved in build metadata) or EffectivePom (causes effective pom info is saved in build metadata)

multiModule

No description.

Element	Type	Description
`discovery`	`Discovery`	Section to specify how to discover multi module projects.

discovery

No description.

Element	Type	Description
`scanProfiles/scanProfile*`	`List<String>`	(Many) Profiles to discover multi module project

projectVersioning

No description.

Attribute	Type	Description
`adjustMetaInf`	`boolean`	Determines whether version in metadata must be changed according to building project version. Default value is: `false` .
`calculateProjectVersionChecksum`	`boolean`	Determines whether project version should be included to calculate checksum input. Default value is: `false` .

remote

No description.

Attribute	Type	Description
`enabled`	`boolean`	No description. Default value is: `true` .
`saveToRemote`	`boolean`	Save output to remote cache. Recommended to enable on CI agents only. Default value is: `false` .
`transport`	`String`	The transport to use, currently, only 'resolver' is supported. Default value is: `resolver` .
`id`	`String`	The repository id used to find authentication / mirror information in maven settings, default to 'cache'. Default value is: `cache` .

Element	Type	Description
`url`	`String`	Address of remote cache

attachedOutputs

Section relative to outputs which are not artifacts but need to be saved/restored.

Element	Type	Description
`dirNames/dirName*`	`List<DirName>`	(Many) Path to a directory containing files which needs to be saved/restored (relative to the build directory).

dirName

Path to a directory containing files which needs to be saved/restored (relative to the build directory).
Examples :

<dirName>classes</dirName> : files in ${project.basedir}/target/classes
<dirName glob="jacoco.xml"></dirName> : jacoco report files in ${project.basedir}/target
<dirName>../src/main/javagen</dirName> : files in ${project.basedir}/src/main/javagen (in this exemple, javagen is a folder saved in git but erased on clean)

Element Content: Directory name in build output directory to attach to cached artifacts.

Attribute	Type	Description
`glob`	`String`	Entries are filtered by matching this glob. Default value is: `*` .

local

No description.

Element	Type	Description
`location`	`String`	The base directory where the local cache is located. Defaults to {@code $\{localRepository}/../cache}.
`maxBuildsCached`	`int`	Maximum number of cached build per artifact in local cache. First created cache (the oldest) is evicted if breached. Default value is: `3` .

input

Configuration for source code input files participating in checksum calculation

Element	Type	Description
`global`	`PathSet`	Global input calculation rules applicable to all projects and plugins in the build
`plugins/plugin*`	`List<PluginConfigurationScan>`	(Many) Plugin specific input calculation rules

global

Global input calculation rules applicable to all projects and plugins in the build

Element	Type	Description
`glob`	`String`	Type of files to globally scan. All types are scanned by default. Example to scan only java and xml files : `{.java,.xml}` Default value is: `*` .
`includes/include*`	`List<Include>`	(Many) Extra paths to scan in order to compute the checksum (Project and test - sources/resources are already in the scan list)
`excludes/exclude*`	`List<Exclude>`	(Many) Paths and files to exclude from checksum computation

include

file or a directory path to add to checksum computation. Relative path are relative to each module basedir.

Include elements can also be added per project with the use of maven properties.

Element Content: Path to add to the checksum computation

Attribute	Type	Description
`recursive`	`boolean`	Will search in sub-folders if set to true Default value is: `true` .
`glob`	`String`	Files in a directory are filtered by matching their names against this glob.

exclude

A file or a directory path to exclude from the checksum computation. Relative path are relative to each module basedir.

When referring to a directory, additional properties help adjust the scope of the exclusion:

glob - only entries matching this glob pattern are excluded
entryType - type of entries excluded from the scan
matcherType - entry property on which the glob matching is applied

By default, targeting a directory excludes everything underneath it.

Examples :

<exclude>src/main/doc</exclude> : excludes everything under : ${project.basedir}/src/main/doc
<exclude>src/main/java/package-info.java</exclude> : excludes this file : ${project.basedir}/src/main/java/package-info.java
<exclude glob="package-info.java"></exclude> : excludes all the files named package-info.java
<exclude glob="src/main/resources/**.txt" entryType="FILE" matcherType="PATH" ></exclude> : excludes all the text files located under the "resources" folder

Exclude elements can also be added per project with the use of maven properties.

Element Content: An absolute or relative path to a filename or a directory. In the later case, the exclusion is applied starting from this directory (can be beneficial in term of performances). If empty, the glob is applied on every file listed as a potential part of the checksum.

Attribute	Type	Description
`glob`	`String`	Entries are filtered by matching this glob (see matcherType property). Default value is: `**` .
`entryType`	`String`	Type of entries filtered. One of FILE, DIRECTORY, ALL. Excluding a directory excludes its subfiles and subdirectories. Default value is: `ALL` .
`matcherType`	`String`	The entry property matched for exclusion. One of FILENAME, PATH. For a path, if the exclusion value is empty or a relative path, matching is done relatively to the project folder. Default value is: `FILENAME` .

plugin

No description.

Attribute	Type	Description
`groupId`	`String`	No description.
`artifactId`	`String`	No description.

Element	Type	Description
`effectivePom`	`EffectivePom`	Effective pom calculation rules
`dirScan`	`DirScanConfig`	Specifies plugin level rules of configuration processing in search of referenced source files
`executions/execution*`	`List<ExecutionConfigurationScan>`	(Many) Specifies execution specific configuration processing in search of referenced source files

effectivePom

No description.

Element	Type	Description
`excludeProperties/excludeProperty*`	`List<String>`	(Many) Plugin configuration property should be excluded from effective pom calculation

dirScan

No description.

Attribute	Type	Description
`ignoreParent`	`boolean`	Ignore parent settings or inherit and merge Default value is: `false` .
`mode`	`String`	Either 'auto' (scan directory accordingly to cache implementation) or 'skip' (skip directory).

Element	Type	Description
`includes/include*`	`List<TagScanConfig>`	(Many) Forces cache to treat property value as input and include in calculation. If set, only included properties will be takein in calculation (whitelist)
`excludes/exclude*`	`List<TagExclude>`	(Many) Tag to exclude when scanning plugin configuration for input files (blacklist)
`tagScanConfigs/tagScanConfig*`	`List<TagScanConfig>`	(Many) Additional processing rules for non-blacklisted tags

include

No description.

Attribute	Type	Description
`recursive`	`boolean`	No description. Default value is: `true` .
`glob`	`String`	No description. Default value is: `*` .
`tagName`	`String`	No description.

exclude

No description.

Attribute	Type	Description
`tagName`	`String`	No description.

tagScanConfig

No description.

Attribute	Type	Description
`recursive`	`boolean`	No description. Default value is: `true` .
`glob`	`String`	No description. Default value is: `*` .
`tagName`	`String`	No description.

execution

No description.

Attribute	Type	Description
`ignoreParentConfig`	`boolean`	ignore parent config or inherit/merge Default value is: `false` .

Element	Type	Description
`execIds/execId*`	`List<String>`	(Many) No description.
`dirScan`	`DirScanConfig`	Specifies rules of configuration processing in search of referenced source files

output

No description.

Element	Type	Description
`exclude`	`OutputExclude`	Patterns to exclude output artifacts applicable to all projects in the build

exclude

No description.

Element	Type	Description
`patterns/pattern*`	`List<String>`	(Many) No description.

executionControl

No description.

Element	Type	Description
`runAlways`	`Executables`	Specify which plugin should run always if present in build regardless of cached status
`ignoreMissing`	`Executables`	Specify which executions/plugins/goals do not affect generated artifacts and do not affect build correctness. If cached build lacks of ignorable executions only, it still could be reused. Typically case is then cached build is produced with 'verify' and you locally you run 'install'. Strictly speaking these are different builds but in most of cases you want this difference to be ignored
`reconcile`	`Reconcile`	Specify which plugin should run always if present in build regardless of cached status

runAlways

No description.

Element	Type	Description
`plugins/plugin*`	`List<PluginSet>`	(Many) Specify which executions should run always if present in build regardless of cached status
`executions/execution*`	`List<ExecutionIdsList>`	(Many) Specify which executions should run always if present in build regardless of cached status
`goalsLists/goalsList*`	`List<GoalsList>`	(Many) Specify which goals should run always if present in build regardless of cached status

plugin

No description.

Attribute	Type	Description
`groupId`	`String`	No description.
`artifactId`	`String`	No description.

execution

No description.

Attribute	Type	Description
`groupId`	`String`	No description.
`artifactId`	`String`	No description.

Element	Type	Description
`execIds/execId*`	`List<String>`	(Many) Executions ids list with plugin identifier

goalsList

No description.

Attribute	Type	Description
`groupId`	`String`	No description.
`artifactId`	`String`	No description.

Element	Type	Description
`goals/goal*`	`List<String>`	(Many) Goals identification

ignoreMissing

No description.

Element	Type	Description
`plugins/plugin*`	`List<PluginSet>`	(Many) Specify which executions should run always if present in build regardless of cached status
`executions/execution*`	`List<ExecutionIdsList>`	(Many) Specify which executions should run always if present in build regardless of cached status
`goalsLists/goalsList*`	`List<GoalsList>`	(Many) Specify which goals should run always if present in build regardless of cached status

reconcile

No description.

Attribute	Type	Description
`logAllProperties`	`boolean`	Controls if all plugin properties to be logged (true is default). All the properties logged with respect to children: * logAll on plugin level overrides global value * true: logged all if no blacklists (<nolog/>) and whitelists (<log/>) specified on plugin level * false: logged only tracked and included by whitelists (<log/>) on plugin level <log/> Default value is: `true` .

Element	Type	Description
`plugins/plugin*`	`List<GoalReconciliation>`	(Many) Reconciliation rules for plugin properties which might be affected by command line flags, etc

plugin

No description.

Attribute	Type	Description
`goal`	`String`	No description.
`groupId`	`String`	No description.
`artifactId`	`String`	No description.

Element	Type	Description
`reconciles/reconcile*`	`List<TrackedProperty>`	(Many) No description.
`logs/log*`	`List<PropertyName>`	(Many) Specify property which should be logged to build metadata for exploration
`nologs/nolog*`	`List<PropertyName>`	(Many) Specify property which should not be logged
`logAll`	`boolean`	Controls if all plugin properties to be logged (true is default). All the properties logged with respect to log/nolog children: * true: logged all if no blacklists (<nolog/>) and whitelists (<log/>) specified on plugin level * false: logged only tracked and included by whitelists (<log/>) on plugin level Default value is: `true` .

reconcile

No description.

Element Content: No description.

Attribute	Type	Description
`propertyName`	`String`	No description.
`skipValue`	`String`	No description.
`defaultValue`	`String`	No description.

log

No description.

Element Content: No description.

Attribute	Type	Description
`propertyName`	`String`	No description.

nolog

No description.

Element Content: No description.

Attribute	Type	Description
`propertyName`	`String`	No description.