blob: 5c44cbf70f5e0dabd976fbfdd2918872cbd2fe8f [file] [log] [blame]
<!---
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
Getting Started
---------------
To onboard the build-cache extension you need to complete several steps:
* Declare caching extension in your project (either in `pom.xml` or `.mvn/extensions.xml`)
* Add `maven-build-cache-config.xml` cache config in `.mvn/` (optional) to customize the default behavior
* Validate build results and iteratively adjust config to reflect project specifics properly
* Setup remote cache (optional)
#[[###]]# Declaring build cache extension
```xml
<extension>
<groupId>org.apache.maven.extensions</groupId>
<artifactId>maven-build-cache-extension</artifactId>
<version>${project.version}</version>
</extension>
```
either in `pom.xml`'s `<project>/<build>/<extensions>` or in `.mvn/extensions.xml`'s `<extensions>`. Using core
extension model (`.mvn/extensions.xml` file) is preferable as it allows better access to maven APIs and could allow
more sophisticated optimizations in the future.
#[[###]]# Adding build cache config
Copy template config [`maven-build-cache-config.xml`](maven-build-cache-config.xml)
to [`.mvn/`](https://maven.apache.org/configure.html) directory of your project.
To understand the caching machinery, review the config and read the comments. In a typical scenario, you need to:
* Exclude unstable, temporary files or environment-specific files
* Add critical plugins parameters to runtime reconciliation
* Configure precise source code file selectors. Though source code locations are discovered automatically from project
and
plugin configs, there might be edge cases.
* Configure remote cache (if using the remote cache)
#[[###]]# Adjusting build cache config
After configuring the extension, run a usual command, for example, `mvn package`, and verify the caching engine is
activated:
* Check log output - there should be the cache-related output or initialization error message:
```
[INFO] Loading cache configuration from <project dir>/.mvn/maven-build-cache-config.xml
```
* Navigate to your local repo directory - there should be a sibling directory `build-cache` next to the usual
local `repository`.
* Find `buildinfo.xml` in the cache repository for a typical module and review it. Ensure that
* Expected source code files are present in the build info
* Review all plugins used in the build and add their critical parameters to the reconciliation
Try to find the best working trade-off between fairness and cache efficiency. Adding unnecessary rules and
checks could reduce both performance and cache efficiency (hit rate).
#[[###]]# Adding caching CI and remote cache
To leverage the remote cache feature need to provide shared storage. Any technology supported
by [Maven Resolver](https://maven.apache.org/resolver/) will suffice. In the simplest form, it could be any HTTP web
server
supporting get/put operations. Working examples:
* Sonatype Nexus Repository (raw repository)
* Artifactory (generic repository)
* [Nginx OSS](http://nginx.org/en/) with fs module
See [Remote cache setup](remote-cache.html) for a detailed description of the remote cache setup