This is an automated email from the ASF dual-hosted git repository. shuber pushed a commit to branch UNOMI-892-maven-cache in repository https://gitbox.apache.org/repos/asf/unomi.git
commit 9ddb94ada476777cc55a703c3be590955c717721 Author: Serge Huber <[email protected]> AuthorDate: Thu Oct 16 09:06:17 2025 +0200 UNOMI-892-maven-cache: Adopt Maven Build Cache, consolidate BUILDING into manual, update website docs - Enable Maven Build Cache (extensions.xml, maven-build-cache-config.xml); document usage, parameters, purge options; add official links - Update BUILDING to deprecate content and point to online manual and local Asciidoc source - Expand manual (manual/src/main/asciidoc/building-and-deploying.adoc): - Add Maven Build Cache section with detailed parameter differences and performance times (1m59s vs 3.176s) - Replace old site scripts with generate-manual.sh usage (publish/simulate), requirements, destinations - Align Maven requirement to 3.9.8 - Minor doc cleanups and consistency across build instructions --- .mvn/extensions.xml | 23 +++++ .mvn/maven-build-cache-config.xml | 59 ++++++++++++ BUILDING | 72 +------------- .../src/main/asciidoc/building-and-deploying.adoc | 107 ++++++++++++++++++++- 4 files changed, 192 insertions(+), 69 deletions(-) diff --git a/.mvn/extensions.xml b/.mvn/extensions.xml new file mode 100644 index 000000000..f9a3dfca9 --- /dev/null +++ b/.mvn/extensions.xml @@ -0,0 +1,23 @@ +<!-- - + 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. + --> +<extensions> + <extension> + <groupId>org.apache.maven.extensions</groupId> + <artifactId>maven-build-cache-extension</artifactId> + <version>1.2.0</version> + </extension> +</extensions> \ No newline at end of file diff --git a/.mvn/maven-build-cache-config.xml b/.mvn/maven-build-cache-config.xml new file mode 100644 index 000000000..1e0eb9902 --- /dev/null +++ b/.mvn/maven-build-cache-config.xml @@ -0,0 +1,59 @@ +<!-- - + 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. + --> +<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";> + <!-- + Template Maven build cache configuration + --> + <configuration> + <enabled>true</enabled> + <hashAlgorithm>SHA-256</hashAlgorithm> + <validateXml>true</validateXml> + <remote enabled="false"> + <url>http://host:port</url> + </remote> + <local> + <maxBuildsCached>3</maxBuildsCached> + </local> + <projectVersioning adjustMetaInf="true" /> + </configuration> + <input> + <global> + <!-- If not defined, default glob is "*" --> + <!--glob> {*.java,*.groovy,*.yaml,*.svcd,*.proto,*assembly.xml,assembly*.xml,*logback.xml,*.vm,*.ini,*.jks,*.properties,*.sh,*.bat} </glob--> + <includes> + <!-- By default, project sources and resources directories are included + (src/main/java and src/main/resources) --> + <!-- In this example, the goal is to include a wider range of src directories (like + src/main/assembly or src/main/groovy) --> + <include>src/</include> + </includes> + <excludes> + <!-- We don't want a static "hash" pom resolution (it would conflict the will to + adjust the version in the manifest), --> + <!-- we exclude this specific file (as it is already by default since it is not in + an include folder --> + <!-- The need to rebuild a project based on the pom is already computed with some + intelligence by the extension. --> + <exclude>pom.xml</exclude> + <!-- Also excluding everything located in this project specific folder --> + <exclude>src/main/javagen/**</exclude> + </excludes> + </global> + </input> +</cache> \ No newline at end of file diff --git a/BUILDING b/BUILDING index 4362d11a3..03ff90681 100644 --- a/BUILDING +++ b/BUILDING @@ -18,74 +18,10 @@ Building Apache Unomi ===================== -Initial Setup -------------- +This file has been deprecated to avoid duplication. Please use the online manual for up-to-date instructions: -1) Install J2SE 17 SDK (or later), which can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/index.html + Online manual (Building): https://unomi.apache.org/manual/latest/index.html#_building -2) Make sure that your JAVA_HOME environment variable is set to the newly installed - JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or - $JAVA_HOME$/bin (unix). +To propose edits to the build documentation, update the source Asciidoc here: -3) Install Maven 3.0.3 (or later), which can be downloaded from - http://maven.apache.org/download.html. Make sure that your PATH includes - the MVN_HOME/bin directory. - - -Building --------- - -1) Change to the top level directory of Apache Unomi source distribution. -2) Run - - $> mvn clean install - - This will compile Apache Unomi and run all of the tests in the - Apache Unomi source distribution. Alternatively, you can run - - $> mvn -P \!integration-tests clean install - - This will compile Apache Unomi without running the tests and takes less - time to build. - -3) The distributions will be available under "package/target" directory. - -Updating the website --------------------- - -We provide two scripts to generate the website and upload the modifications -to the live SVN repository. To generate the website and check if everything is in -place simply launch: - - ./generate-site.sh - -The generated site will then be in the target/site directory - -Once it is ready to be published to the live site, simply use the following -command: - - ./generate-site-and-upload.sh SVNusername SVNpassword - -Where the required username and password have the proper credentials for the SVN -Apache repository. - -JGitFlow --------- - -We now can use the [JGitFlow Maven plugin](http://jgitflow.bitbucket.org) to make it easier to work with feature, -hotfix and other types of branches. - -For example, to start a feature branch, simply use - - mvn jgitflow:feature-start - -This will prompt you for the feature name, and then create a feature branch and update -all the POMs to have a version that contains the feature name. This makes it then a lot -easier to integrate with continuous integration systems to generate builds for the -feature branch. - -Once the feature is completed you can use - - mvn jgitflow:feature-finish - -To merge the branch into master. + manual/src/main/asciidoc/building-and-deploying.adoc diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc index c91c86052..a38d4334b 100644 --- a/manual/src/main/asciidoc/building-and-deploying.adoc +++ b/manual/src/main/asciidoc/building-and-deploying.adoc @@ -23,7 +23,7 @@ JDK location, and that your PATH includes %JAVA_HOME%\bin (windows) or $JAVA_HOME$/bin (unix). -. Install Maven 3.9.6 (or later), which can be downloaded from +. Install Maven 3.9.8 (or later), which can be downloaded from http://maven.apache.org/download.html[http://maven.apache.org/download.html]. Make sure that your PATH includes the MVN_HOME/bin directory. @@ -64,6 +64,111 @@ TIP: On a non-English Windows env, the Asciidoctor Maven Plugin may fail to + . The distributions will be available under "package/target" directory. +==== Updating the website + +Use the top-level `generate-manual.sh` script to generate and publish the documentation website. + +[source] +---- +./generate-manual.sh publish <svn_user> <svn_pass> +./generate-manual.sh simulate <svn_user> <svn_pass> +---- + +Modes: + +* `publish`: generates all documentation and publishes to Apache SVN +** Generates exactly 2 versions (latest + stable) +** Publishes HTML manual to `$SVN_WEBSITE_BASE/manual` and API docs from master +** Uploads release packages (PDF/ZIP) to Apache Dist SVN for non-master branches +** Removes old versions automatically on the website + +* `simulate`: dry-run; prints the commands without making changes + +Requirements: + +* Java 11+, Maven 3.6+, Git, SVN client, `bc` +* Access to the `master` and the stable branch configured in `generate-manual-config.sh` + +Outputs and locations: + +* Staging directories under `target/generated-docs/` (created by the build) +* Website content committed to `$SVN_WEBSITE_BASE/manual/<version>` +* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/<version>` + +Notes: + +* The script sources optional `generate-manual-config.sh` and `shell-utils.sh` for configuration/utilities. +* Javadoc aggregation is attempted; if it fails (toolchain mismatch), the rest still publishes. + +==== JGitFlow + +You can use the https://jgitflow.bitbucket.org[JGitFlow Maven plugin] to work with feature, hotfix and other types of branches. + +For example, to start a feature branch, simply use: + +[source] +---- +mvn jgitflow:feature-start +---- + +This will prompt you for the feature name, and then create a feature branch and update all the POMs to have a version that contains the feature name. This makes it easier to integrate with continuous integration systems to generate builds for the feature branch. + +Once the feature is completed you can use: + +[source] +---- +mvn jgitflow:feature-finish +---- + +To merge the branch into master. + +==== Maven Build Cache + +Apache Unomi uses the Maven Build Cache extension to significantly improve build performance by caching compiled artifacts and avoiding unnecessary recompilation. + +For more information, see the official documentation: + +* https://maven.apache.org/extensions/maven-build-cache-extension/[Maven Build Cache Extension Overview] +* https://maven.apache.org/extensions/maven-build-cache-extension/parameters.html[Build Cache Parameters Reference] + +Performance improvements: + +* Without cache: ~1 minute 59 seconds for a full clean install +* With cache: ~3.176 seconds for subsequent builds (after initial build) + +The build cache is enabled by default and configured in the `.mvn/maven-build-cache-config.xml` file. The cache configuration includes: + +* Local caching with up to 3 builds cached +* SHA-256 hash algorithm for cache keys +* Includes all source directories (`src/`) +* Excludes `pom.xml` files and generated sources (`src/main/javagen/**`) + +Command line control: + +* Disable cache: `mvn -Dmaven.build.cache.enabled=false clean install` + ** Completely turns off the build cache functionality + ** Maven will not store or retrieve any build outputs from the cache + ** Performs a full build as if the cache were not present + ** Use this when you want to ensure no cache influence on the build + +* Skip cache (force rebuild): `mvn -Dmaven.build.cache.skipCache=true clean install` + ** Skips looking up artifacts in caches but still writes new results to cache + ** Forces Maven to rebuild everything without using cached artifacts + ** New build results will be stored in cache for future builds + ** Use this to force a complete rebuild while keeping cache functionality active + +* Enable cache (default): `mvn -Dmaven.build.cache.enabled=true clean install` + ** Enables full cache functionality (read and write) + ** Maven will use cached artifacts when available and store new results + ** This is the default behavior when the cache is enabled + +Purging the build cache: + +To completely reset the build cache and force a full rebuild: + +* Skip cache and rebuild: `mvn -Dmaven.build.cache.skipCache=true clean install` +* Or manually delete the cache directory: `rm -rf ~/.m2/build-cache` (Unix/Mac) or `rmdir /s %USERPROFILE%\.m2\build-cache` (Windows) + ==== Installing an ElasticSearch server Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch server as this is no longer supported by
