| <!--- |
| 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 |