Processing's ant-based build chain can create executables natively runnable for Linux, Mac, and Windows. 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.
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
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.
Overview of steps
Before actually building, it is worth outlining the steps of the build process briefly:
- The modules outside of
build
are built first. During this process, a number of automated unit tests will be executed with results displayed on the command line. - The
build
module itself will built and results will go intobuild/{os}/work
where{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
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
.app
file can be executed via a double click atbuild/macosx/work/Processing.app
or$ 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
.
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.
@sampottinger it might be worth mentioning that it's a good idea to do
ant linux-clean
etc to remove stale builds (I needed to do this to get antlr working again on my last build)