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 3 simple steps:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

-Ddocker=true

Enable buiding eXist-db Docker images.

-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).

-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.