Build From Source

Instructions to build all DL4J libraries from source.

A reference for building dl4j from source can be found for every platform in our workflows. Below we will recommend common steps such as pre requisites for each platform and commands to build from source for cpu for various configurations.

For an overview of the GitHub actions workflows see the overview doc

f you have suggestions for improving this document, please comment over at the community forums

Core steps:

1. Building libnd4j for your specific platform

2. Linking the nd4j backend you want to compile for against libnd4j via JavaCPP

3. Compiling the rest of the code in to jar files

Key concepts

1. Libnd4j is a CMake based c++ project that supports running optimized math code on different architectures. Its sole focus is being a tiny self contained library for running math kernels. It can link against optimized BLAS routines, platform specific CNN libraries such as OneDNN and CuDNN, and contains hundreds of math kernels for implementing neural networks and other math routines.

2. Maven: Maven is the core build tool for deeplearning4j. Understanding maven is key to building deeplearning4j from source

3. Maven and CMake: For compiling libnd4j, we invoke a buildnativeoperations.sh wrapper script via maven. buildnativeoperations.sh in turn automatically sets up CMake to then build the c++ project

4. pi_build.sh: This is our build script for embedded and ARM based platforms. It focuses on cross compilation running on a Linux x86 based platform.

5. buildnativeoperations.sh: The main build script for libnd4j. It initializes CMake and invokes CMake compilation for the user on whatever platform the user is currently on unless the user specifies an alternative platform. Specifying a different platform is possible for android for example.

Common steps for all platforms

Ensure you have the following installed: 1. cmake 3.19 or above

2. GCC 4.9 or above

3. Maven 3.8 or higher

4. JDK 11 (Note: a JDK not a JRE) this has a compiler needed for building java programs

When the above in installed, ensure everything is setup on your PATH.

Set your JAVA_HOME to wherever java is installed with:

export JAVA_HOME=path/to/your/java

Building for x86_64

The main considerations for building on x86_64 are:

1. Whether to compile for avx2 or avx512

2. Whether to use OpenBLAS or MKL

3. Whether to link against OneDNN

Linux:

The target directory should folders like bin and lib in it.

On red hat systems (fedora, centos, rockylinux, oracle, alma,..) this will typically be:

yum group mark install "Development Tools"
yum install cmake maven

Depending on how old your RHEL variant is, you may need to build cmake from source.

For ubuntu/debian:

sudo apt update 
sudo apt install build-essential 
sudo apt-get install cmake maven

Mac:

On macs, we use brew to manage the pre requisites. Install brew using: https://brew.sh/ Once brew is installed then run:

brew install gpg1 gnu-sed unzip  ccache gcc swig autoconf-archive automake cmake libomp libtool libusb ant maven nasm xz pkg-config sdl gpg bison flex perl ragel binutils gradle gmp isl libmpc mpfr wget python

Windows:

On windows, we use msys2. Please follow the setup guides here: https://www.msys2.org/

After it's installed, use an msys2 terminal and run:

pacman -Ss  base-devel  git tar pkg-config unzip p7zip zip autoconf autoconf-archive automake patch   mingw-w64-x86_64-make --noconfirm mingw-w64-x86_64-gnupg mingw-w64-x86_64-cmake mingw-w64-x86_64-nasm mingw-w64-x86_64-toolchain mingw-w64-x86_64-libtool mingw-w64-x86_64-gcc  mingw-w64-x86_64-gcc-fortran mingw-w64-x86_64-libwinpthread-git mingw-w64-x86_64-SDL mingw-w64-x86_64-ragel

Once everything is installed, in your platform terminal, you can run maven commands.

The simplest default install is:

mvn -Pcpu clean install -DskipTests

If you want to do something more complicated like build with avx2/avx512 or use onednn then you need to understand a few more concepts.

The first part is knowing what platform you're on. Below are the common ones:

1. linux-x86_64

2. macosx-x86_64

3. windows-x86_64

Typically you need to specify this as a parameter in combination with whatever the target advanced functionality (avx, onednn,..) you want is. Below are samples for linux, replace the platform with whatever platform you are running on below:

# Note for mac osx this is due to lack of protoc availability and mac osx arm64:
Macs need -Pprotoc-provided-binaries
# Basic
mvn -Pcpu clean install -DskipTests


#AVX2
mvn -Pcpu -Dlibnd4j.classifier=linux-x86_64-avx2 -Dlibnd4j.extension=-avx2 -Djavacpp.platform.extension=-avx2 clean install -DskipTests

#AVX512
mvn -Pcpu -Dlibnd4j.classifier=linux-x86_64-avx512 -Dlibnd4j.extension=-avx512 -Djavacpp.platform.extension=-avx512 clean install -DskipTests

#Onednn and AVX512:
mvn  -Dlibnd4j.classifier=linux-x86_64-onednn-avx-512 -Dlibnd4j.helper=-onednn -Dlibnd4j.extension=-avx512 -Djavacpp.platform.extension=-onednn-avx512

#Onednn and AVX512:
mvn  -Dlibnd4j.classifier=linux-x86_64-onednn-avx2-Dlibnd4j.helper=-onednn -Dlibnd4j.extension=-avx2 -Djavacpp.platform.extension=-onednn-avx2

Building for ARM

ARM based builds all link against the armcompute library by default and, as mentioned above, use the pi_build.sh script for building libnd4j on specific platforms. Note that pi_build.sh can also be used to compile all of dl4j for a specific project.

pi_build.sh mainly focuses on cross compilation.

In order to properly use the pi_build.sh script, a number of environment variables should be set. Per platform, you can find these environment variables in the final build step under the environment section.

If you would like to compile deeplearning4j on an actual ARM device, please use the normal buildnativeoperations.sh workflow.

Building for CUDA

In order to compile deeplearning4j for a particular version, you must first invoke change-cuda-versions.sh in the root directory:

./change-cuda-versions.sh $YOUR_CUDA_VERSION

This will ensure that all library versions are set to the appropriate version. Ensure that the CUDA toolkit you need is installed. If you intend on using CuDNN, ensure that is also installed correctly. For installing CUDA, consider using our install scripts as a reference if you intend on doing automated installs.

Jetson nano users: please see this thread for successfully compiling deeplearning4j on Jetson nano.

In short: It relies on CUDA 10.0. The JavaCPP presets for CUDA are also only compiled for arm64 for CUDA 10.0. You can find the supported CUDA versions for CUDA 10.0 here If you would like something more up to date, please feel free to contact us over at our forums As of 1.0.0-M1.1 you can also use updated dependencies:

<dependency>
  <groupId>org.nd4j</groupId>
  <artifactId>nd4j-cuda-10.2</artifactId>
  <version>1.0.0-M2.1</version>
</dependency>

Note for windows users

We use msys2 for compiling libnd4j. CUDA requires MSVC in order to be installed in order to properly compile CUDA kernels. If you want to compile libnd4j for CUDA from source, please ensure you first invoke the vcvars.bat script in a cmd terminal, then launch msys2 manually. For more specifics, please see our Windows CUDA 11 and 11.2 build files.