Building Processing for Android
The build system of Processing for Android is entirely based on Gradle (Ant support was removed because there are many critical steps, particularly related to dependency resolution, that cannot be easily implemented with Ant), and it includes Android Studio sample projects for developing and testing the core, VR, and any other Android-specific libraries. Eclipse projects for the Android mode and the SDK Updater tool are also provided.
The build system uses gradle to build processing core and mode, the VR and AR libraries, and the SDK Downloader tool, and to create the Android mode package ready to use.
The first step is to install the Android SDK. This can be done manually with the command line tools available at the bottom of this page under the "Command line tools only" section, where you can download the one corresponding to the Operating System you are using (Windows, Mac, or Linux). Unzip the zip file and move the contents of the resulting cmdline-tools folder into <path to SDK>/cmdline-tools/latest. For example (on Mac, and replacing with the correct version number and SDK folder):
unzip commandlinetools-mac-6858069_latest.zip
mkdir ~/android-devel/SDK
mkdir ~/android-devel/SDK/cmdline-tools
mv cmdline-tools ~/android-devel/SDK/cmdline-tools/latest
One the command lines tools are placed in the SDK location, you can use the sdkmanager to download the necessary components of the SDK:
cd ~/android-devel/SDK/cmdline-tools/latest/bin
./sdkmanager "platform-tools" "platforms;android-33"
Then, create a local.properties file in the root folder of the repo with the following contents:
sdk.dir=<path to Android SDK>
In the case the previous examples, should be ~/android-devel/SDK/ but you can use any other location of your preference. If you are on Windows, use either double back slashes "\" as the file separator, or forward slashes "/" (Unix-style). Otherwise, the build process will fail. Alternatively, the build script will try to create this file automatically if the ANDROID_SDK environmental variable is defined in the system.
Once a valid local.properties is available, you can build the Android mode distribution by running:
gradle dist
This assumes you have Gradle version 7 (version 8 is not yet supported) available system-wide (binary releases can be downloaded from here), alternatively you can use the Gradle wrapper, which is included with the mode:
./gradlew dist
This will download all the required files to proceed with the build and distribution process.
If the build process of all modules concludes successfully, the AndroidMode.zip and the AndroidMode.txt files will be stored inside the dist subfolder.
Clean all build files with:
gradle clean
or
./gradlew clean
Note that the ant build scripts are no longer provided to build the mode or core library.
Import the folder debug into Android Studio, okay the Gradle Sync dialog that shows next, and wait for Android Studio to download all the dependencies. You should get a project space where you can run the provided sample apps (simple and vrcube), add new apps, and modify and debug the core and vr libraries. The processing-core and processing-vr Android library projects simply point to the source folders in core/src and mode/libraries/vr/src, so any changes in the source code files in those locations will affect the sample apps.
The Android mode is a Java project that can be developed from a Java IDE such as Eclipse or IntelliJ. The Eclipse project files are included, and the steps required to get the mode to run from Eclipse are as follows:
Since we only require Processing 4 as a dependency, perform a shallow clone of the Processing 4 repo and build it by running ant in the processing/build folder, as detailed in the build instructions for Processing 4:
git clone https://github.com/processing/processing4.git --depth 1
- Import the Processing 4 repo into Eclipse: Import > Projects from Git > Existing local repository > Select Processing folder > Import existing eclipse project
- Select:
- processing-app
- processing-core
- processing-java (Select the option with path processing/java)
- Right click the processing-app project and select Run As > Java Application > “Base - processing.app”
- Build the processing for Android distribution using gradle, and then Import the Processing for Android repo into Eclipse: Import > Projects from Git > Existing local repository > Select Processing folder > Import existing eclipse project
- Select:
- android-mode
- android-mode-sdkupdater
- Right click the android-mode package > Build Path > Configure Build Path
- Add the classpath variables ANDROID_SDK and ANDROID_JAR, and set the first to the path of your Android SDK, and the second to the android.jar file located in the platforms/android-xx folder of the SDK (where xx is the Android API level).
- Add/Edit the Run Configuration to the processing-app needed to load the Android mode from the development repository:
- Right click on the processing-app project, and select Run As...|Run Configurations
- Create a new run configuration or edit the existing configuration, making sure it has processing-app as the project, and processing.app.Base as the main class.
- In the arguments tab, enter
-Dusemode=processing.mode.android.AndroidMode:${resource_loc:/android-mode}as VM arguments.
- Every time there is a change in the mode source (or in the core or VR libraries) you need to repackage the mode before running from Eclipse. To do so, run the “gradle dist” command in the processing-android root folder, as discussed in the before.
- Start processing-app from the run menu. The Android Mode should now be present in the Mode menu.
- In order to run a debug session including breakpoints in the source code, add the processing and processing-android folders in the Source tab of Run Configurations dialog.
- You could create a new builder that runs gradle dist every time the android-mode project is built by Eclipse. This is done by going to the project's properties, then to the Builders option and select New. There, you should set the working directory as the location of local processing-android repo, browse for the gradlew command to use in Location, and add dist as argument. This builder should be moved up before the default Java Builder.
The Android mode source can be imported into a new IntelliJ project quite easily. As with Eclipse, we need to clone the Processing 4 repo first. Then:
- Import the repo into IntelliJ: Import Project > Select Processing 4 folder > Import from external model (Eclipse) See the section Import a project with settings in the IntelliJ online documentation for more info.
- In the “Select Eclipse projects to import” window, select
- processing-app
- processing-core
- processing-java
- Goto Run > Edit Configurations and create a new Application configuration.
- Choose Java Application.
- Set “Main class” to “Base (processing.app)”
- And “Use classpath of module” to “processing-app”
- Go to File > Project Structure > Modules > Add > Import Module > Select Processing-Android folder > Import module from external model (Eclipse) > Select mode project projects only
- Rename the mode module as android-mode, you may also need to fix some of the autogenerated module dependencies in IntelliJ (such as JDK or libraries) to make sure that there are no dependency errors.
- Go to File > Settings > Appearance & Behaviour > Path Variables and set the ANDROID_SDK and ANDROID_JAR variable’s (create if not present) values to your Android SDK path and the android.jar file located in the platforms/android-xx folder of the SDK (where xx is the Android API level), respectively. Also create a new variable called ANDROID_MODE (or anything you want) and set its value to
<path to processing-android repo>/mode. - Run the "gradle dist" command in the processing-android folder to build the core library and the mode.
- Set the VM options parameter of the run configuration to
-Dusemode=processing.mode.android.AndroidMode:$VAR$. Replace VAR with the variable you created in step 2 (e.g.: ANDROID_MODE). - Run the project. The Android Mode should now be present in the Mode menu.
- The "gradle dist" step can be made it automatically by check the 'Before launch' section for your run config.
These are some special tasks that only need to be run occasionally to update the Gradle wrapper included in the repo, or the Android permissions supported by the mode.
Run the following command to update the bundled Gradle wrapper:
gradle wrapper --gradle-version 6.5
(replacing 6.5 by the version of Gradle you want to update to). Then, you have to commit the new Gradle wrapper files to the repo. If no version is provided, then the gradle-wrapper version in the mode/versions.properties file is used instead.
Add --rerun-tasks to the command if the Gradle says that the task is up-to-date and refuses to update.
First make sure to install required dependencies to run this target with:
pip install -r mode/scripts/requirements.txt
and then:
gradle permissions