Mode Overview

Modes, also called language modes, allow Processing users to code and run sketches in different code languages and on different platforms. The default mode built-in to the Processing Development Environment (PDE) is called "Java", and compiles Processing code (with its Java-like syntax) to run sketches on the Java Virtual Machine (JVM). The name of the selected mode for each sketch appears in the small drop-down menu in the corner of that sketch. To begin a sketch in a different mode, create a new blank sketch and then select a different mode type from that drop-down before editing the sketch contents.

Additional modes may be installed and include Android Mode, Coffeescript mode, Python mode, p5.js, and Processing.R, among others.

Installing modes

In PDE, modes may be installed via via the Contributions Manager "Modes" tab. A shortcut to this tab from any sketch window is the mode dropdown menu > Add Mode. For more on Modes in the PDE interface, see Environment > Programming modes.

Note: Modes are distributed through PDE, however there are some modes, like CoffeeScript mode and Processing.py which are no longer compatible with PDE 3 - they only run on PDE 2 and earlier.

Other projects are related to or inspired by Processing but that are not distributed as modes. They are available as stand-alone applications. Examples include JRubyArt, p5py, and pyp5js.

Modes, Languages, and Libraries

Modes enable writing Processing sketches in different programming languages: Python mode in the syntax of Python 2, R mode in R, p5.js in JavaScript. Each mode has its own language documentation and examples. All modes implement core features of Processing such as setup, draw, size, point, line, rect, stroke, fill, translate, and rotate... but they may differ in language specific-ways: different variable types, naming conventions, or things available in some modes but not others such as advanced features (PShape) or included libraries (p5.dom).

Modes also target different platforms: p5.js runs in the web browser, Android mode runs on Android devices, Python and R mode are both transpiled into Java to run on JVM, much like the default mode.

Modes are compiled anr/or run on diffent platforms. This affects whether and how modes can access Processing (Java) libraries -- or libraries in their own language. The following table lists some currently available modes in PDE, what platform they run on, and their access to P5 libs and/or native libs.

Mode	Language	Runs on	P5 libs	language libs
Java	Processing	Java JVM	all	any Java
Android	Java	Android	many	Android Java
p5.js	JavaScript	browser	no	p5.js libraries, potentially anything in JavaScript
p5py	Python 3	Python 3	no	Python 3
Python	Python 2	Jython/JVM	many	any Java, pure Python 2
R	R	Renjin/JVM	many	any Java, some R

Differences in how and where a mode runs affect how that mode can access other Processing code or language libraries. p5.js runs in JavaScript, so it can interact natively with other JavaScript libraries developed for the web--but it cannot use Processing contributed libraries developed in Java, as they will not run in a browser JavaScript engine. By contrast, the Python and R modes run as Java, so they can load many of the same Java libraries that are available for the default Processing mode. However, unlike p5.js these modes are limited in what libraries they can use from their "native" language: Python mode's Jython interpreter can import most "pure" (uncompiled) Python 2 packages without compiled dependencies, while R mode's Renjin maintains a list compatible R packages. Compiled libraries, scientific libraries, and libraries with many dependencies tend not to work.

Note: some libraries are published for multiple modes, with e.g. a Java mode and p5.js version.

Where to Put Modes

PDE Contributions Manager automatically places downloaded and installed modes inside the Processing folder in a folder named modes. You may also install modes directly by unzipping them to Processing/modes. This can be useful during development for testing. You may need to restart PDE to detect a manually installed mode.

Creating Your Own Mode

Documentation on how to author and build a mode is currently incomplete.

Mode developers currently learn by examining the structure and layout existing modes on their public code repositories.

• processing-p5js-mode
• processing.py
• Proceesing.R

There is also a mode template for PDE 3.

If you are building your own mode, Eclipse is the recommended development environment. It's not possible to build modes from within the Processing application. Like libraries, creating a mode with the PDE will cause problems because the JAR file exported from the PDE will contain the current version of the processing.core classes, which will cause major conflicts when trying to use the PDE. Modes that contain processing packages in this manner will have to be rejected or removed from the site. Use an IDE such as Eclipse for to build new modes.

How mode distribution works

On startup PDE Contributions Manager checks the internet for update sources.conf information. It then uses the source entry line, such as:

169 \ https://py.processing.org/3/PythonMode.txt

...and downloads the listed mode properties txt file. It uses the information in this file to display the mode in the Contributions Manager and to check for updates against any currently installed mode version. For example, here are the name and version number from PythonMode.txt

