JAL-3594 Documentation added to building.md for using the utils/channels/... folders

diff --git a/doc/building.md b/doc/building.md
index d2544f7..f2d832a 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -409,17 +409,25 @@ looks to see if there's an updated file) to point to a particular Jalview channe
 place to look for required files.  If the selected channel type requires the getdown `appbase` to be a local
 directory on the filesystem (instead of a website URL) then a modified version of the `getdown-launcher.jar` will
 be used to allow this.  The two versions of the `getdown-launcher.jar` can be found in `getdown/lib`.
+Note that the DEVELOP and RELEASE channels will normally use a getdown-launcher.jar that *does not* allow the
+`file://` scheme to be used in the appbase.
+
 Some other variables used in the build process might also be set differently depending on the value of `CHANNEL`
 to allow smooth operation of getdown in the given context.
 
-There are several values of `CHANNEL` that can be chosen, with a default of `LOCAL`.  Here's what they're for and what they do:
+There are several values of `CHANNEL` that can be chosen, with no choice leading to a default of `LOCAL`.
+Here's what they're for and what they do:
 
-* `LOCAL`: This is for running the compiled application from the development directory.
+* `LOCAL`: This is for running the compiled application from the development directory and used by default.
   It will set
-    - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION`
-      (e.g. `file://home/user/git/jalview/getdown/files/11`)
+    - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION`
+      (e.g. `file://home/user/git/jalview/getdown/website/11`)
     - application subdir as `alt`
     - Getdown launcher can use a `file://` scheme appbase. 
+    - Compile jalview with `gradle getdown` or `gradle shadowJar`
+    - Run Jalview on the command line without using the installers with,
+      Using getdown, e.g. `java -jar ./getdown/files/11/getdown-launcher.jar ./getdown/files/11 jalview`
+      or using the shadowJar with, e.g. `java -jar ./build/libs/jalview-all-TEST-j11.jar`
 * `BUILD`: This is for creating an appbase channel on the build server by an automatic or manually started build.
   It will set
     - `appbase` as `https://builds.jalview.org/browse/${bamboo_planKey}/latest/artifact/shared/getdown-channel/JAVA_VERSION`
@@ -469,6 +477,22 @@ e.g.
 gradle getdown -PCHANNEL=SCRATCH-my_test_version
 ```
 
+**New `CHANNEL` appearance features 2020-12-10**
+There are now differing cosmetics for different channels, including application icons, Getdown splashscreen,
+About splashscreen, Installer backgrounds, application name.  This is controlled by the files in
+```
+utils/channels
+```
+In `utils/channels` there are different directories for the different channels.  Currently there are directories for
+`develop`, `release`, `test-release` and `default`.  If a specified `CHANNEL` is not one of `DEVELOP`, `RELEASE` or `TEST-RELEASE`
+then it will use the `default` directory.
+
+Inside the `utils/channels/<channelname>` directory are:
+- a file `channel_gradle.properties`.  This will be used by the `build.gradle` script (i.e. any gradle build) to *override* the values found in `gradle.properties`.
+- an `images` directory used to store different images referred to in this channels's `channel_gradle.properties`.
+- a `resources` directory which is merged into the javliew.jar's own resources directory.  Importantly it contains a `channel_properties` file and another `images` dir which contains properties and images used by the application (in `jalview.util.ChannelProperties`), such as icon files or banner images, and the `app_name` property used as the display name for the application (e.g. "Jalview Develop") inside the application code.  Please see the `getProperty` and `getImage` methods in `jalview.bin.ChannelProperties` to access these channel based resources. 
+
+
 #### JALVIEW_VERSION and the RELEASE file
 Any Jalview build will include the value of JALVIEW_VERSION in various places, including the 'About' and Jalview Desktop window title, and in filenames for the stand-alone executable jar. You can specify a custom version for a build via the JALVIEW_VERSION property, but for most situations, JALVIEW_VERSION will be automatically configured according to the value of the CHANNEL property, using the `jalview.version` property specified in the RELEASE file:
   - `CHANNEL=RELEASE` will set version to jalview.version