Building eXist-db

(2Q19)

This article will tell you how to build eXist-db from source, please also check the build instructions in the source-code repo.

Building eXist-db from GitHub

Building eXist-db is quite easy and requires four simple steps:

Make sure you have the required build tools installed
- Java JDK - Building eXist-db requires JDK 8 or newer. If you are looking for an OpenJDK, then the Azul Zulu JDK may suite you.
- Apache Maven - Building eXist-db requires Maven 3.6.0 or newer.
- Docker (optional) - If you wish to build the Docker image, then Docker is required.
- HFS Support (optional) - If you are on Linux and wish to build a DMG for Mac platforms.
  - CentOS etc. - sudo yum install hfsutils hfsplus-tools
  - Debian etc. - sudo apt-get install hfsprogs hfsplus
- Apple Developer Code signing certificate (optional) - If you are on a Mac and wish to build and sign a DMG.
Clone from Github

The GitHub URL for the develop branch is:
```
https://github.com/eXist-db/exist.git
```
Please follow the instructions on our GitHub page page ( README.md section)

You can clone it by running:
```
git clone --single-branch --branch=develop https://github.com/eXist-db/exist.git
```
The above will only clone the develop branch, if you require all branches, you should omit the --single-branch --branch=develop arguments.
Set JAVA_HOME

Before starting the build, your JAVA_HOME environment variable should be set to point to the root directory of the JAVA JDK (note: JDK, not JRE!). Open a console on Unix/Linux, or a DOS cmd prompt on Windows and type:
```
set JAVA_HOME=c:\path\to\jdk
```
on Windows or
```
export JAVA_HOME=/path/to/jdk
```
on Unix/Linux.
Build eXist

Change into the eXist-db directory you just checked out and call
```
mvn -DskipTests clean compile
```

Using the Build System

You can rebuild all eXist-db packages and distributions from the cloned source code:

mvn -DskipTests clean package

This will create a fresh distributions in the exist-distribution/target directory, and a fresh installer in the exist-installer/target directory.

If you wish to also build a Docker image, you should add the property -Ddocker=true.

If you wish to also build a signed DMG on Mac, you should add the properties -Dmac-signing=true -Dmac.codesign.identity="The ID of your Apple Developer Certificate".


`mvn clean`	Cleans the files and directories generated by a previous build. Data is not preserved unless you have overriden the path to the data directory.
`mvn compile`	Recompiles any changed source code.
`mvn dependency:analyze`	Checks for any problems with the dependencies that eXist-db depends on.
`mvn test`	Runs all tests across all modules. Surefire HTML reports can be found in the modules `target/surefire-reports/html` folder.
`mvn install`	Installs all Maven artifacts to your local Maven repository (i.e. Unix/Linux: `~/.m2/repository`, or Windows: `%USERPROFILE%\.m2\repository`.
`mvn package`	Performs the full lifecycle build, after which eXist-db distributions can be found in `exist-distribution/target`, and an eXist-db IzPack installer can be found in `exist-installer/target`.


`-V`	Show the version of Maven and Java used for the build.
`-o`	Execute Maven in offline (i.e. no Internet access!) mode.
`-U`	Force Maven to check online for any updates to dependency versions.
`-T`	Force Maven to execute the lifecycle for the reactor modules in parallel. For example `-T 2C` instructs Maven to use 2x the core count of threads to parallelise the build. This can have a large positive imapact on build times.
`-P profileName` (Enable named profile) `-P !profileName` (Disable named Profile)	Enables of disables build profiles, see the list of profiles below.
`-Ddocker=true`	Enable buiding eXist-db Docker images.
`-Ddocker.tag=tag-name`	Tags the built eXist-db Docker image with a specific tagname.
`-Dmac.signing=true`	Enable signing of Mac `.app` and `.DMG` files (only on Mac platforms).
`-Dmac.codesign.identity="The ID of your Apple Developer Certificate"`	Specify the certificate for signing of Mac `.app` and `.DMG` files (only on Mac platforms).
`-Dxar.resolve.offline=true`	Do not attempt to download the latest version of any EXPath Packages which are set to be auto-deployed. Useful for offline working; inferred by Maven's `-O` option.
`-DskipTests`	Do not execute any tests.
`-Ddependency-check.skip=true`	Skip the OWASP dependency security analysis.
`-Dtest=MyTestClassName`	The name of a single test to run. If running Maven from the root of the project as opposed to inside the specific module which houses the test, you sould also add `-DfailIfNoTests=false`.
`-DtrimStackTrace=false`	When running tests, if a stacktrace is produced as part of an error, show the full output instead of trimming it.
`MAVEN_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"`	When this precedes the `mvn` command, Maven will be run through the Java debugger, which allows you to connect from IntelliJ or another IDE which support JDWP.

Build Profiles

Some aspects of the build are separated into profiles which may be enabled or disabled as needed.



`skip-build-dist-archives`	Skip building eXist-db .tar.bz2 and .zip packages	Disabled
`docker`	Build/Publish an eXist-db Docker Container	Disabled
`installer`	Build/Publish an eXist-db IzPack installer	Enabled
`codesign-mac-app`	Codesign the eXist-db .app package. Requires macOS and an Apple Developer Certificate	Enabled on macOS when `-Dmac-signing=true`
`mac-dmg-on-mac`	Build/Publish a DMG for eXist-db from Mac. Requires macOS.	Enabled on macOS when `-Denv.CI=true` is not set, e.g. Travis-CI
`mac-dmg-on-unix`	Build/Publish a DMG for eXist-db from Unix. Requires Unix like OS with loopback filesystem and HFS tools.	Enabled on Linux when `-Denv.CI=true` is not set, e.g. Travis-CI
`codesign-mac-dmg`	Codesign the eXist-db DMG. Requires macOS and an Apple Developer Certificate	Enabled on macOS when `-Dmac-signing=true`
`java8-runtime-compatibility`	Ensure runtime compatibility with Java 8. Sets the `-release 8` to javac.	Enabled on JDK 9+
`micro-benchmarks`	eXist-db Micro-benchmarks	Enabled
`concurrency-stress-tests`	eXist-db JCStress Tests	Enabled
`windows-disable-parallel-testing`	Causes the test suite to run without parallelism	Enabled on AppVeyor Windows Builds

Building eXist-db