cleaning up the build script and making notes about download size and tradeoffs

Author: benfry

README.md

@@ -1,7 +1,18 @@
 # `FX2D`
 
-This repository contains the JavaFX renderer for Processing 4, also known as `FX2D`. 
+This repository contains the JavaFX renderer for Processing 4, also known as `FX2D`.
 
 The JavaFX binaries have grown very large in size so this was a necessary step to avoid making the Processing download excessively large, given that not everyone uses JavaFX. More discussion/explanation [here](https://github.com/processing/processing4/issues/348).
 
-This version of the JavaFX library will be required for `FX2D` sketches starting with 4.0 beta 4.
+This version of the JavaFX library will be required for `FX2D` sketches starting with 4.0 beta 4.
+
+
+## Download Size
+
+The build script creates a very large download (hundreds of megabytes), because Processing supports several platforms (3 officially, 3 more unofficially) and we want to make it easy to use all of them. This is an acceptable tradeoff for a standalone library like this, but if you want a smaller build, you have options:
+
+1. Disable `<antcall target="retrieve-gluon">` stanzas for platforms you don't care about.
+
+2. Un-comment the `<!-- <exclude name="**/*jfxwebkit.*" /> -->` line so that the WebKit library is removed.
+
+These are not done by default because we've seen projects that (1) run on all those platforms, and (2) use the full browser implementation available with the WebKit support. Again, because this is an optional download, this seems the correct tradeoff.

build.xml

@@ -110,7 +110,8 @@ ${line.separator}with the path to where you have the code for Processing 4 check
         <include name="**/*.so" />
 
         <!-- The webkit library might be skipped because it is massive.
-             Remove libjfxwebkit.dylib, libjfxwebkit.so, jfxwebkit.dll -->
+             Un-comment this line for a smaller build. It will remove
+             libjfxwebkit.dylib, libjfxwebkit.so, jfxwebkit.dll -->
         <!-- <exclude name="**/*jfxwebkit.*" /> -->
 
         <!-- Not using this either, but since we're using 'include',
@@ -127,52 +128,43 @@ ${line.separator}with the path to where you have the code for Processing 4 check
   <target name="download-javafx">
     <property name="gluon.version" value="17.0.2" />
 
+    <!-- Retrieves all six of our (un)officially supported platforms.
+         You can comment some of these out if you'd like a smaller build. -->
+
     <antcall target="retrieve-gluon">
-      <!-- <param name="platform.zip" value="javafx-${gluon.version}-macos" /> -->
       <param name="platform.name" value="osx" />
       <param name="platform.arch" value="x64" />
-      <!-- <param name="platform.path" value="${library.path}/macos-x86_64" /> -->
       <param name="platform.variant" value="macos-x86_64" />
     </antcall>
 
     <antcall target="retrieve-gluon">
-      <!-- <param name="gluon.base" value="javafx-${gluon.version}-macos" /> -->
       <param name="platform.name" value="osx" />
       <param name="platform.arch" value="aarch64" />
       <param name="platform.variant" value="macos-aarch64" />
-      <!-- <param name="platform.path" value="${library.path}/macos-aarch64" /> -->
     </antcall>
 
     <antcall target="retrieve-gluon">
-      <!-- <param name="gluon.base" value="javafx-${gluon.version}-windows" /> -->
       <param name="platform.name" value="windows" />
       <param name="platform.arch" value="x64" />
       <param name="platform.variant" value="windows-amd64" />
-      <!-- <param name="platform.path" value="${library.path}/windows-amd64" /> -->
     </antcall>
 
     <antcall target="retrieve-gluon">
-      <!-- <param name="gluon.base" value="javafx-${gluon.version}-linux" /> -->
       <param name="platform.name" value="linux" />
       <param name="platform.arch" value="x64" />
       <param name="platform.variant" value="linux-amd64" />
-      <!-- <param name="platform.path" value="${library.path}/linux-amd64" /> -->
     </antcall>
 
     <antcall target="retrieve-gluon">
-      <!-- <param name="gluon.base" value="javafx-${gluon.version}-linux" /> -->
       <param name="platform.name" value="linux" />
       <param name="platform.arch" value="arm32" />
       <param name="platform.variant" value="linux-arm" />
-      <!-- <param name="platform.path" value="${library.path}/linux-arm" /> -->
     </antcall>
 
     <antcall target="retrieve-gluon">
-      <!-- <param name="gluon.base" value="javafx-${gluon.version}-linux" /> -->
       <param name="platform.name" value="linux" />
       <param name="platform.arch" value="aarch64" />
       <param name="platform.variant" value="linux-aarch64" />
-      <!-- <param name="platform.path" value="${library.path}/linux-aarch64" /> -->
     </antcall>
   </target>