Required Software

• Git
• Java 8 JDK
  
  • 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 (*NIX).
• Maven
  
  • Installation instructions
  • Make sure that Maven has enough memory to build DDF. Set appropriate memory settings in the MAVEN_OPTS environment variable such as "-Xms64m -Xmx4096m"

Setting up a Build Environment

If you haven't already, begin by setting up your development environment

Cloning

In order to run through a full build, be sure to have a clone for the ddf repository and optionally the ddf-support repository (NOTE: daily snapshots are deployed so downloading and building each repo may not be necessary since those artifacts will be retrieved.):

git clone git://github.com/codice/ddf.git
git clone git://github.com/codice/ddf-support.git (Optional)

Install the git hooks (see below for more info)

cd ddf/gitsetup
mvn install -Pgitsetup
cd ddf-support/gitsetup
mvn install -Pgitsetup

Git Hooks

Design

Git hooks have two functions:

1. Ensuring all commit comments are prefixed with a ticket number
2. Sanitizing against dirty words:
   1. filenames
   2. commit comments
   3. file content

Each repository contains a file named commit-prefix.txt under the gitsetup folder which is used to identify the ticket prefix required at the beginning of each commit message.

Sanitization is done based on a list of dirty words that is composed by combining blacklisted words from 3 locations:

• resources/blacklist-words.txt (inside the githooks artifact for default blacklisted words)
• gitsetup/blacklist-words.txt (as previously downloaded or manually copied at install time)
• ~/.gitsetup/backlist-words.txt (for optional personal blacklisted words)

From the resulting set of blacklisted words, those listed in the file gitsetup/whitelist-words.txt are which is committed inside each repository are removed. The remaining are then use as dirty words to sanitize against. The default blacklist list will typically contains expressions such as:

REGEX:\.printStackTrace
REGEX:do\snot\scommit
REGEX:System\.out\.print(?:ln|f)?

Words listed in all these files can be specified using Java regular expressions in addition to literal strings. Sanitization properly identifies word boundaries. Dirty words and expressions are case insensitive.

Installation

Git hooks should be installed in all git repositories. The installation process is simple and simply require executing:

mvn install -Pgitsetup

inside the gitsetup module provided in each repositories. They can also be removed and cleaned up using the clean maven goal instead of the install one.

When first installing the git hooks, maven will download automatically the git hooks jar artifact in your local repository and will continuously update this artifact at least once a day. Your git configuration will then be validated. Basically, it will make sure that you have defined the following 3 properties properly:

• core.autocrlf
• user.name
• user.email

The installation will then proceed to obtain the blacklist for all dirty words. You can manually store your own file as blacklist-words.txt under the gitsetup folder inside the repository or you can have it downloaded and refreshed automatically. If you choose the former then it will be up to you to update the file as it changes. If you choose the later then it will automatically be updated at least once a day as long as your have access to Nexus repository where it is deployed. In order to do so, you will be prompted for the Maven coordinates for the blacklist artifact. Defaults are provided but may not be suitable for all.

[INFO] Installing git hooks.
[INFO] The blacklist words file was not found
[INFO] Do you wish to download it automatically (y/n) [Y]? ↵
[INFO]
[INFO] Please provide the maven artifact's coordinates for the blacklist words file:
[INFO] group id []: com.my_group_id↵
[INFO] artifact id [blacklist-words]: ↵
[INFO] version [RELEASE]: ↵
[INFO] type [txt]: ↵
[INFO] classifier []: ↵

To download the artifact, the git hooks setup code will callback into maven (even when the hooks are actually running later during a git commit). So make sure that maven is accessible from the command line and that your settings.xml file located under your .m2 folder provides the right information. If you typically specify the settings file on the command line using maven's -s option or if you have defined two settings files (e.g. one for out of office and one for in office) and are using a mvn function to switch from one to the other, make sure to add -Dsettings.location=settings.path in addition to the -s settings.path such that the hooks will know which one to use when internally invoking maven. The settings.xml file location will be recorded at install time. You can always re-run the installation if the location changes.

That is it. Your hooks are now installed.

Building

Change to the root directory of the cloned ddf repository. Run the following command:

mvn install

Building with multiple threads

To build DDF using the [parallel builds feature of maven](https://cwiki.apache.org/confluence/display/MAVEN/Parallel+builds+in+Maven+3), Run the following command:

mvn install -T 8 

This tells maven to use 8 threads when building DDF. You can manually adjust the thread count to suit your machine, or use a relative thread count to the number of cores present on your machine by running the following command:

mvn install -T 1.5C 

This will use 6 threads if your machine has 4 cores.

Skipping Tests and Static Analysis

In conjunction with the above, there are two other flags that can be used to speed up the build. To skip running static analysis tools and tests, run the following command:

mvn install -T 1.5C -DskipStatic=true -DskipTests=true

Skipping Documentation

Additionally, the documentation module can be skipped entirely by adding the `-pl` flag with an `!` and the relative path of the module.

From the top level pom:

mvn install -T 1.5C -pl !distribution/docs

The `!` may need to be escaped:

mvn install -T 1.5C -pl \!distribution/docs

Incremental Builds

DDF now supports PR branch incremental builds using the GitFlow Incremental Builder Maven extension.

To enable incremental builds, simply add the -Dgib.enabled=true flag to your mvn command:

mvn install -Dgib.enabled=true

By default, the incremental builder will use the PR's base branch (e.g., refs/remotes/origin/master, refs/remotes/origin/2.10.x, etc.) to determine the modules that have changed and need to be rebuilt. To use a different base branch, used the -Dgib.referenceBranch option:

mvn install -Dgib.enabled=true -Dgib.referenceBranch=refs/remote/fork/branch

All the other options mentioned above can be used in conjunction with the incremental builder.

For a complete list of options, refer to the GitFlow Incremental Builder page.