Merge branch 'merge_review/JAL-3490_2_11_2_develop' into develop

[jalview.git] / doc / building.md

diff --git a/doc/building.md b/doc/building.md
index 398181a..06e796d 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -165,6 +165,7 @@ Within the `jalview` folder you will find (of possible interest):
  `utils/install4j/`  | files used by the packaging tool, install4j
  `build.gradle`      | the build file used by gradle
  `gradle.properties` | configurable properties for the build process
+ `RELEASE`          | propertyfile configuring JALVIEW_VERSION (from jalview.version) and the release branch (from jalview.release). An alternative file can be specified via JALVIEW_RELEASE_FILE property
 
 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
 
@@ -422,7 +423,7 @@ There are several values of `CHANNEL` that can be chosen, with a default of `LOC
       Note that bamboo_planKey should be set by the build plan with `-Pbamboo_planKey=${bamboo.planKey}`
     - application subdir as `alt`
     - Getdown launcher cannot use a `file://` scheme appbase. 
-* `DEVELOP`: This is for creating a `develop` appbase channel on the main web server.  This won't become live until the actual getdown artefact is synced to the web server.
+* `DEVELOP`: This is for creating a `develop` appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server.
   It will set
     - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
     - application subdir as `alt`
@@ -465,6 +466,13 @@ e.g.
 gradle getdown -PCHANNEL=SCRATCH-my_test_version
 ```
 
+#### 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
+  - `CHANNEL=TEST or DEVELOP` will append '-test' or '-develop' to jalview.version
+  
+It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.
+
 #### `install4jMediaTypes`
 If you are building *install4j* installers (requires *install4j* to be installed) then this property specifies a comma-separated 
 list of media types (i.e. platform specific installers) *install4j* should actually build.
@@ -555,18 +563,18 @@ Search for and install:
 as the latest released version does not install in Eclipse 2019-03.
 However, you can install a working release of TestNG for Eclipse by going to
 >
-Help->Install New Software...
+> Help->Install New Software...
 >
-and entering
+> and entering
 >
-`TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release`
+> `TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release`
 >
-into the *Work with* box and click on the *Add...* button.
+> into the *Work with* box and click on the *Add...* button.
 >
-Eclipse might pause for a bit with the word *Pending* in the table below at this point, but it will eventually list TestNG with 
+> Eclipse might pause for a bit with the word *Pending* in the table below at this point, but it will eventually list TestNG with 
 a selection box under the *Name* column.
 >
-Select *TestNG* and carry on through the 
+> Select *TestNG* and carry on through the 
 install process to install the TestNG plugin.
 
 After installing the plugins, check that Java 11 is set up in Eclipse as the default JRE (see section [Java 11 compliant JDK](#java-11-compliant-jdk)).