Address PR review comments for build.sh script
- Fix color readability in build.sh examples section: replace GRAY with NC
(no color) for better terminal readability. Use NC once at the start
instead of wrapping each line with color codes.
- Add comprehensive documentation for build.sh script in Building section:
* Add brief mention at the start of Building section with cross-reference
* Add new "Using the build.sh script" subsection with:
- Overview of script features and benefits
- Step-by-step usage instructions
- Complete set of examples matching build.sh --help output
- All examples use plain commands without prompt markers
- Minor formatting: align help output option descriptions for consistency
The documentation examples now exactly match those displayed by build.sh --help,
ensuring consistency between the script and its documentation.
diff --git a/build.sh b/build.sh
index 3413e03..19dd5d0 100755
--- a/build.sh
+++ b/build.sh
@@ -280,22 +280,22 @@
echo -e " ${CYAN}-s, --skip-tests${NC} Skip all tests"
echo -e " ${CYAN}-i, --integration-tests${NC} Run integration tests"
echo -e " ${CYAN}-d, --deploy${NC} Deploy after build"
- echo -e " ${CYAN}-X, --maven-debug${NC} Enable Maven debug output"
- echo -e " ${CYAN}-o, --offline${NC} Run Maven in offline mode"
+ echo -e " ${CYAN}-X, --maven-debug${NC} Enable Maven debug output"
+ echo -e " ${CYAN}-o, --offline${NC} Run Maven in offline mode"
echo -e " ${CYAN}--debug${NC} Run Karaf in debug mode"
echo -e " ${CYAN}--debug-port PORT${NC} Set debug port (default: 5005)"
- echo -e " ${CYAN}--debug-suspend${NC} Suspend JVM until debugger connects"
+ echo -e " ${CYAN}--debug-suspend${NC} Suspend JVM until debugger connects"
echo -e " ${CYAN}--no-maven-cache${NC} Disable Maven build cache"
echo -e " ${CYAN}--purge-maven-cache${NC} Purge local Maven cache before building"
echo -e " ${CYAN}--karaf-home PATH${NC} Set Karaf home directory for deployment"
- echo -e " ${CYAN}--use-opensearch${NC} Use OpenSearch instead of ElasticSearch"
- echo -e " ${CYAN}--no-karaf${NC} Build without starting Karaf"
- echo -e " ${CYAN}--auto-start ENGINE${NC} Auto-start with specified engine"
+ echo -e " ${CYAN}--use-opensearch${NC} Use OpenSearch instead of ElasticSearch"
+ echo -e " ${CYAN}--no-karaf${NC} Build without starting Karaf"
+ echo -e " ${CYAN}--auto-start ENGINE${NC} Auto-start with specified engine"
echo -e " ${CYAN}--single-test TEST${NC} Run a single integration test"
echo -e " ${CYAN}--it-debug${NC} Enable integration test debug mode"
- echo -e " ${CYAN}--it-debug-port PORT${NC} Set integration test debug port"
- echo -e " ${CYAN}--it-debug-suspend${NC} Suspend integration test until debugger connects"
- echo -e " ${CYAN}--skip-migration-tests${NC} Skip migration-related tests"
+ echo -e " ${CYAN}--it-debug-port PORT${NC} Set integration test debug port"
+ echo -e " ${CYAN}--it-debug-suspend${NC} Suspend integration test until debugger connects"
+ echo -e " ${CYAN}--skip-migration-tests${NC} Skip migration-related tests"
else
cat << "EOF"
_ _ _____ _ ____
@@ -334,29 +334,31 @@
echo
echo "Examples:"
if [ "$HAS_COLORS" -eq 1 ]; then
- echo -e " ${GRAY}# Build with integration tests using OpenSearch${NC}"
- echo -e " ${GRAY}$0 --integration-tests --use-opensearch${NC}"
- echo -e
- echo -e " ${GRAY}# Build in debug mode${NC}"
- echo -e " ${GRAY}$0 --debug --debug-port 5006 --debug-suspend${NC}"
- echo -e
- echo -e " ${GRAY}# Deploy to specific Karaf instance${NC}"
- echo -e " ${GRAY}$0 --deploy --karaf-home ~/apache-karaf${NC}"
- echo -e
- echo -e " ${GRAY}# Build without Karaf and auto-start OpenSearch${NC}"
- echo -e " ${GRAY}$0 --no-karaf --auto-start opensearch${NC}"
- echo -e
- echo -e " ${GRAY}# Run a single integration test${NC}"
- echo -e " ${GRAY}$0 --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT${NC}"
- echo -e
- echo -e " ${GRAY}# Debug a single integration test${NC}"
- echo -e " ${GRAY}$0 --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT --it-debug --it-debug-suspend${NC}"
- echo -e
- echo -e " ${GRAY}# Run without colored output${NC}"
- echo -e " ${GRAY}NO_COLOR=1 $0${NC}"
- echo -e " ${GRAY}# or ${NC}"
- echo -e " ${GRAY}export NO_COLOR=1${NC}"
- echo -e " ${GRAY}$0${NC}"
+ # Reset to default terminal color for examples (better readability)
+ echo -e "${NC}"
+ echo " # Build with integration tests using OpenSearch"
+ echo " $0 --integration-tests --use-opensearch"
+ echo
+ echo " # Build in debug mode"
+ echo " $0 --debug --debug-port 5006 --debug-suspend"
+ echo
+ echo " # Deploy to specific Karaf instance"
+ echo " $0 --deploy --karaf-home ~/apache-karaf"
+ echo
+ echo " # Build without Karaf and auto-start OpenSearch"
+ echo " $0 --no-karaf --auto-start opensearch"
+ echo
+ echo " # Run a single integration test"
+ echo " $0 --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT"
+ echo
+ echo " # Debug a single integration test"
+ echo " $0 --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT --it-debug --it-debug-suspend"
+ echo
+ echo " # Run without colored output"
+ echo " NO_COLOR=1 $0"
+ echo " # or"
+ echo " export NO_COLOR=1"
+ echo " $0"
else
echo " # Build with integration tests using OpenSearch"
echo " $0 --integration-tests --use-opensearch"
diff --git a/manual/src/main/asciidoc/building-and-deploying.adoc b/manual/src/main/asciidoc/building-and-deploying.adoc
index c91c860..12dfd91 100644
--- a/manual/src/main/asciidoc/building-and-deploying.adoc
+++ b/manual/src/main/asciidoc/building-and-deploying.adoc
@@ -14,6 +14,11 @@
=== Building
+Apache Unomi 3.x provides a convenient `build.sh` script that simplifies the build process with
+enhanced error handling, preflight validation, and deployment options. See the
+<<Using the build.sh script>> section below for details. Alternatively, you can build using Maven
+directly as described in this section.
+
==== Initial Setup
. Install J2SE 17 SDK (or later), which can be downloaded from
@@ -64,6 +69,96 @@
+
. The distributions will be available under "package/target" directory.
+==== Using the build.sh script
+
+Apache Unomi 3.x provides a unified `build.sh` script that simplifies the build, deployment, and execution process.
+This script replaces multiple legacy build scripts and provides enhanced error handling, colorized output, and
+comprehensive environment validation.
+
+The `build.sh` script offers the following features:
+
+* **Preflight validation**: Automatically checks for required tools (Java, Maven, GraphViz), system resources
+ (memory, disk space), Maven settings, and port availability
+* **Flexible build options**: Support for skipping tests, running integration tests, using OpenSearch, debug modes,
+ and more
+* **Deployment helpers**: Automatically copies KAR packages to Karaf deploy directory and purges caches
+* **Enhanced output**: Colorized, structured output with progress indicators (respects `NO_COLOR` environment variable)
+
+To use the script:
+
+. Get the code: `git clone https://github.com/apache/unomi.git`
+. Change to the top level directory of Apache Unomi source distribution.
+. Make the script executable (if needed): `chmod +x build.sh`
+. Run the script with your desired options:
++
+[source]
+----
+./build.sh --help
+----
++
+This will display all available options and usage examples.
+
+Common usage examples:
+
+* Build with integration tests using OpenSearch:
++
+[source]
+----
+./build.sh --integration-tests --use-opensearch
+----
++
+* Build in debug mode:
++
+[source]
+----
+./build.sh --debug --debug-port 5006 --debug-suspend
+----
++
+* Deploy to specific Karaf instance:
++
+[source]
+----
+./build.sh --deploy --karaf-home ~/apache-karaf
+----
++
+* Build without Karaf and auto-start OpenSearch:
++
+[source]
+----
+./build.sh --no-karaf --auto-start opensearch
+----
++
+* Run a single integration test:
++
+[source]
+----
+./build.sh --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT
+----
++
+* Debug a single integration test:
++
+[source]
+----
+./build.sh --integration-tests --single-test org.apache.unomi.itests.graphql.GraphQLEventIT --it-debug --it-debug-suspend
+----
++
+* Run without colored output:
++
+[source]
+----
+NO_COLOR=1 ./build.sh
+----
++
+or
++
+[source]
+----
+export NO_COLOR=1
+./build.sh
+----
++
+For a complete list of options and examples, run `./build.sh --help`.
+
==== Installing an ElasticSearch server
Starting with version 1.2, Apache Unomi no longer embeds an ElasticSearch server as this is no longer supported by