name = Python Mode for Processing 3
version = 3056

When the user clicks "Download" on a mode, the Contribution Manager looks for a zip file with the same path / name as the properties file, but a ".zip" extension:

https://py.processing.org/3/PythonMode.zip

PDE then downloads, the mode, unzips it, verifies it as valid, and installs it into the folder Processing/Modes/PythonMode. The mode is now installed in PDE.

When the mode is updated, Contributions Manager detects a new version available (generally on restart) when it re-downloads PythonMode.txt and notes that the version has changed. It marks the mode in Contributions Manager as available for update.

Distributing a Mode through PDE Contributions Manager

In order for modes to be distributed via PDE Contributions Manager, the mode must:

1. define properties by creating a mode properties txt file, e.g. mymode.txt
2. build and package the mode in a zip file with an identical name, e.g. mymode.zip
3. release the mode by uploading both files to the same public URL directory.
4. list in PDE by submitting the .txt URL to Processing for listing in the PDE file sources.conf

For an existing example, see Python mode:

• the properties .txt file URL: https://py.processing.org/3/PythonMode.txt
• the mode .zip file URL: https://py.processing.org/3/PythonMode.zip
• the sources.conf line: "169 \ https://py.processing.org/3/PythonMode.txt"

To update a mode, update the txt and zip. No changes need be made to sources.conf.

1. Define properties: the properties .txt file

This enables discovery, download, and update of your mode through PDE. Each time you release a new version of your mode, you must update the properties file in order to notify PDE Contributions Manager that a new update is available.

A properties .txt file looks like this:

name = Python Mode for Processing 3
authorList = [Jonathan Feinberg](http://MrFeinberg.com/)
url = https://github.com/jdf/processing.py
sentence = Write Processing sketches in Python.
paragraph =
version = 3056
prettyVersion = 3056
minRevision = 246
maxRevision = 

The file may be hand-edited. However, many modes generate them automatically at build time. For example, Python mode uses a mode.properties template file which is filed out during the build process, e.g. using Eclipse.

2. Build and package: the mode .zip file

This is the downloadable and installable release of your mode. It is created during your build process, e.g. using Eclipse.

Documentation on how to author and build a mode is currently incomplete.

3. Release: publishing the mode

In order to publish your mode (and update it thereafter) in a way that is compatible with PDE discovery, you may upload your latest txt and zip file to any public URL, so long as they have the same exact name/path with different extensions.

For this example, we will assume:

• You have created a public repo https://github.com/foo/mymode/
• You have written your mode, it builds, and it can be locally installed in PDE
• You are using a GitHub repo and GitHub releases for your public URLs -- although this could be any web server.

To publish your mode, whether the first time or as an update:

1. build your mode, creating build artifacts mymode.txt and mymode.zip
2. use git tag to tag your release commit with a semantic version number, e.g. v1.0
3. push the tag/commit to GitHub
4. create a release
   • on github.com, navigate to releases in your repo -- e.g. https://github.com/foo/mymode/releases -- and begin creating a new release
   • select the tag, e.g. v1.0
   • attach the two build artifacts to the release: mymode.txt and mymode.zip
   • publish the release

Your mode is now available via two URLs:

• https://github.com/foo/mymode/releases/tag/v1.0
• https://github.com/foo/mymode/releases/latest/

...and those have two corresponding download URLs:

• https://github.com/foo/mymode/releases/download/v1.0.7/mymode.txt
• https://github.com/foo/mymode/releases/download/latest/mymode.txt

This second URL is stable -- it always refers to whatever the attachment on the latest release. That will be important for later listing in PDE.

To update your mode, follow the numbered steps above again. Your new release will have a new tag and release URL, e.g. v1.1, but it will also be available at GitHub latest, replacing the old release. You do not need to submit any changes to sources.conf after your first release -- all future updates to your public .txt + .zip URLs will be automatically discovered by PDE Contributions Manager, generally on PDE restart.

List in PDE: appearing in the Contributions Manager for install

Once you have published your stable mode properties .txt URL, send your static links to the Processing Librarian: Elie Zananiri. We'll review your properties file to make sure everything is in order and add your contribution to the list of advertised libraries. New listings are discovered by PDE Contributions Manager -- generally on restart -- and available for download.

Note: Submitting your mode for listing in PDE only needs to be done once, the very first time you publish your mode--not every time you make a new release. All future updates to your public .txt + .zip will be automatically discovered by PDE Contributions Manager through that listing, although the may require a PDE restart to be detected.