This is an automated email from the ASF dual-hosted git repository. hboutemy pushed a commit to branch MNG-7129-maven-caching in repository https://gitbox.apache.org/repos/asf/maven.git
commit f8271b6056c1f8799bad049ef91a46ef2a483d13 Author: Hervé Boutemy <[email protected]> AuthorDate: Sun Dec 12 14:55:13 2021 +0100 reworked documentation links and title levels --- deploySite.sh | 2 +- pom.xml | 3 ++- src/site/apt/index.apt | 2 +- src/site/markdown/cache.md | 12 ++++----- src/site/markdown/getting-started.md | 4 +-- src/site/markdown/how-to.md | 2 +- src/site/markdown/parameters.md | 6 ++--- src/site/markdown/performance.md | 16 +++++------- src/site/markdown/remote-cache.md | 30 +++++++++++----------- .../{markdown => resources}/maven-cache-config.xml | 0 src/site/site.xml | 22 +++++++++++----- 11 files changed, 54 insertions(+), 45 deletions(-) diff --git a/deploySite.sh b/deploySite.sh index d7a5c5f..4a5ba75 100644 --- a/deploySite.sh +++ b/deploySite.sh @@ -19,5 +19,5 @@ # under the License. # -mvn -Preporting site site:stage "$@" +mvn -Preporting site site:stage -Danimal.sniffer.skip "$@" mvn scm-publish:publish-scm "$@" diff --git a/pom.xml b/pom.xml index e5711c8..0f5f0a6 100644 --- a/pom.xml +++ b/pom.xml @@ -37,6 +37,7 @@ under the License. <name>Apache Maven Build Cache Extension</name> <inceptionYear>2021</inceptionYear> + <url>https://maven.apache.org/ref/caching/</url> <properties> <maven.compiler.source>1.8</maven.compiler.source> @@ -72,7 +73,7 @@ under the License. <id>apache.website</id> <url>scm:svn:https://svn.apache.org/repos/asf/maven/website/components/${maven.site.path}</url> </site> - </distributionManagement> + </distributionManagement> <dependencies> <dependency> diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt index db29a8d..b2ebdf7 100644 --- a/src/site/apt/index.apt +++ b/src/site/apt/index.apt @@ -27,4 +27,4 @@ Maven Caching Maven Incremental Build and Cache (local and remote). - Read {{{./CACHE.html} more documentation}}. + Read {{{./cache.html} more documentation}}. diff --git a/src/site/markdown/cache.md b/src/site/markdown/cache.md index 46c3f69..16a23e1 100644 --- a/src/site/markdown/cache.md +++ b/src/site/markdown/cache.md @@ -117,12 +117,12 @@ Such scheme allows to validate cache correctness by reconciling outcomes of cach ## See also -* [Getting started](getting-started.md) - getting starting with cache and usage manual -* [Usage](usage.md) - shared cache setup procedure -* [Remote cache setup](remote-cache.md) - shared cache setup procedure -* [How-To](how-to.md) - cookbook for typical scenarios -* [Performance](performance.md) - performance tuning -* [Cache Parameters](parameters.md) - description of supported parameters +* [Getting started](getting-started.html) - getting starting with cache and usage manual +* [Usage](usage.html) - shared cache setup procedure +* [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-cache-config.xml) diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md index 56fd82f..d395b0f 100644 --- a/src/site/markdown/getting-started.md +++ b/src/site/markdown/getting-started.md @@ -28,8 +28,8 @@ To on-board incremental Maven you need to complete several steps: ```xml <extension> - <groupId>org.apache.maven.caching</groupId> - <artifactId>maven-caching-extension</artifactId> + <groupId>org.apache.maven.extensions</groupId> + <artifactId>maven-build-cache-extension</artifactId> <version>1.0.0-SNAPSHOT</version> </extension> ``` diff --git a/src/site/markdown/how-to.md b/src/site/markdown/how-to.md index 3394ef1..56b4832 100644 --- a/src/site/markdown/how-to.md +++ b/src/site/markdown/how-to.md @@ -15,7 +15,7 @@ limitations under the License. --> -### Overview +## Overview Cache configuration provides you additional control over incremental Maven behavior. Follow it step by step to understand how it works and figure out your optimal config diff --git a/src/site/markdown/parameters.md b/src/site/markdown/parameters.md index 476c046..8f3e3f7 100644 --- a/src/site/markdown/parameters.md +++ b/src/site/markdown/parameters.md @@ -15,11 +15,11 @@ limitations under the License. --> -# Overview +## Build Cache Parameters This documents contains various configuration parameters supported by cache engine -## Command line flags +### Command line flags | Parameter | Description | Usage Scenario | | ----------- | ----------- | ----------- | @@ -32,7 +32,7 @@ This documents contains various configuration parameters supported by cache engi | `-Dremote.cache.lazyRestore=(true/false)` | Restore artifacts from remote cache lazily | Performance optimization | | `-Dremote.cache.restoreGeneratedSources=(true/false)` | Do not restore generated sources and directly attached files | Performance optimization | -## Project level properties +### Project level properties Project level parameters allow overriding global parameters on project level Must be specified as project properties: diff --git a/src/site/markdown/performance.md b/src/site/markdown/performance.md index 03a8173..22b409d 100644 --- a/src/site/markdown/performance.md +++ b/src/site/markdown/performance.md @@ -15,18 +15,18 @@ limitations under the License. --> -# Performance Tuning +## Performance Tuning Various setup options which affect cache performance. -## General notes +### General notes Tuning of cache performance could reduce both resources consumption and build execution time but that is not guaranteed. In many scenarios build time of invalidated (changed) projects could be dominating in overall build time. Performance wins achieved by a faster cache engine might not correlate with final build times in straightforward way. As usual with performance, effect of performance optimizations should be carefully measured in relevant scenarios. -## Hash algorithm selection +### Hash algorithm selection By default, cache uses SHA-256 algorithm which is sufficiently fast and provides negligible probability of hash collisions. In projects with large codebase, performance of hash algorithms becomes more important and in such @@ -43,7 +43,7 @@ or <hashAlgorithm>XXMM</hashAlgorithm> ``` -## Filter out unnecessary/huge artifacts +### Filter out unnecessary/huge artifacts Price of uploading and downloading from cache of huge artifacts could be significant. In many scenarios assembling WAR, EAR or ZIP archive could be done more efficiently locally from cached JARs than storing bundles. In order to filter out @@ -59,7 +59,7 @@ artifacts add configuration section: </cache> ``` -## Use lazy restore +### Use lazy restore By default, cache tries to restore all artifacts for a project preemptively. Lazy restore could give a significant time and resources wins for remote cache by avoiding requesting and downloading unnecessary artifacts from cache. Use command @@ -72,7 +72,7 @@ line flag: Note: In case of cache corruption lazy cache cannot fallback to normal execution, it will fail instead. To heal the corrupted cache need to force rewrite of the cache or remove corrupted cache entries manually -## Disable project files restoration +### Disable project files restoration By default, cache support partial restore of source code state from cached generated sources (and potentially more, depending on configuration). This could be helpful in local environment, but likely unnecessary and adds overhead in @@ -82,7 +82,7 @@ continuous integration. To disable add command line flag -Dremote.cache.restoreGeneratedSources=false"; ``` -## Disable post-processing of archives(JARs, WARs, etc) META-INF +### Disable post-processing of archives(JARs, WARs, etc) META-INF Post-processing is disabled by default, but for some projects 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)) @@ -99,5 +99,3 @@ for the build (continuous integration, `verify` scenarios and similar) consider ... </cache> ``` - - diff --git a/src/site/markdown/remote-cache.md b/src/site/markdown/remote-cache.md index 74b0bdc..39bf151 100644 --- a/src/site/markdown/remote-cache.md +++ b/src/site/markdown/remote-cache.md @@ -15,13 +15,13 @@ limitations under the License. --> -# Overview +## Overview This document describes generic approach to remote cache setup. The process implies good knowledge of both Maven and the project. Due to Maven model limitation the process is semi-manual, but allows you to achieve sufficient control and transparency over caching logic. -## Before you start +### Before you start Before you start, please keep in mind basic principles: @@ -36,21 +36,21 @@ Before you start, please keep in mind basic principles: tests ensure that critical surefire parameters are tracked (`skipTests` and similar) in config. The same applies for all over plugins. -# Step-By-Step +## Step-By-Step -## Minimize number of moving parts +### Minimize number of moving parts * Run build with single threaded builder to make sure logs from different modules do not interfere * Use the same branch which no-one else commits to * Designate single agent/node for CI builds * Preferably use the same OS between CI and local machine -## Fork branch for cache setup purposes +### Fork branch for cache setup purposes Fork stable code branch for cache setup purposes as you will need source code which doesn't change over time of setup. Also, you likely will need to do code changes as long as you go. -## Setup http server to store artifacts +### Setup http server to store artifacts In order to share build results cache needs a shared storage. The simplest option is to set up a http server which supports http PUT/GET/HEAD operations will suffice (Nginx, Apache or similar). Add the url to config and @@ -73,13 +73,13 @@ Beside the http server, remote cache could be configured using any storage which by [Maven Wagon](https://maven.apache.org/wagon/). That includes a wide set of options, including SSH, FTP and many others. See Wagon documentation for a full list of options and other details. -## Build selection +### Build selection Build stored in cache ideally should be a build assembled in the most correct, comprehensive and complete way. Pull requests builds are good candidates to populate cache usually because this is there quality safeguards are applied normally. -## CI Build setup to seed shared cache +### CI Build setup to seed shared cache Allow writes in remote cache add jvm property to designated CI builds. @@ -90,7 +90,7 @@ Allow writes in remote cache add jvm property to designated CI builds. Run the build, review log and ensure that artifacts are uploaded to remote cache. Now, rerun build and ensure that it completes almost instantly because it is fully cached. -## Remote cache relocation to local builds +### Remote cache relocation to local builds As practice shows, developers often don't realize that builds they run in local and CI environments are different. So straightforward attempt to reuse remote cache in local build usually results in cache misses because of difference in @@ -127,15 +127,15 @@ Review `buildsdiff.xml` file and eliminate detected discrepancies. You can also low level insights. See techniques to configure cache in [How-To](how-to.md) and troubleshooting of typical issues in the section below. -# Common issues +## Common issues -## Issue 1: Local checkout is with different line endings +### Issue 1: Local checkout is with different line endings Solution: normalise line endings. Current implementation doesn't have built-in line endings normalization, it has to be done externally. In git it is recommended to use `.gitattributes` file to establish consistent line endings across all envs for file types specific to this project -## Issue 2: Effective poms mismatch because of plugins injection by profiles +### Issue 2: Effective poms mismatch because of plugins injection by profiles Different profiles between remote and local builds likely result in different text of effective poms. As effective pom contributes hash value to the key that could lead to cache misses. Solution: instead of adding/removing specific plugins @@ -191,7 +191,7 @@ Use: Hint: effective poms could be found in `buildinfo` files under `/build/projectsInputInfo/item[@type='pom']` xpath (`item type="pom"`). -## Issue 3: Effective pom mismatch because of environment specific properties +### Issue 3: Effective pom mismatch because of environment specific properties Potential reason: Sometimes it is not possible to avoid discrepancies in different environments - for example if plugin takes command line as parameter, it will be likely different on Win and linux. Such commands will appear in effective @@ -211,7 +211,7 @@ filter out such properties from effective pom: </input> ``` -## Issue 4: Unexpected or transient files in cache key calculation +### Issue 4: Unexpected or transient files in cache key calculation Potential reasons: plugins or tests emit temporary files (logs and similar) in non-standard locations. Solution: adjust global exclusions list to filter out the unexpected files: @@ -224,7 +224,7 @@ global exclusions list to filter out the unexpected files: see sample config for exact syntax -## Issue 5: Difference in tracked plugin properties +### Issue 5: Difference in tracked plugin properties Tracked property in config means it is critical for determining is build up to date or not. Discrepancies could happen for any plugin for a number of reasons. Example: local build is using java target 1.6, remote: 1.8. `buildsdiff.xml` diff --git a/src/site/markdown/maven-cache-config.xml b/src/site/resources/maven-cache-config.xml similarity index 100% rename from src/site/markdown/maven-cache-config.xml rename to src/site/resources/maven-cache-config.xml diff --git a/src/site/site.xml b/src/site/site.xml index aa24fb5..15f4f67 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -25,26 +25,36 @@ under the License. <edit>${project.scm.url}</edit> <body> + <breadcrumbs> + <item name="Ref" href="../" /> + <item name="Maven Build Cache Extension" href="./" /> + </breadcrumbs> + <menu name="Overview"> <item name="Introduction" href="index.html"/> <item name="JavaDocs" href="apidocs/index.html"/> <item name="Source Xref" href="xref/index.html"/> <!--item name="FAQ" href="faq.html"/--> - <item name="maven-cache-config.xml" href="cache-config.html"/> </menu> <menu name="Documentation"> - <item name="Overview" href="CACHE.html"/> - <item name="Howto" href="CACHE-HOWTO.html"/> - <item name="Parameters" href="CACHE-PARAMETERS.html"/> - <item name="Remote" href="CACHE-REMOTE.html"/> + <item name="Overview" href="cache.html"/> + <item name="Getting Started" href="getting-started.html"/> + <item name="Usage" href="usage.html"/> + <item name="Remote Cache Setup" href="remote-cache.html"/> + <item name="Howto" href="how-to.html"/> + <item name="Performance" href="performance.html"/> + <item name="Cache Parameters" href="parameters.html"/> + </menu> + + <menu name="Reference"> + <item name="maven-cache-config.xml" href="cache-config.html"/> </menu> <menu name="Cache Internals"> <item name="buildinfo.xml" href="cache-build.html"/> <item name="diff-*.xml" href="cache-diff.html"/> <item name="cache-report.xml" href="cache-report.html"/> - <!--item name="FAQ" href="faq.html"/--> </menu> <menu ref="parent"/>
