Documentation

processing · Stefterv · Mar 7, 2025 · Nov 14, 2024 · Nov 14, 2024 · Nov 14, 2024
commit b89efed0334f0d1f8dad740570da522f41c9e0bd
diff --git a/.gitignore b/.gitignore
@@ -109,3 +109,4 @@ java/build/
 /java/preprocessor/build
 /java/lsp/build
 /.kotlin/sessions
+/core/examples/build
diff --git a/BUILD.md b/BUILD.md
@@ -0,0 +1,60 @@
+# How to Build Processing
+
+Great to see you are interested in contributing to Processing. To get started you will need to have an IDE to build and develop Processing. Our recommendation and what we use ourselves is Intellij IDEA.
+
+## IntelliJ IDEA
+
+First, [download the IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/). Make sure to select the "Community Edition", not "Ultimate". The Community Edition is free and built on open-source software. You may need to scroll down to find the download link. Then:
+
+1. Clone the Processing4 repository to your machine locally
+1. Open the cloned repository in IntelliJ IDEA CE
+1. In the main menu, go to File > Project Structure > Project Settings > Project.
+1. In the SDK Dropdown option, select a JDK version 17 or Download the jdk
+1. Click the green Run Icon in the top right of the window. This is also where you can find the option to debug Processing. 
+1. Logs can be found in the `Build` or `Debug` pane on the bottom left of the window
+
+
+## VSCode
+1. Clone the Processing4 repository to your machine locally
+1. Open the cloned repository in VScode
+1. Wait for Gradle to set up the repository
+1. (If you want debugging install [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) and [Java Extension Pack](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)) 
+1. Go to the Gradle Tab and click app -> Tasks -> compose desktop -> run
+
+Instructions for other editors are welcome and feel free to contribute the documentation for those [here](#other-editors)
+
+
+## Architecture
+Processing is build of three distinct parts, the `Core`, `Java` and the `App`. The `Core` currently stands alone and `Java` and `App` depend on it. `Java` and `App` are currently interdependent but we are working on decoupling those two.
+
+`Core`: The part of the code that gets bundled with your sketches, so the functionality like `ellipse(25,25,50,50);` The inner workings of that function can be found here.
+
+`Java`: This is the pipeline that will take your `.pde` file and compile and run it. The PDE understands different _modes_ with `Java` being the primary one.
+
+`App`: This is the PDE, the visual part of the editor that you see and work within when you use Processing.
+
+### Examples
+
+- You want to fix a bug with one of the argument of a function that you use in a sketch. The `Core` is probably where you would find the implementation of the function that you would like to modify.
+- A feature/bug of the PDE editor has been driving you nuts, and  you can no longer stand it. You would probably find your bug in the `App` section of this project.
+- You've written a large sketch and Processing has become slow to compile, a place to improve this code can probably be found in the `Java` section.
+
+## User interface
+Traditionally Processing has been written in Java swing and Flatlaf (and some html & css). Since 2025 we have switched to include Jetpack Compose, for a variety of reasons but mostly for it's inter-compatibility. There were ideas to switch to a React based editor, but this approach allows us to slowly replace Java swing components to Jetpack Compose, Ship of Theseus style.   
+
+## Build system
+
+We use `Gradle` as the build system for Processing. This used to be `Ant` but we have switched to be more in line with modern standards and to hopefully switch the internal build system in the `Java` mode to `Gradle` as well, unifying both systems for simplicity.
+
+## Kotlin vs Java
+Since introducing the Gradle build system we also support Kotlin within the repository. Refactors from Java to Kotlin are not really necessary at this stage, but all new functionality should be written in Kotlin.
+
+Any classes that end in `..Kt.Java` are there for backwards compatibility with the `Ant` build system and can be removed when that is no longer necessary. 
+
+### Running Processing
+
+The main task to run or debug the PDE is `app:run` this run the application with `compose desktop`
+
+If your main concern is with the `Core` you don't need to start the whole PDE to test your changes. In IntelliJ IDEA you can select any of the sketches in `core/examples/src/.../` to run by click on the green arrow next to their main functions. This will just compile core and the example sketch. Feel free to also new examples for your newly added functionality.
+
+## Other editors
diff --git a/README.md b/README.md
@@ -30,12 +30,12 @@ While we assume good intentions, and will give everyone a chance to learn, we ha
 Building Processing locally on your machine will let you troubleshoot and make sure your contributions work as intended before submitting them to this repository. It also gives you the flexibility to experiment and learn more about how Processing is structured.
 
 For a quick start: 
-1. Fork and clone the repository.
-1. Open it in IntelliJ IDEA.
-1. Install the required [Ant plugin](https://plugins.jetbrains.com/plugin/23025-ant).
-1. Hit Run.
+1. Fork and clone the repository
+1. Open it in IntelliJ IDEA
+1. Wait for Gradle to sync
+1. Hit Run
 
-For more information and detailed instructions, follow our [How to Build Processing](build/README.md) guide.
+For more information and detailed instructions, follow our [How to Build Processing](BUILD.md) guide.
 
 ## Contact Information
 For technical support or troubleshooting with your project, please post on the [Processing Forum](https://discourse.processing.org/).

diff --git a/app/README.md b/app/README.md
@@ -0,0 +1,12 @@
+# Processing `App`
+
+This is the PDE, the visual part of the editor that you see and work within when you use Processing.
+
+## Important classes
+
+The main class of this project is the `src/.../Base.java` this is where the PDE starts after the splash screen.
+
+The `ui/Editor.java` class is the class that is instantiated to show an editor window of the PDE.
+
+`Mode.java` is the class that any mode within Procesing inherits from.
+
diff --git a/build/README.md b/build/README.md
@@ -1,5 +1,7 @@
 # How to Build Processing
 
+This folder contains files for the legacy `Ant` build system. This build system will be removed in the future when we're sure we no longer need it.
+
 ## IntelliJ IDEA CE
 
 First, [download the IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/). Make sure to select the "Community Edition", not "Ultimate". The Community Edition is free and built on open-source software. You may need to scroll down to find the download link. Then:

diff --git a/core/README.md b/core/README.md
@@ -1,4 +1,9 @@
-# Including the Processing Core library on your project
+# Processing Core
+
+`Core` contains the implementations of all the functionality that you would use within a Processing sketch, e.g. `size()` and `ellipse()` 
+
+
+## Including the Processing Core library on your project
 Processing’s core libraries are available through [Maven Central](https://central.sonatype.com/artifact/org.processing/core).  
 This allows integration of Processing into Java-based projects using build tools like Maven or Gradle.
 
@@ -56,6 +61,13 @@ dependencies {
   implementation group: 'org.processing', name: 'core', version: '4.3.1'
 }
 ```
+
+## Developing for Core
+The easiest way to develop for core, without the need to build the whole project, is to use the `examples/src` sketches. In 
+
+## PGraphics Modes
+Documentation on how to develop graphics modes as a library should go here. 
+
 ### Other
 Other example snippets on including the library are included in the [Maven Central repo](https://central.sonatype.com/artifact/org.processing/core).  
 Please look up on how to add the custom https://jogamp.org/deployment/maven repository to your build system.

diff --git a/java/README.md b/java/README.md
@@ -0,0 +1,20 @@
+# Processing Java Mode
+
+This the Java Mode in Processing. It compiles your sketches and runs them. It is the primary mode of Processing.
+
+## Folders
+- `application` assets for exporting applications within the mode
+- `generated` generated antlr code for the mode, should be moved to a proper `antlr` plugin within gradle
+- `libraries` libraries that are available within the mode
+- `lsp` gradle build system for the language server protocol, in the future we should decouple the lsp from the java mode and pde and move all relevant code here. For now it can be found in `src/.../lsp`
+- `mode` legacy files for `Ant`
+- `preprocessor` the preprocessor for the mode, same deal as with the lsp, although the decoupling has mostly been done
+- `src` the main source code for the mode
+- `test` tests for the mode
+- `theme` assets for the mode, related to autocomplete and syntax highlighting
+
+## Future plans
+- Decouple the `lsp` and `preprocessor` from the mode and move them to their own repositories
+- Move the `antlr` code to a proper plugin within gradle
+- Create a gradle plugin to convert `.pde` file to `.java` files
+- Create a gradle based version of Java mode.