Processing Build Instructions
The following instructions describe how to build and release Processing across Windows, OS X, and Linux.
Local Environment Setup
Processing's ant-based build chain can create executables natively runnable for Linux, Mac, and Windows.
Pre-Requisites
Although Processing will download and use its own copy of OpenJDK and OpenJFX, the build chain itself requires Java 11+ and Ant in addition to getting a copy of the Processing source code.
Getting Java and Ant
You can choose to install these yourself or use the following guides below:
- Instructions for installing Java
- Instructions for installing Ant
- Instructions for modifying your environment variables on windows, mac and linux.
Getting Processing
One will also need to clone the repository for Processing itself. Some users who are simply building Processing but not contributing to it may prefer a "shallow" clone which does not copy the full history of the repository:
git clone --depth 1 https://github.com/processing/processing.git
Users that are developing for the project may require a full clone:
git clone https://github.com/processing/processing.git
Building
One can either build for your own operating system (the "host" operating system) or, starting with Processing 4, one can "cross-build" from a host nix system (linux or mac) to any other "target os" build. Before continuing, please be aware that you are agreeing to the license terms and that the developers do not make any guarantee or warranty (implicit or express) for any purpose.
Overview of steps
Before actually building, it is worth outlining the steps of the build process briefly:
- The modules outside of
buildare built first. During this process, a number of automated unit tests will be executed with results displayed on the command line. - The
buildmodule itself will built and results will go intobuild/{os}/workwhere{os}is the operating system for which you are building like "windows". Note that both ARM and x64 builds go into the same OS directory. - During the build of
build, the OpenJDK and OpenJFX will be downloaded with their binaries copied into the distribution. If building for the first time, these automated downloads from AdoptOpenJDK and Gluon may take some time.
Note that one may need to "clean" via ant linux-clean or equivalent.
Building for the "host" operating system
If building for your own system, navigate to where where you pulled the Processing source and execute ant build on the command line.
$ cd [path to processing repository]
$ cd build
$ ant build
The results will go into build/{os}/work where {os} matches the "host" operating system.
Executing a "cross-build"
If building for another operating system (if you are on Linux and want to build for Windows), there are a number of "cross-build" targets available. Note that one can only execute "cross-builds" on a *nix system (Linux or Mac) but "cross-builds" are available for all targeted operating systems.
For example, here is how to execute a cross-build "targeting" Windows (the results will go into build/windows/work):
$ cd [path to processing repository]
$ cd build
$ ant cross-build-windows
The following cross-build targets are available:
- cross-build-macosx
- cross-build-linux-x64
- cross-build-linux-aarch64
- cross-build-windows
Automated Tests
Unit tests are available by running the test target:
$ cd [path to processing repository]
$ cd build
$ ant test
These tests are not executed by default when running the build target but are recommended for developers contributing to the project.
Running
The build can be run directly or through Ant.
Executing via Ant
If built for the host operating system, one can use the ant run target as shown below:
$ cd [path to processing repository]
$ cd build
$ ant run
If not yet built, this will cause Processing to be built prior to running.
Using Executable Directly
Regardless of if cross-building, there are executables generated that can be run directly on the target operating system:
- Mac: the
.appfile can be executed via a double click atbuild/macosx/work/Processing.appor$ open build/macosx/work/Processing.app. - Linux: The resulting executable ends up at
build/linux/work/processing. - Windows: The resulting executable ends up at
build/windows/work/processing.exe.
Distributing
A number of targets are provided for distribution of executables. If the executable is not yet built, it will be created prior to running the dist target.
Available targets:
- macosx-dist
- windows-dist
- linux-dist
One can also use ant dist to distribute for the host OS.
Examples
For the host system, one can distribute like so:
$ cd [path to processing repository]
$ cd build
$ ant dist
From a nix system, one can cross-build and distribute for linux like so:
$ cd [path to processing repository]
$ cd build
$ ant linux-dist
Regardless, the distributable ends up in build/{os}/work where {os} is the target OS.
Code Signing
At present, only Mac builds require code signing to avoid an "App Gateway" issue. This is not executed by default by ant dist or ant macosx-dist. One can sign the resulting .app file though via:
$ /usr/bin/codesign --force --sign "Developer ID Application: Certificate Common Name" Processing.app/Contents/PlugIns/jdk-...
$ /usr/bin/codesign --force --sign "Developer ID Application: Certificate Common Name" Processing.app
Note that one will need to complete the jdk-... string to be something like jdk-11.0.1+13 depending on the build. Anyway, this will require an Apple Developer ID.
This is not strictly required especially if you are using your own app build.