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

A

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.