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 @@ --> + + org.apache.maven.extensions + maven-build-cache-extension + 1.2.1 + com.gradle develocity-maven-extension 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 @@ + + + + true + SHA-256 + true + + http://host:port + + + 3 + + + + + + + src/ + + + pom.xml + src/main/javagen/** + + + + \ 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 +./generate-manual.sh simulate +---- + +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/` +* Release artifacts (PDF/ZIP + signatures/checksums) committed to Apache Dist SVN at `$SVN_DIST_BASE/` + +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