Building the Pi4J Project is simple and requires minimal effort. Pi4J is primarily built using Apache Maven and Java 11. Pi4J can be built directly on your host computer or inside a Docker container where all toolchains and dependencies are already installed, configuired and cached.
If you wish to build using a Docker container, please skip ahead to the Building with Docker topic.
In order to build Pi4J, the host system must have the following toolchains pre-installed.
| Name | Version | URL |
|---|---|---|
| Java Development Kit (JDK) | 11.0.7 (or newer) | https://openjdk.java.net/ |
| Apache Maven | 3.6.3 (or newer) | https://maven.apache.org/download.cgi |
The JAVA_HOME system environment variable must be configiured to point to the JDK installed path.
To build the Pi4J project, use the following Maven comand from the parent Pi4J directory.
mvn clean install
If you prefer to skip all unit/integration testing, use the folllowing Maven command:
mvn clean install -DskipTests
Alternatively, the Pi4J project can be entirely compiled inside a prebuilt Pi4J Builder Docker container. This eliminates the need/requirement to install the build toolchains and configure your system to build Pi4J. To build the Pi4J project using Docker, run the following shell script from the parent Pi4J directory.
./build-docker.sh
The project which provides these Docker images can be found on GitHub > Pi4J/pi4j-docker and includes an extensive README with the full info on how to build and use these images.
Extract from the README:
This project contains the Dockerfiles and build scripts to create the Pi4J builder
docker images used for compiling/building the Pi4J projects. The Pi4J builder images
include the following:
Pi4J Base Builder pi4j/pi4j-builder-base:latest :
This is the base image used by all the other builder images. It's based on Ubuntu 18.04
with JDK 11 and Maven pre-installed. This image's entry point is a Bash shell.
(https://hub.docker.com/repository/docker/pi4j/pi4j-builder-base)
Pi4J Native Builder pi4j/pi4j-builder-native:latest :
This image is derived from pi4j/pi4j-builder-base and adds support for native cross-compilers
and build tools for architectures: arm, armhf, aarch64/arm64. This image's
entry point is a bash shell attempting to execute the file ./build.sh in the volume mounted
under the /build path.
Pi4J v1.4 Builder pi4j/pi4j-builder:1.4 :
This image is derived from pi4j/pi4j-builder-native and additionally includes pre-cached Maven
build plugins and dependencies for Pi4J v1.4 builds. This image's
entry point is a Maven shell. If not explicitly provided, the default maven build arguments will be:
clean install -DskipTests -Pall-platforms. This will effectively build all Pi4J projects including
the pi4j-native project containing native libraries which will be cross-compiled for RaspberryPi/ARM
(32-bit & 64-bit) devices.
Pi4J v2.0 Builder pi4j/pi4j-builder:2.0 :
This image is derived from pi4j/pi4j-builder-native and additionally includes pre-cached Maven
build plugins and dependencies for Pi4J v2.0 builds. This image's
entry point is a Maven shell. If not explicitly provided, the default maven build arguments will be:
clean install -DskipTests -native. This will effectively build all Pi4J projects including
the native library projects which will be cross-compiled for RaspberryPi/ARM (32-bit & 64-bit) devices.
Note: Pi4J versions prior to v1.4 are not currently tested or supported in these Docker images.
Pi4J V.2 also includes native libraries that will need to be compiled if you are modifying any native code. Most users will never need to compile the native libraries as these artifacts are automatically downloaded when building the Pi4J JARs from Maven repositories. One of the following commands can be used to build the Pi4J JARs and Native Libraries:
mvn clean install -Pnative
mvn clean install -Pnative,docker
mvn clean install -Pnative,cross-compile
See the custom build profiles in the Custom Build Profiles section for more information about the profiles illustrated in these commands.
Additional information about Docker Builds vs Cross-Compiler builds can be found here: https://github.com/Pi4J/pi4j-v2/issues/21#issuecomment-651976487
The Pi4J Maven build includes a number of custom profiles that can be activated to perform various build steps.
| Profile | Description | Notes |
|---|---|---|
sources | Package raw sources for each JAR | Only needed when performing a snapshot or release build. |
javadoc | Compile and package JavaDoc for each JAR | Only needed when performing a snapshot or release build. |
native | Compile any native libraries included in the build | Only needed when modifying native code or performing a snapshot or release build. |
docker | Use docker builder containers to compile native library artifacts | Only used when incuding the native profile or performing a snapshot or release build. |
cross-compile | Use cross-compilers on host to compile native library artifacts | Only used when incuding the native profile or performing a snapshot or release build. |
test-hardware | Perform hardware integration testing | EXPERIMENTAL |
mac | Use docker builder containers to compile native library artifacts (Same as docker profile) | Automatically activated when running build from a MacOS host system. |
windows | Use docker builder containers to compile native library artifacts (Same as docker profile) | Automatically activated when running build from a Windows host system. |
transfer | Perform SSH/SCP file transfers for each JAR to a remote Raspberry Pi | Used for parallel development and testing. |
You can activate a build profile using the -P{profile-name} argument in the Maven command:
mvn clean install -Pjavadoc
Pi4J release and snapshot builds are reserved for the Pi4J Development Team. A release build ensures all JARs, resources, source-bundles, native libraries, and javadoc artifacts are compiled and deployed to the public Maven repositories. You can use the following command to perform all the build steps that would be performed during a release or snapshot build.
mvn clean install -Drelease-build