JAL-4192 more specific info about versions needed

[jalview.git] / doc / building.md

diff --git a/doc/building.md b/doc/building.md
index 3122efb..81700ac 100644 (file)
--- a/doc/building.md
+++ b/doc/building.md
@@ -5,16 +5,16 @@
 ```
 # download
 git clone http://source.jalview.org/git/jalview.git
-# compile
-cd jalview
-gradle shadowJar
+# compile - needs java 11 JDK
+cd ./jalview
+gradle shadowJar  # needs to be gradle 7.6.3 or above (but not gradle 8)
 # run
 java -jar build/libs/jalview-all-*-j11.jar
 
 # and/or create launcher
 gradle getdown
 # use launcher
-cd getdown/files
+cd ./build/getdown/files/11
 java -jar getdown-launcher.jar . jalview
 ```
 
@@ -23,10 +23,10 @@ java -jar getdown-launcher.jar . jalview
 
 > To get set up using _only_ the Eclipse IDE (<https://www.eclipse.org/>) then please see the section [Setting up in Eclipse IDE](#setting-up-in-eclipse-ide) 
 
-The method here is described in terms of using a command line.  You can easily do this on linux or in a Terminal window in macOS.  You can do it in Windows.
+The method here is described assumes using a command line.  You can easily do this on linux or in a Terminal window in macOS.  You can do it in Windows.
 
 * Java 11 compliant JDK
-* gradle 5.2 or above *(NB gradle 6.6 and above currently produces NullPointerExceptions during the build. This is non-fatal and does not affect the build. Use gradle 6.5.1 to avoid this)*
+* gradle 7.6.3 or above, but not gradle 8 
 * git
 
 > The versions and installation methods here are just suggestions (which we have tested 
@@ -336,7 +336,7 @@ the `tests/` folder.  A summary of results should appear in your console.
 You can run different defined groups of tests with
 
 ```bash
-gradle test -PtestngGroups=Network
+gradle test -Ptestng_groups=Network
 ```
 
 Available groups include Functional (default), Network, External. 
@@ -348,9 +348,15 @@ Some of Jalview's Functional tests don't pass reliably in all environments. We t
 To exclude one or more groups of tests, add them as a comma separated list in testngExcludedGroups.
 
 ```bash
-gradle test -PtestngExcludedGroups=Not-bamboo
+gradle test -Ptestng_excluded_groups=Not-bamboo
 ```
+#### Viewing stdout and stderr for tests
+
+By default, gradle doesn't report any of the output or error streams produced by tests. You can enable output by setting the following:
 
+```bash
+gradle test -Ptest_output=1
+```
 
 ### Installer packaging with *install4j*
 
@@ -484,7 +490,7 @@ About splashscreen, Installer backgrounds, application name.  This is controlled
 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`
+`default`, `develop`, `release`, `test-release`, `jalviewjs` and `jalviewjs-release`.  If a specified `CHANNEL` is not one of `DEVELOP`, `RELEASE`, `TEST-RELEASE`, `JALVIEWJS`, `JALVIEWJS-RELEASE`
 then it will use the `default` directory.
 
 Inside the `utils/channels/<channelname>` directory are:
@@ -495,8 +501,10 @@ Inside the `utils/channels/<channelname>` directory are:
 
 #### 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
+  - `CHANNEL=RELEASE` will set version to jalview.version.
+  - `CHANNEL=TEST or DEVELOP` will append '-test' or '-develop' to jalview.version.
+  - `CHANNEL=JALVIEWJS` will use the `channel.props` found in `utils/channels/jalviewjs` but otherwise uses `LOCAL` settings.
+  - `CHANNEL=JALVIEWJS-RELEASE` uses a symbolic link to `utils/channels/jalviewjs` but otherwise uses `RELEASE` settings.
   
 It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.