benfry · benfry · Jan 7, 2020 · Dec 4, 2019 · Dec 26, 2019 · Dec 26, 2019
diff --git a/README.md b/README.md
@@ -1,15 +1,21 @@
-This is an experimental fork to attempt the move to JDK 11. Because that's a major, API-breaking change, it would be Processing 4.
+Processing 4
+==============================
+Processing 4 is an exciting next step for Processing in which the internals of the software will see important updates, helping prepare the platform for its future. This includes the move to JDK 11 and support for new Java language features. There are likely going to be major API-breaking changes in addition to Java 11 so this release would be Processing 4.
 
-I'm working with Sam Pottinger to incorporate [his changes](https://github.com/sampottinger/processing4) to see if that can be the basis for this new release. Getting things moved to OpenJDK 11 will help the longevity of the project.
+<br>
 
-**It's not clear if we'll ship an actual Processing 4.0**, because I have less free time than ever, and very little development help. If you'd like to help, contribute bug fixes.
+Note from Ben
+------------------------------
+I'm working with [Sam Pottinger](https://github.com/sampottinger) to incorporate his changes to see if that can be the basis for this new release. Getting things moved to OpenJDK 11 will help the longevity of the project.
 
-Ben Fry, 4 October 2019
+It's not clear if we'll ship an actual Processing 4.0, because I have less free time than ever, and very little development help. If you'd like to help, contribute bug fixes.
 
----
+Ben Fry, 4 October 2019
 
-## API changes
+<br>
 
+API changes
+------------------------------
 As with all releases, I'll do everything possible to avoid breaking API. However, there will still be tweaks that have to be made. We'll try to keep them minor.
 
-* `Base.defaultFileMenu` is now `protected` instead of `static public`
+* `Base.defaultFileMenu` is now `protected` instead of `static public`
diff --git a/build/README.md b/build/README.md
@@ -0,0 +1,188 @@
+Processing Build Instructions
+==============================
+The following instructions describe how to build and release Processing across Windows, OS X, and Linux.
+
+<br>
+<br>
+
+
+Local Environment Setup
+------------------------------
+Processing's ant-based build chain can create executables natively runnable for Linux, Mac, and Windows.
+
+<br>
+
+**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.
+
+<br>
+
+**Getting Java and Ant**  
+You can choose to install these yourself or use the following guides below:
+
+ - [Instructions for installing Java](https://adoptopenjdk.net/installation.html?variant=openjdk11&jvmVariant=hotspot#x64_mac-jdk)
+ - [Instructions for installing Ant](http://ant.apache.org/manual/install.html)
+ - Instructions for modifying your environment variables on [windows](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/), [ mac](https://medium.com/@himanshuagarwal1395/setting-up-environment-variables-in-macos-sierra-f5978369b255) and [linux](https://www.cyberciti.biz/faq/set-environment-variable-linux/).
+
+<br>
+
+**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
+```
+
+<br>
+<br>
+
+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. Before continuing, please be aware that you are agreeing to the [license terms](https://github.com/sampottinger/processing/blob/master/LICENSE.md) and that the developers do not make any guarantee or warranty (implicit or express) for any purpose.
+
+<br>
+
+**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](https://openjdk.java.net/) and [OpenJFX](https://openjfx.io/) will be downloaded with their binaries copied into the distribution. If building for the first time, these automated downloads from [AdoptOpenJDK](https://adoptopenjdk.net/) and [Gluon](https://gluonhq.com/) may take some time.
+
+Note that one may need to "clean" via `ant linux-clean` or equivalent.
+
+<br>
+
+**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.
+
+<br>
+
+**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
+
+<br>
+<br>
+
+Automated Tests
+------------------------------
+Unit tests are available by running the test target:
+
+```
+$ cd [path to processing repository]
+$ cd build
+$ ant test
+```
+
+These tests are not executed by default when running the `build` target but are recommended for developers contributing to the project.
+
+<br>
+<br>
+
+Running
+------------------------------
+The build can be run directly or through Ant.
+
+<br>
+
+**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.
+
+<br>
+
+**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`.
+
+<br>
+<br>
+
+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.
+
+<br>
+
+**Available targets:**  
+
+ - macosx-dist
+ - windows-dist
+ - linux-dist
+
+One can also use `ant dist` to distribute for the host OS.
+
+<br>
+
+**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.
+
+<br>
+
+**Code Signing**  
+At present, only Mac builds require code signing to avoid an ["App Gateway"](https://support.apple.com/en-us/HT202491) 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](https://developer.apple.com/developer-id/).
+
+This is not strictly required especially if you are using your own app build.