Library Guidelines

Tip

To develop a library for Processing, the Library Template is a great starting point. It simplifies the setup process and helps you avoid many common pitfalls.

Once you're ready to publish your library, submit it through the GitHub issue form for new contributions.

Requirements

Each library contribution should include the following:

• Examples – People learn best from examples, so we encourage you to include code examples in your library release. Provide short, well-commented examples to illustrate basic functionality, and include demos to help users understand the potential of your library.

• Properties File – To show information about your library in the PDE's Contribution Manager, you need to provide a library.properties file. This file contains the full name of your library, a brief summary of its purpose, and other information. For more details, please read the Library Basics page.

• Home Page – A Processing library should have its own web page, stored at a stable URL (or at least as stable as possible). We recommend using GitHub Pages and the official Library Template. The template includes a basic MkDocs setup and a script to deploy it automatically to GitHub Pages. Your library's home page should include:

  • A brief abstract describing the purpose of your library.
  • A list of examples showcasing the library’s functionality.
  • Some tutorials that demonstrate potential use cases (optional).
  • A list of systems (macOS, Windows, Linux) and versions on which the library was successfully tested.
  • The latest Processing version the library has been tested with (e.g., Processing 4.3).
  • Dependencies, if any (e.g., other libraries or frameworks required by your library).
  • Keywords that describe the library’s purpose and features.
  • The date of the latest update.
  • A link to a .zip file containing the library, documentation, and examples.

• Documentation – We recommend using Javadoc-style comments in your library code since it is the most common way to document a Java API. You can use the Deploy - Publish Javadoc GitHub action or any number of other tools that can convert code with Javadoc-style comments into a practical reference. The documentation should be stored in a folder named reference, and include an index.html file that is the starting point. The reference should be updated with each new release.

• Source Code – We strongly encourage including the source code in your library releases (if you’re using GitHub, this is the default). Only libraries with source code will be featured on processing.org/reference/libraries. Sharing your source code helps the community grow and ensures that your library can continue to live on even if you’re no longer maintaining it yourself.

• License – Include a license file in your library distribution to specify how your library can be used and shared. For example, GPL-2.0-or-later. For an overview of some popular open-source licenses, see https://choosealicense.com/licenses/

Library Naming Rules

Warning

Do not use "Processing" as a prefix in the name of your library.

However, if your library is a Processing port of or a bridge to another framework, you can use a name like “XXX for Processing.”

For example:

• ❌ "Processing Box2D" is not allowed.
• ✅ "Box2D for Processing" is acceptable.

Additionally, classes should not be prefixed with P the way that the core Processing classes are (PImage, PGraphics, etc). We'd like to reserve that naming for “official” things that are inside processing.core and other associated classes.

Same goes for using Processing, Pro, or P5, whether it's a prefix or a suffix.

Similarly, please don't use processing as the prefix for your library packages. We need to keep that name space clear for official things as well.

Release Artifacts

Note

If you use the official Library Template, the following files will be created for you by the release workflow. If you’re hosting your library on your own domain, please follow the guidelines below.

Below is the required structure for hosting the release artifacts of a Processing library. These files must be accessible at stable URLs.

For example, if your library is called myLibrary and the latest version is at https://mywebsite.com/releases/latest/ the following links should be valid:

• https://mywebsite.com/releases/latest/myLibrary.zip
• https://mywebsite.com/releases/latest/myLibrary.txt
• https://mywebsite.com/releases/latest/myLibrary.pdex

Important

All release artifacts must have the same base name (differing only by extension) and be hosted in the same directory.

Description of Files

1. myLibrary.zip file

   • Contains the compiled library, documentation, and examples.

2. myLibrary.txt file

   • A direct copy of the library.properties file but with the name changed to myLibrary.txt (assuming your library is called myLibrary)
   • Provides metadata such as the library's name, version, author, and dependencies.
   • Required for library submission and indexing in Processing’s Contribution Manager.

3. myLibrary.pdex file

   • Identical to the .zip file but with a .pdex extension.
   • Enables direct installation via the Processing IDE using a pde:// link.
     Example: pde://https://mywebsite.com/releases/latest/myLibrary.pdex (read more about the pde:// protocol)

Folder Structure

Note

If you use the official Library Template, this folder structure is already set up for you. If you’re building your library from scratch, please follow the guidelines below.

Libraries should be distributed as zipped files, and the distribution should be laid out as follows:

• theLibrary/library/theLibrary.jar
• theLibrary/reference/
• theLibrary/examples/
• theLibrary/src/
• theLibrary/library.properties

The reference folder contains the documentation in HTML format as generated from Javadoc, the examples folder contains a set of sketches that help to understand the usage and functionality of the library. The library only contains the library's JAR file (and if necessary, any additional .jar, .dll, .so, or .jnilib files). Anything that is found inside the library folder will be exported with your sketch. The src folder contains the source. The name "src" is used because that's the default for Eclipse (and presumably other IDEs).

Following the folder structure is important because it simplifies documentation, and makes it easier for users to know what to expect. It also means that your reference pages can automatically be added to the Help menu in the PDE, and your library examples will automatically be added to the Examples menu. By placing your library in a .zip file and following the structure above, it enables future possibilities for automatic installation and library updates.

Avoid .DS_Store files on macOS

Be sure to remove .DS_Store files created by macOS before posting your library. These files are unnecessary and can clutter your distribution.

To prevent .DS_Store files from being included in your repository, add the following line to your .gitignore file:

.DS_Store

You can also remove existing .DS_Store files from your folders using the Terminal.app with the following command:

find YourFolderName -name .DS_Store -delete

Make sure to specify your folder name correctly. Avoid using / or anything that might delete .DS_Store files across your entire disk.

Alternatively, you can create a .zip file without .DS_Store files by running:

zip -r theLibrary.zip theLibrary -x "*.DS_Store"