This is an automated email from the ASF dual-hosted git repository.
maxnovikov pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/maven-build-cache-extension.git
The following commit(s) were added to refs/heads/master by this push:
new df45256 documentation fixes and updates (#460)
df45256 is described below
commit df45256108ef848657c2dde02295183f8faa058b
Author: Alex Ashitkin <[email protected]>
AuthorDate: Sun Mar 1 12:36:02 2026 -0500
documentation fixes and updates (#460)
---
src/site/markdown/concepts.md | 20 +--
src/site/markdown/how-to.md | 189 +++++++++++++-----------
src/site/markdown/index.md.vm | 8 +-
src/site/markdown/parameters.md | 160 ++++++++++++++++----
src/site/markdown/performance.md | 55 +++++--
src/site/markdown/remote-cache.md | 20 ++-
src/site/markdown/usage.md | 11 +-
src/site/resources/maven-build-cache-config.xml | 2 +
8 files changed, 313 insertions(+), 152 deletions(-)
diff --git a/src/site/markdown/concepts.md b/src/site/markdown/concepts.md
index 948d434..40a765c 100644
--- a/src/site/markdown/concepts.md
+++ b/src/site/markdown/concepts.md
@@ -33,10 +33,12 @@ project without building and installing dependencies from
the larger project.
### Cache concepts
-The build cache calculates a key from module inputs, stores outputs in the
cache, and transparently restores them later to the standard Maven core. The
cache associates each project state with a unique key
+The build cache calculates a key from module inputs, stores outputs in the
cache, and transparently restores them later
+to the standard Maven core. The cache associates each project state with a
unique key
and restores it in subsequent builds. It analyzes source code, project model,
plugins, and their parameters. Projects with the same key are up-to-date (not
changed) and can be restored from
-the cache. Projects that prodiuce different keys are out-of-date (changed),
and the cache fully rebuilds them. In the latter
+the cache. Projects that produce different keys are out-of-date (changed), and
the cache fully rebuilds them. In the
+latter
case, the cache does not make any
interventions in the build execution logic and delegates build work to the
standard maven Maven core. This approach
ensures that
@@ -46,9 +48,9 @@ of [project object
model](https://maven.apache.org/pom.html#What_is_the_POM) and
a configuration file. Source code content fingerprinting is digest based,
which is more reliable than
the file timestamps used in tools like Make or Apache Ant. Cache outputs can
be shared using a remote cache.
Deterministic inputs calculation allows distributed and parallel builds
running in heterogeneous environments (like a
-cloud of build agents) efficiently reuse cached build artifacts as soon as
they are published. Therefore, incremental
-The build cache is particularly useful for large Maven
-projects that have a significant number of small modules. Remote caching,
combined with relocatable inputs
+cloud of build agents) to efficiently reuse cached build artifacts as soon as
they are published.
+The build cache is particularly useful for large Maven projects that have a
significant number of small modules. Remote
+caching, combined with relocatable inputs
identification, effectively enables the "change once - build once" approach
across all environments.
### Maven insights
@@ -93,10 +95,10 @@ configuration.
Though strict, comprehensive cache rules aiming for 100% coverage of all
parameters and files might be tempting, it is
rarely the optimal decision. When applied to real projects, perfect
correctness could lead to prevailing hit misses and
-render caching useless. Configuring sufficient (good enough) correctness might
yield the best outcomes. Incremental
-Maven
-provides flexible and transparent control over caching policy and allows
achieving desired results - maximizes usability
-or maximize equivalency between pre-cached candidates and requested builds.
+render caching useless. Configuring sufficient (good enough) correctness might
yield the best outcomes. The build cache
+provides flexible and transparent control over caching policy and allows
achieving desired results — maximizing
+usability
+or maximizing equivalency between pre-cached candidates and requested builds.
## Usage
diff --git a/src/site/markdown/how-to.md b/src/site/markdown/how-to.md
index ce7fa6d..356283d 100644
--- a/src/site/markdown/how-to.md
+++ b/src/site/markdown/how-to.md
@@ -22,8 +22,6 @@ understand how it works, and figure out an optimal config
### Minimal config
-Minimal config
-
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.2.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -31,6 +29,7 @@ Minimal config
<configuration>
<enabled>true</enabled>
+ <!-- XX is the default and fastest algorithm. See performance.html for
all available algorithms. -->
<hashAlgorithm>XX</hashAlgorithm>
</configuration>
@@ -47,13 +46,14 @@ Minimal config
Just add `<remote>` section under `<configuration>`
```xml
- <configuration>
- <enabled>true</enabled>
- <hashAlgorithm>XX</hashAlgorithm>
- <remote>
- <url>https://yourserver:port</url>
- </remote>
- </configuration>
+
+<configuration>
+ <enabled>true</enabled>
+ <hashAlgorithm>XX</hashAlgorithm>
+ <remote>
+ <url>https://yourserver:port</url>
+ </remote>
+</configuration>
```
### Adding more file types to input
@@ -61,29 +61,33 @@ Just add `<remote>` section under `<configuration>`
Add all the project-specific source code files in `<glob>`. Scala, in this
case:
```xml
- <input>
- <global>
- <glob>{*.java,*.xml,*.properties,*.scala}</glob>
- </global>
- </input>
+
+<input>
+ <global>
+ <glob>{*.java,*.xml,*.properties,*.scala}</glob>
+ </global>
+</input>
```
### Adding source directory for bespoke project layouts
-In most cases, the build-cache extension automatically recognizes directories
by introspecting the build. When it is not enough, adding additional
directories with `<include>` is possible. Also, you can filter out undesirable
dirs and files by using exclude tag.
+In most cases, the build-cache extension automatically recognizes directories
by introspecting the build. When it is not
+enough, adding additional directories with `<include>` is possible. Also, you
can filter out undesirable dirs and files
+by using exclude tag.
```xml
- <input>
- <global>
- <glob>{*.java,*.xml,*.properties,*.scala}</glob>
- <includes>
- <include>importantdir/</include>
- </includes>
- <excludes>
- <exclude>tempfile.out</exclude>
- </excludes>
- </global>
- </input>
+
+<input>
+ <global>
+ <glob>{*.java,*.xml,*.properties,*.scala}</glob>
+ <includes>
+ <include>importantdir/</include>
+ </includes>
+ <excludes>
+ <exclude>tempfile.out</exclude>
+ </excludes>
+ </global>
+</input>
```
### Plugin property is environment-specific and yields different cache keys in
different environments
@@ -91,45 +95,49 @@ In most cases, the build-cache extension automatically
recognizes directories by
Consider to exclude env specific properties:
```xml
- <input>
- <global>
- ...
- </global>
- <plugins>
- <plugin artifactId="maven-surefire-plugin">
- <effectivePom>
- <excludeProperties>
- <excludeProperty>argLine</excludeProperty>
- </excludeProperties>
- </effectivePom>
- </plugin>
- </plugins>
- </input>
+
+<input>
+ <global>
+ ...
+ </global>
+ <plugins>
+ <plugin artifactId="maven-surefire-plugin">
+ <effectivePom>
+ <excludeProperties>
+ <excludeProperty>argLine</excludeProperty>
+ </excludeProperties>
+ </effectivePom>
+ </plugin>
+ </plugins>
+</input>
```
-Implications - builds with different `argLine` will have an identical key.
Validate that it is acceptable in terms of artifact equivalency.
+Implications - builds with different `argLine` will have an identical key.
Validate that it is acceptable in terms of
+artifact equivalency.
### Plugin property points to a directory where only a subset of files is
relevant
-If the plugin configuration property points to `somedir`, it will be scanned
with the default glob. You can tweak it with custom
+If the plugin configuration property points to `somedir`, it will be scanned
with the default glob. You can tweak it
+with custom
processing rule
```xml
- <input>
- <global>
- ...
- </global>
- <plugins>
- <plugin artifactId="protoc-maven-plugin">
- <dirScan mode="auto">
-
<!--<protoBaseDirectory>${basedir}/..</protoBaseDirectory>-->
- <tagScanConfigs>
- <tagScanConfig tagName="protoBaseDirectory"
recursive="false" glob="{*.proto}"/>
- </tagScanConfigs>
- </dirScan>
- </plugin>
- </plugins>
- </input>
+
+<input>
+ <global>
+ ...
+ </global>
+ <plugins>
+ <plugin artifactId="protoc-maven-plugin">
+ <dirScan mode="auto">
+ <!--<protoBaseDirectory>${basedir}/..</protoBaseDirectory>-->
+ <tagScanConfigs>
+ <tagScanConfig tagName="protoBaseDirectory"
recursive="false" glob="{*.proto}"/>
+ </tagScanConfigs>
+ </dirScan>
+ </plugin>
+ </plugins>
+</input>
```
### Local repository is not updated because the `install` phase is cached
@@ -137,33 +145,35 @@ processing rule
Add `executionControl/runAlways` section:
```xml
- <executionControl>
- <runAlways>
- <plugins>
- <plugin artifactId="maven-failsafe-plugin"/>
- </plugins>
- <executions>
- <execution artifactId="maven-dependency-plugin">
- <execIds>
- <execId>unpack-autoupdate</execId>
- </execIds>
- </execution>
- </executions>
- <goalsLists>
- <goalsList artifactId="maven-install-plugin">
- <goals>
- <goal>install</goal>
- </goals>
- </goalsList>
- </goalsLists>
- </runAlways>
- </executionControl>
+
+<executionControl>
+ <runAlways>
+ <plugins>
+ <plugin artifactId="maven-failsafe-plugin"/>
+ </plugins>
+ <executions>
+ <execution artifactId="maven-dependency-plugin">
+ <execIds>
+ <execId>unpack-autoupdate</execId>
+ </execIds>
+ </execution>
+ </executions>
+ <goalsLists>
+ <goalsList artifactId="maven-install-plugin">
+ <goals>
+ <goal>install</goal>
+ </goals>
+ </goalsList>
+ </goalsLists>
+ </runAlways>
+</executionControl>
```
### I occasionally cached build with `-DskipTests=true`, and tests do not run
now
If you add command line flags to your build, they do not participate in
effective pom - Maven defers the final value
-resolution to plugin runtime. To invalidate the build if the filed value is
different in runtime, add a reconciliation section
+resolution to plugin runtime. To invalidate the build if the filed value is
different in runtime, add a reconciliation
+section
to `executionControl`:
```xml
@@ -193,7 +203,10 @@ to `executionControl`:
</cache>
```
-Please notice the `skipValue` attribute. It captures the value that makes the
plugin skip execution. Think of `skipProperty` as follows: if the build started
with `-DskipTests=true`, restoring results from a build with completed tests is
safe because the local run does not require completed tests. The same logic
applies to any other plugin, not just Surefire.
+Please notice the `skipValue` attribute. It captures the value that makes the
plugin skip execution. Think of
+`skipProperty` as follows: if the build started with `-DskipTests=true`,
restoring results from a build with completed
+tests is safe because the local run does not require completed tests. The same
logic applies to any other plugin, not
+just Surefire.
### How to renormalize line endings in working copy after committing
.gitattributes (git 2.16+)
@@ -212,7 +225,8 @@ git reset --hard
### I want to cache the interim build and override it later with the final
version
-Solution: set `-Dmaven.build.cache.remote.save.final=true` to nodes that
produce final builds. Such builds will not be overridden
+Solution: set `-Dmaven.build.cache.remote.save.final=true` to nodes that
produce final builds. Such builds will not be
+overridden
and eventually will replace all interim builds
### I want to disable dependencies checksum calculation of one plugin
@@ -220,17 +234,19 @@ and eventually will replace all interim builds
Set attribute `excludeDependencies` to `true` in `input/plugins/plugin`
section:
```xml
- <input>
- <plugins>
+
+<input>
+ <plugins>
<plugin artifactId="maven-surefire-plugin" excludeDependencies="true">
</plugin>
- </plugins>
- </input>
+ </plugins>
+</input>
```
### I want to disable caching of compile-only builds
-By default, the cache extension saves build outputs when running compile-only
phases (like `mvn compile` or `mvn test-compile`).
+By default, the cache extension saves build outputs when running compile-only
phases (like `mvn compile` or
+`mvn test-compile`).
This allows subsequent builds to restore compiled classes without
recompilation. To disable this behavior and only cache
builds that reach the package phase or later:
@@ -239,6 +255,7 @@ mvn compile -Dmaven.build.cache.cacheCompile=false
```
This is useful when:
+
* You want to ensure cache entries always contain packaged artifacts (JARs,
WARs, etc.)
* Your workflow relies on artifacts being available in the local repository
* You prefer the traditional behavior where only complete builds are cached
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index f0fb322..d89ebbd 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -18,7 +18,7 @@
Getting Started
---------------
-**The build-cache extension will be activated only when using Apache Maven
from 3.9.x.**
+**The build-cache extension requires Apache Maven 3.9.0 or later (including
Maven 4).**
To onboard the build-cache extension you need to complete several steps:
@@ -87,10 +87,12 @@ See [Remote cache setup](remote-cache.html) for a detailed
description of the re
## See also
-* [Usage](usage.html) - shared cache setup procedure
+* [Usage](usage.html) - usage and activation details
* [Remote cache setup](remote-cache.html) - shared cache setup procedure
* [How-To](how-to.html) - cookbook for typical scenarios
* [Performance](performance.html) - performance tuning
* [Cache Parameters](parameters.html) - description of supported parameters
* [Sample config file](maven-build-cache-config.xml)
-* [Concepts](concepts.html) - getting starting with cache and usage manual
+* [Concepts](concepts.html) - getting started with cache concepts
+
+> **Maven 4 note:** The extension is compatible with Maven 4.x. No additional
configuration is required.
diff --git a/src/site/markdown/parameters.md b/src/site/markdown/parameters.md
index c03886a..a4f985d 100644
--- a/src/site/markdown/parameters.md
+++ b/src/site/markdown/parameters.md
@@ -21,25 +21,26 @@ This document contains various configuration parameters
supported by the cache e
### Command line flags
-| Parameter | Description
| Usage Scenario
|
-|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
-| `-Dmaven.build.cache.configPath=path to file` | Location of
cache configuration file
| Cache config is not in default
location |
-| `-Dmaven.build.cache.enabled=(true/false)` | Cache and
associated features disabled/enabled
| To remove noise from logs
when the remote cache is not available |
-| `-Dmaven.build.cache.remote.enabled=(true/false)` | Checks and
downloads artifacts from the remote cache (overrides <remote
enabled=("true"/"false")>) | To control
remote cache access by node, if, say, some nodes lack reliable access |
-| `-Dmaven.build.cache.remote.save.enabled=(true/false)` | Remote cache
save allowed or not
| To designate nodes which allowed
to push in remote shared cache |
-| `-Dmaven.build.cache.remote.save.final=(true/false)` | Prohibit to
override remote cache
| Prevents cache records from
being overridden by subsequent builds |
-| `-Dmaven.build.cache.remote.url=` | Url of the
remote cache (overrides <remote><url></url></remote>)
| To override url of remote
cache from command line |
-| `-Dmaven.build.cache.remote.server.id=` | Id of the
remote cache server (overrides <remote id=""></remote>)
| To override id of remote
cache server from command line |
-| `-Dmaven.build.cache.failFast=(true/false)` | Fail on the
first module which cannot be restored from cache
| Remote cache
setup/tuning/troubleshooting |
-| `-Dmaven.build.cache.baselineUrl=<http url>` | Location of
baseline build for comparison
| Remote cache
setup/tuning/troubleshooting |
-| `-Dmaven.build.cache.lazyRestore=(true/false)` | Restore
artifacts from remote cache lazily
| Performance optimization
|
-| `-Dmaven.build.cache.restoreGeneratedSources=(true/false)` | Restore
generated sources and directly attached files in the corresponding project
directories. (default is true) | Performance
optimization |
-| `-Dmaven.build.cache.restoreOnDiskArtifacts=(true/false)` | Restore
generated artifacts in the project build directory. (default is true)
| Performance optimization
|
-| `-Dmaven.build.cache.alwaysRunPlugins=<list of plugins>` | Comma separated
list of plugins to always run regardless of cache state. An example:
`maven-deploy-plugin:*,maven-install-plugin:install` | Remote cache
setup/tuning/troubleshooting |
-| `-Dmaven.build.cache.skipCache=(true/false)` | Skip looking up
artifacts in caches. Does not affect writing artifacts to caches, disables only
reading when set to `true` | May be used to trigger a forced
rebuild when matching artifacts do exist in caches |
-| `-Dmaven.build.cache.skipSave=(true/false)` | Skip writing build
result in caches. Does not affect reading from the cache. |
Configuring MR builds to benefits from the cache, but restricting writes to the
`master` branch |
-| `-Dmaven.build.cache.mandatoryClean=(true/false)` | Enable or
disable the necessity to execute the `clean` phase in order to store the build
result in cache | Reducing the risk to save
"wrong" files in cache in a local dev environnement |
-| `-Dmaven.build.cache.cacheCompile=(true/false)` | Cache compile
phase outputs (classes, test-classes, generated sources). When enabled
(default), compile-only builds create cache entries that can be restored by
subsequent builds. When disabled, caching only occurs during package phase or
later. | Performance optimization for incremental builds
|
+| Parameter | Description
| Usage
Scenario
|
+|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| `-Dmaven.build.cache.configPath=path to file` | Location of
cache configuration file
|
Cache config is not in default location
|
+| `-Dmaven.build.cache.location=<path>` | Override the
local cache repository directory (default: `build-cache` directory sibling to
the local Maven repository)
|
Store the local cache on a faster disk or a shared network path
|
+| `-Dmaven.build.cache.enabled=(true/false)` | Cache and
associated features disabled/enabled
|
To remove noise from logs when the remote cache is not available
|
+| `-Dmaven.build.cache.remote.enabled=(true/false)` | Checks and
downloads artifacts from the remote cache (overrides <remote
enabled=("true"/"false")>)
| To control remote cache access by node, if, say, some nodes
lack reliable access |
+| `-Dmaven.build.cache.remote.save.enabled=(true/false)` | Remote cache
save allowed or not
| To
designate nodes which allowed to push in remote shared cache
|
+| `-Dmaven.build.cache.remote.save.final=(true/false)` | Prohibit to
override remote cache
|
Prevents cache records from being overridden by subsequent builds
|
+| `-Dmaven.build.cache.remote.url=` | Url of the
remote cache (overrides <remote><url></url></remote>)
| To
override url of remote cache from command line
|
+| `-Dmaven.build.cache.remote.server.id=` | Id of the
remote cache server (overrides <remote id=""></remote>)
|
To override id of remote cache server from command line
|
+| `-Dmaven.build.cache.failFast=(true/false)` | Fail on the
first module which cannot be restored from cache
|
Remote cache setup/tuning/troubleshooting
|
+| `-Dmaven.build.cache.baselineUrl=<http url>` | Location of
baseline build for comparison
|
Remote cache setup/tuning/troubleshooting
|
+| `-Dmaven.build.cache.lazyRestore=(true/false)` | Restore
artifacts from remote cache lazily
|
Performance optimization
|
+| `-Dmaven.build.cache.restoreGeneratedSources=(true/false)` | Restore
generated sources and directly attached files in the corresponding project
directories. (default is true)
| Performance optimization
|
+| `-Dmaven.build.cache.restoreOnDiskArtifacts=(true/false)` | Restore
generated artifacts in the project build directory. (default is true)
|
Performance optimization
|
+| `-Dmaven.build.cache.alwaysRunPlugins=<list of plugins>` | Comma separated
list of plugins to always run regardless of cache state. An example:
`maven-deploy-plugin:*,maven-install-plugin:install`
| Remote cache setup/tuning/troubleshooting
|
+| `-Dmaven.build.cache.skipCache=(true/false)` | Skip looking up
artifacts in caches. Does not affect writing artifacts to caches, disables only
reading when set to `true`
| May be
used to trigger a forced rebuild when matching artifacts do exist in caches
|
+| `-Dmaven.build.cache.skipSave=(true/false)` | Skip writing
build result in caches. Does not affect reading from the cache.
|
Configuring MR builds to benefits from the cache, but restricting writes to the
`master` branch |
+| `-Dmaven.build.cache.mandatoryClean=(true/false)` | Enable or
disable the necessity to execute the `clean` phase in order to store the build
result in cache. Default: `false`
|
Reducing the risk to save "wrong" files in cache in a local dev environment
|
+| `-Dmaven.build.cache.cacheCompile=(true/false)` | Cache compile
phase outputs (classes, test-classes, generated sources). When enabled
(default), compile-only builds create cache entries that can be restored by
subsequent builds. When disabled, caching only occurs during package phase or
later. | Performance optimization for incremental builds
|
### Project-level properties
@@ -56,13 +57,116 @@ project properties:
</pom>
```
-| Parameter | Description
[...]
-|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| `maven.build.cache.input.glob` | Project specific <a
href="build-cache-config.html#global">glob</a> to select sources. Overrides the
global glob.
[...]
-| `maven.build.cache.input` | Additional <a
href="build-cache-config.html#include">inputs</a><br/><br/>Example
:<br/>```<maven.build.cache.input.1>src/main/scala<maven.build.cache.input.1>```<br/>```<maven.build.cache.input.2>assembly-conf<maven.build.cache.input.2>```
[...]
-| `maven.build.cache.exclude.xxx` | Additional <a
href="build-cache-config.html#class_exclude">exclusion</a>. <br/><br/>Example
:<br/>```<maven.build.cache.exclude.value.1>src/main/java/package-info.java<maven.build.cache.exclude.value.1>```<br/>```<maven.build.cache.exclude.value.2>src/main/resources<maven.build.cache.exclude.value.2>```<br/>```<maven.build.cache.exclude.glob.2>*.md<maven.build.cache.exclude.glob/2>```<br/>Produce
two project exclusions : <br/>```<exclude> [...]
-| `maven.build.cache.processPlugins` | Introspect plugins to find
inputs or not. The default value is true.
[...]
-| `maven.build.cache.skipCache` | Skip looking up artifacts for
a particular project in caches. The default value is false.
[...]
-| `maven.build.cache.restoreGeneratedSources` | Restore generated sources and
directly attached files in the corresponding project directories. The default
value is true.
[...]
-| `maven.build.cache.restoreOnDiskArtifacts` | Restore generated artifacts
in the project build directory. The default value is true.
[...]
+| Parameter | Description
[...]
+|---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| `maven.build.cache.input.glob` | Project specific <a
href="build-cache-config.html#global">glob</a> to select sources. Overrides the
global glob.
[...]
+| `maven.build.cache.input` | Additional <a
href="build-cache-config.html#include">inputs</a><br/><br/>Example
:<br/>```<maven.build.cache.input.1>src/main/scala<maven.build.cache.input.1>```<br/>```<maven.build.cache.input.2>assembly-conf<maven.build.cache.input.2>```
[...]
+| `maven.build.cache.exclude.xxx` | Additional <a
href="build-cache-config.html#class_exclude">exclusion</a>. <br/><br/>Example
:<br/>```<maven.build.cache.exclude.value.1>src/main/java/package-info.java<maven.build.cache.exclude.value.1>```<br/>```<maven.build.cache.exclude.value.2>src/main/resources<maven.build.cache.exclude.value.2>```<br/>```<maven.build.cache.exclude.glob.2>*.md<maven.build.cache.exclude.glob/2>```<br/>Produce
two project exclusions : <br/>```<exclude>s [...]
+| `maven.build.cache.processPlugins` | Introspect plugins to find
inputs or not. The default value is true.
[...]
+| `maven.build.cache.skipCache` | Skip looking up artifacts for
a particular project in caches. The default value is false.
[...]
+| `maven.build.cache.restoreGeneratedSources` | Restore generated sources and
directly attached files in the corresponding project directories. The default
value is true.
[...]
+| `maven.build.cache.restoreOnDiskArtifacts` | Restore generated artifacts in
the project build directory. The default value is true.
[...]
+### XML configuration reference
+
+The following elements are supported in `maven-build-cache-config.xml` but
have no command-line equivalent.
+
+#### `<local>` — local cache storage options
+
+```xml
+
+<configuration>
+ <local>
+ <maxBuildsCached>3</maxBuildsCached>
+ <location>/path/to/local-cache</location>
+ </local>
+</configuration>
+```
+
+| Element | Default
| Description
|
+|-------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| `maxBuildsCached` | `3`
| Maximum number of cached build records retained per project.
|
+| `location` | `build-cache` dir sibling to the local Maven repository
| Custom path for the local cache repository. Overridable via
`-Dmaven.build.cache.location`. |
+
+#### `<remote>` — transport and identity attributes
+
+```xml
+
+<configuration>
+ <remote enabled="true" id="my-cache" transport="resolver">
+ <url>http://your-buildcache-url</url>
+ </remote>
+</configuration>
+```
+
+| Attribute | Default | Description
|
+|----------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| `id` | `cache` | Matches a `<server>` entry in `settings.xml`
for authentication. Overridable via `-Dmaven.build.cache.remote.server.id`.
|
+| `transport` | `resolver` | Transport layer. Currently only `resolver`
(Maven Resolver / Aether) is supported.
|
+| `saveToRemote` | `false` | Save build outputs to the remote cache.
Recommended to enable on CI agents only. Overridable via
`-Dmaven.build.cache.remote.save.enabled`. |
+
+#### `<attachedOutputs>` — extra output directories and permissions
+
+```xml
+
+<configuration>
+ <attachedOutputs preservePermissions="true">
+ <dirNames>
+ <dirName>generated-sources/apt</dirName>
+ </dirNames>
+ </attachedOutputs>
+</configuration>
+```
+
+| Element/Attribute | Default | Description
|
+|-----------------------|---------|----------------------------------------------------------------------------------------------------------|
+| `preservePermissions` | `true` | Preserve Unix file-system permissions when
restoring artifacts from cache. Requires a POSIX file system. |
+| `dirNames/dirName` | — | Additional output directories to include
in cached artifacts beyond standard Maven output directories. |
+
+#### `<projectVersioning>` — version handling in cached artifacts
+
+```xml
+
+<configuration>
+ <projectVersioning adjustMetaInf="true"
calculateProjectVersionChecksum="false"/>
+</configuration>
+```
+
+| Attribute | Default | Description
|
+|-----------------------------------|---------|-----------------------------------------------------------------------------------------------------------|
+| `adjustMetaInf` | `false` | Auto-correct
`Implementation-Version` in `MANIFEST.MF` when restoring artifacts. Adds
repacking overhead. |
+| `calculateProjectVersionChecksum` | `false` | Include the project version
string in the cache key, making the cache version-aware. |
+
+#### `<debugs>` — diagnostic metadata in build records
+
+```xml
+
+<configuration>
+ <debugs>
+ <debug>FileHash</debug>
+ <debug>EffectivePom</debug>
+ </debugs>
+</configuration>
+```
+
+| Value | Description
|
+|----------------|------------------------------------------------------------------------------------------------------------|
+| `FileHash` | Records per-file hashes in `buildinfo.xml`. Useful for
diagnosing cache misses. |
+| `EffectivePom` | Embeds the full effective POM XML in `buildinfo.xml`.
Useful for diagnosing effective-pom hash mismatches. |
+
+#### `<executionControl>/<ignoreMissing>` — gracefully skip optional plugins
+
+```xml
+
+<executionControl>
+ <ignoreMissing>
+ <plugins>
+ <plugin artifactId="some-optional-plugin"/>
+ </plugins>
+ </ignoreMissing>
+</executionControl>
+```
+
+Plugins listed under `ignoreMissing` are skipped gracefully when they are not
found in the cache, instead of
+causing a cache miss failure. Useful for optional plugins that run only in
specific environments (e.g.,
+CI-only reporting plugins).
diff --git a/src/site/markdown/performance.md b/src/site/markdown/performance.md
index ffd9ce4..af464f8 100644
--- a/src/site/markdown/performance.md
+++ b/src/site/markdown/performance.md
@@ -19,36 +19,51 @@
### General notes
-Cache tuning could significantly reduce resource consumption and build
execution time, but that is not guaranteed. Performance-tuning hints might not
considerably affect the build time depending on a usage pattern. As usual with
performance tuning, measure results in relevant scenarios to validate results
and weigh the pros and cons.
+Cache tuning could significantly reduce resource consumption and build
execution time, but that is not guaranteed.
+Performance-tuning hints might not considerably affect the build time
depending on a usage pattern. As usual with
+performance tuning, measure results in relevant scenarios to validate results
and weigh the pros and cons.
### Hash algorithm selection
-By default, the cache uses the [XX](https://cyan4973.github.io/xxHash/)
algorithm, which is a very fast hash algorithm and should be enough for most
use cases.
-In projects with a large codebase, the performance of hash algorithms becomes
more critical, and other algorithms like
-XXMM (XX with memory-mapped files) could provide better performance, depending
on the environment.
+By default, the cache uses the [XX](https://cyan4973.github.io/xxHash/)
algorithm, which is a very fast
+non-cryptographic hash algorithm and is sufficient for most use cases. All
supported values for `<hashAlgorithm>` are:
+
+| Identifier | Description
|
+|------------|--------------------------------------------------------------------------------------------------|
+| `XX` | **Default.** xxHash, non-cryptographic, fastest.
|
+| `XXMM` | xxHash with memory-mapped file I/O. Faster for large codebases;
requires a JVM flag on JDK ≥ 17. |
+| `METRO` | Metro hash, standard I/O.
|
+| `METRO+MM` | Metro hash with memory-mapped file I/O. Requires a JVM flag on
JDK ≥ 17. |
+| `SHA-1` | Cryptographic. Not recommended unless integrity guarantees are
required. |
+| `SHA-256` | Cryptographic.
|
+| `SHA-384` | Cryptographic.
|
+| `SHA-512` | Cryptographic, slowest.
|
```xml
+
<hashAlgorithm>XX</hashAlgorithm>
```
-Also note that the usage of the XXMM or METRO+MM algorithms require the
creation of a file `.mvn/jvm.config` in the
-top directory with the following line to run successfully on JDK >= 17.
+The memory-mapped algorithms (`XXMM` and `METRO+MM`) require adding the
following line to `.mvn/jvm.config` in the
+project root to run correctly on JDK ≥ 17:
+
```
--add-opens java.base/sun.nio.ch=ALL-UNNAMED
```
-
### Filter out unnecessary artifacts
The price of uploading and downloading huge artifacts could be significant. In
many scenarios assembling WAR,
-EAR or ZIP archive locally is more efficient than writing to soring in cache
bundles. To filter out artifacts, add the configuration section:
+EAR or ZIP archive locally is more efficient than storing them in cache
bundles. To filter out artifacts, add the
+configuration section:
```xml
+
<cache>
<output>
<exclude>
<patterns>
- <pattern>.*\.zip</pattern>
+ <pattern>.*\.zip</pattern>
</patterns>
</exclude>
</output>
@@ -57,29 +72,37 @@ EAR or ZIP archive locally is more efficient than writing
to soring in cache bun
### Use a lazy restore
-By default, the cache tries to restore all artifacts for a project
preemptively. Lazy restore could give significant time by avoiding requesting
and downloading unnecessary artifacts from the cache.
+By default, the cache tries to restore all artifacts for a project
preemptively. Lazy restore could give significant
+time by avoiding requesting and downloading unnecessary artifacts from the
cache.
It is beneficial when small changes are a dominating build pattern. Use
command line flag:
```
--Dmaven.build.cache.lazyRestore=true";
+-Dmaven.build.cache.lazyRestore=true
```
-In cache corruption situations, the lazy cache cannot support fallback to
normal execution. It will fail instead. To heal the corrupted cache, manually
remove corrupted cache entries or force cache rewrite.
+In cache corruption situations, the lazy cache cannot support fallback to
normal execution. It will fail instead. To
+heal the corrupted cache, manually remove corrupted cache entries or force
cache rewrite.
### Disable project files restoration
-By default, cache supports the partial restoration of source code state from
cached generated sources (and potentially more,
-depending on configuration). It is helpful in a local environment but likely
unnecessary and adds overhead in continuous integration. To disable, add a
command line flag.
+By default, cache supports the partial restoration of source code state from
cached generated sources (and potentially
+more,
+depending on configuration). It is helpful in a local environment but likely
unnecessary and adds overhead in continuous
+integration. To disable, add a command line flag.
```
--Dmaven.build.cache.restoreGeneratedSources=false";
+-Dmaven.build.cache.restoreGeneratedSources=false
```
### Disable post-processing of archives(JARs, WARs, etc) META-INF
-The cache could be configured to auto-correct metadata (most notably
[MANIFEST.MF
`Implementation-Version`](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes)).
The correction requires copying and repacking archive entries and adds
overhead. If the metadata state is not relevant for the build, consider
disabling it (off by default):
+The cache could be configured to auto-correct metadata (most notably
[MANIFEST.MF
+`Implementation-Version`](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes)).
The
+correction requires copying and repacking archive entries and adds overhead.
If the metadata state is not relevant for
+the build, consider disabling it (off by default):
```xml
+
<cache>
<configuration>
...
diff --git a/src/site/markdown/remote-cache.md
b/src/site/markdown/remote-cache.md
index e31f014..6ac2ff7 100644
--- a/src/site/markdown/remote-cache.md
+++ b/src/site/markdown/remote-cache.md
@@ -138,8 +138,10 @@ low-level insights. See techniques to configure cache in
[How-To](how-to.md) and
in the section below. Also, it is possible to diff remote and local
`buildInfo.xml` files directly using any tool of
your preference.
-If you are using a webdav remote server (which is the most easiest to use to
create directories on a remote server), from Maven 3.9.1 and 4.0.0-alpha5,
support of webdav has been removed per default.
+If you are using a webdav remote server (which is the most easiest to use to
create directories on a remote server),
+from Maven 3.9.1 and 4.0.0-alpha5, support of webdav has been removed per
default.
You need to use the following extra configuration:
+
```bash
-Daether.connector.http.supportWebDav=true
OR
@@ -147,7 +149,9 @@ OR
```
Or configure your remote with the following configuration (`dav:url`)
+
```xml
+
<remote enabled="true">
<url>dav:http://your-buildcache-url</url>
</remote>
@@ -233,11 +237,15 @@ Filter out environment-specific properties from the
effective pom model:
<global>
...
</global>
- <plugin artifactId="maven-surefire-plugin">
- <effectivePom>
- <excludeProperty>argLine</excludeProperty>
- </effectivePom>
- </plugin>
+ <plugins>
+ <plugin artifactId="maven-surefire-plugin">
+ <effectivePom>
+ <excludeProperties>
+ <excludeProperty>argLine</excludeProperty>
+ </excludeProperties>
+ </effectivePom>
+ </plugin>
+ </plugins>
</input>
```
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 505dc46..6171f60 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -17,7 +17,9 @@
## Usage
-Once the extension is activated, the cache automatically kicks in on every
`package` or higher phase.
+Once the extension is activated, the cache kicks in automatically. By default,
compile-phase builds
+(`mvn compile`, `mvn test-compile`) are cached in addition to `package` and
later phases. Set
+`-Dmaven.build.cache.cacheCompile=false` to restrict caching to the `package`
phase and above.
## Subtree builds
@@ -51,9 +53,9 @@ Disable in config:
```xml
<cache>
- <configuration>
- <enabled>false</enabled>
- </configuration>
+ <configuration>
+ <enabled>false</enabled>
+ </configuration>
</cache>
```
@@ -64,6 +66,7 @@ On the command line:
```
When a configuration is disabled by default in the config, it can be enabled
via the command line with:
+
```
-Dmaven.build.cache.enabled=true
```
diff --git a/src/site/resources/maven-build-cache-config.xml
b/src/site/resources/maven-build-cache-config.xml
index 1fb0ab9..6103903 100644
--- a/src/site/resources/maven-build-cache-config.xml
+++ b/src/site/resources/maven-build-cache-config.xml
@@ -24,6 +24,8 @@
<configuration>
<enabled>true</enabled>
+ <!-- The default algorithm is XX (fastest, non-cryptographic). SHA-256
is used here for stronger
+ integrity guarantees suitable for a production template. See
performance.html for all options. -->
<hashAlgorithm>SHA-256</hashAlgorithm>
<validateXml>true</validateXml>
<remote enabled="true">
