Build Instructions

How to Build

Requirements

Building HTM.java requires:

• JDK 8
• Gradle 1.7+

Note: Info on installing gradle can be found on the wiki (look at #3) here.

Linux Gradle Issues? see the wiki here or use the reference build environment (below).

Building

Execute a quick sanity check by running all the tests from within the <path to git repo>/htm.java:

gradle check  # Executes the tests and runs the benchmarks

--or--

gradle -Pskipbench check  # Executes the tests w/o running the benchmarks

Reference Build Environment

As a convenience to developers, we provide a docker image with the needed software to build the HTM.java library from sources. This approach relies on the Docker Toolbox, which is installable on Mac and Windows. If you're using Linux, skip to the Build the Docker Image section.

Below we'll use a technique to share your cloned HTM.java sources from your project folder into a docker container, then build the library with gradle. The build outputs are written back to your project folder, not isolated within the container.

Install Docker Toolbox

Follow the instructions on the toolbox site, then open the quickstart terminal. You should adjust the memory settings on the toolbox VM, because the default (2GB) is insufficient for the unit test suite.

[htm.java]$ docker-machine rm default
About to remove default
Are you sure? (y/n): y

[htm.java]$ docker-machine create -d virtualbox --virtualbox-memory 4096 default
...

Build the Docker Image

The docker image, which you simply build once, contains OpenJDK 8 and Gradle. It doesn't contain any HTM.java source code; when we later run the container, the source code is read directly from your project folder.

[htm.java]$ docker build -t $USER/htm.java .
...
Successfully built <IMAGE ID>

Run the Container

Run a container based on the docker image, which launches a bash shell where you'll fire up gradle.

[htm.java]$ docker run -it --rm -v `pwd`:/home/vagrant/htm.java $USER/htm.java

Notice that the current directory (which should be your HTM.java project folder) is shared into the container, as /home/vagrant/htm.java.

Build

Build the project as usual.

vagrant@96e54fd78012:~$ cd /home/vagrant/htm.java
vagrant@96e54fd78012:~/htm.java$ gradle -Pskipbench check
...
BUILD SUCCESSFUL

vagrant@96e54fd78012:~/htm.java$ exit

Debug

You can remotely debug the unit tests from your host into the container. Simply expose the debug port when you start the container, run gradle with debugging enabled, then attach with your IDE. Here's an example:

[htm.java]$ docker-machine ip default
192.168.99.100
[htm.java]$ docker run -it --rm -p 5005:5005 -v `pwd`:/home/vagrant/htm.java $USER/htm.java
vagrant@19e4d58730c4:~$ cd htm.java
vagrant@19e4d58730c4:~/htm.java$ gradle -Dtest.debug -Pskipbench check
...
Listening for transport dt_socket at address: 5005

# attach to 192.168.99.100:5005 from within your IDE!