This is an automated email from the ASF dual-hosted git repository.
shuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git
The following commit(s) were added to refs/heads/master by this push:
new b617d5c25 UNOMI-892-maven-cache: Adopt Maven Build Cache, consolidate
BUILDING into manual, update website docs (#736)
b617d5c25 is described below
commit b617d5c25d19fe0c2740935c958751394c101e1b
Author: Serge Huber <[email protected]>
AuthorDate: Fri Nov 28 12:17:58 2025 +0100
UNOMI-892-maven-cache: Adopt Maven Build Cache, consolidate BUILDING into
manual, update website docs (#736)
* 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
* Adressed feedback from jayblanc.
---
.mvn/extensions.xml | 5 ++
.mvn/maven-build-cache-config.xml | 43 ++++++++++
.vscode/settings.json | 3 +
BUILDING | 72 +---------------
.../src/main/asciidoc/building-and-deploying.adoc | 99 +++++++++++++++++++++-
5 files changed, 153 insertions(+), 69 deletions(-)
diff --git a/.mvn/extensions.xml b/.mvn/extensions.xml
index d0eb2b622..2397f14f1 100644
--- a/.mvn/extensions.xml
+++ b/.mvn/extensions.xml
@@ -20,6 +20,11 @@
-->
<extensions>
+ <extension>
+ <groupId>org.apache.maven.extensions</groupId>
+ <artifactId>maven-build-cache-extension</artifactId>
+ <version>1.2.1</version>
+ </extension>
<extension>
<groupId>com.gradle</groupId>
<artifactId>develocity-maven-extension</artifactId>
diff --git a/.mvn/maven-build-cache-config.xml
b/.mvn/maven-build-cache-config.xml
new file mode 100644
index 000000000..9057a9cce
--- /dev/null
+++ b/.mvn/maven-build-cache-config.xml
@@ -0,0 +1,43 @@
+<!-- -
+ 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";>
+ <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>
+ <includes>
+ <include>src/</include>
+ </includes>
+ <excludes>
+ <exclude>pom.xml</exclude>
+ <exclude>src/main/javagen/**</exclude>
+ </excludes>
+ </global>
+ </input>
+</cache>
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 000000000..7b016a89f
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+ "java.compile.nullAnalysis.mode": "automatic"
+}
\ 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 12dfd9104..433f69e15 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -28,7 +28,7 @@ directly as described in this section.
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.
@@ -159,6 +159,103 @@ export NO_COLOR=1
+
For a complete list of options and examples, run `./build.sh --help`.
+==== 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 17+, 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 efficiency by caching compiled artifacts and avoiding unnecessary
recompilation (build time without/with cached artifacts ~2mn/~3s).
+
+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, manually delete
the cache directory: `rm -rf ~/.m2/build-cache` (Unix/Mac) or `rmdir /s
%USERPROFILE%\.m2\build-cache` (Windows)
+
+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]
+
==== Installing an ElasticSearch server
Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch
server as this is no longer supported by
