sampottinger/processing_build.md

## processing_build.md

      
    Raw
  

              processing_build.md
            
          
    Building Processing

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.


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.


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 into build/{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


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 .app file can be executed via a double click at build/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.


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.