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.
* Java 11 compliant JDK
-* gradle 5.1 or above
+* gradle 5.2 or above
* git
> The versions and installation methods here are just suggestions (which we have tested
These normally take around 5 - 10 minutes to complete and outputs its full results into
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
+```
+
+Available groups are Functional (default), Network, External.
+
### Installer packaging with *install4j*
#### `CHANNEL`
This changes the `appbase` setting in `getdown.txt` (`appbase` is where the getdown launcher
-looks to see if there's an updated file) to point to a particular Jalview
-channel. Expected values are `FILE`, `STABLE`, `DEVELOPMENT`, or a specific version
-of Jalview like `2.11` or `2.10.5`.
-
-A value of `FILE` behaves differently to the other expected values and will use a local
-file-system scheme URI instead of a Jalview release channel. This `file:` scheme URI
-uses an absolute path to the `getdown/website/<JAVA_VERSION>`
-
-On a regular development machine, this property will default to `LOCAL`.
+looks to see if there's an updated file) to point to a particular Jalview channel or some other appropriate
+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`.
+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:
+
+* `LOCAL`: This is for running the compiled application from the development directory.
+ It will set
+ - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION`
+ (e.g. `file://home/user/git/jalview/getdown/files/11`)
+ - application subdir as `alt`
+ - Getdown launcher can use a `file://` scheme appbase.
+* `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`
+ 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.
+ It will set
+ - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
+ - application subdir as `alt`
+ - Getdown launcher cannot use a `file://` scheme appbase.
+* `SCRATCH-NAME`: This is for creating a temporary scratch appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels. The value of `NAME` can be any "word-character" [A-Za-z0-9\_]
+ It will set
+ - `appbase` as `http://www.jalview.org/getdown/SCRATCH-NAME/JAVA_VERSION`
+ - application subdir as `alt`
+ - Getdown launcher cannot use a `file://` scheme appbase.
+* `TEST-LOCAL`: Like `SCRATCH` but with a specific `test-local` channel name and a local filesystem appbase. This is meant for testing an over-the-air update on the local filesystem. An extra property `LOCALDIR` must be given (e.g. `-PLOCALDIR=/home/user/tmp/test`)
+ It will set
+ - `appbase` as `file://${LOCALDIR}`
+ - application subdir as `alt`
+ - Getdown launcher can use a `file://` scheme appbase.
+* `TEST-RELEASE`: Like `SCRATCH` but with a specific `test-release` channel name. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels.
+ It will set
+ - `appbase` as `http://www.jalview.org/getdown/test-release/JAVA_VERSION`
+ - application subdir as `alt`
+ - Getdown launcher cannot use a `file://` scheme appbase.
+* `RELEASE`: This is for an actual release build, and will use an appbase on the main web server with the main `release` channel name. 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/release/JAVA_VERSION`
+ - application subdir as `release`
+ - Getdown launcher cannot use a `file://` scheme appbase.
+* `ARCHIVE`: This is a helper to create a channel for a specific release version, and will use an appbase on the main web server with a specific `archive/JALVIEW_VERSION` channel name. This won't become live until the actual getdown artefact is synced to the web server.
+You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
+ It will set
+ - `appbase` as `http://www.jalview.org/getdown/archive/JALVIEW_VERSION/JAVA_VERSION`
+ - application subdir as `alt`
+ - Getdown launcher cannot use a `file://` scheme appbase.
+* `ARCHIVELOCAL`: Like `ARCHIVE` but with a local filesystem appbase for local testing.
+You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
+ It will set
+ - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION` (where the old jars will have been copied and digested)
+ - application subdir as `alt`
+ - Getdown launcher can use a `file://` scheme appbase.
e.g.
```bash
-gradle getdown -PCHANNEL=DEVELOPMENT
+gradle getdown -PCHANNEL=SCRATCH-my_test_version
```
-#### `MEDIA_TYPES`
+#### `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.
e.g.
```bash
-gradle installers -PJAVA_VERSION=1.8 -PMEDA_TYPE=macosArchive
+gradle installers -PJAVA_VERSION=1.8 -Pinstall4jMediaTypes=macosArchive
```
To get an up-to-date list of possible values, you can run
```bash
perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j/install4j_template.install4j | sort -u
```
-in the `jalview` root folder.
\ No newline at end of file
+in the `jalview` root folder.
+
+
+## Enabling Code Coverage with OpenClover
+
+Bytecode instrumentation tasks are enabled by specifying 'true' (or just a non-whitespace non-numeric word) in the 'clover' property. This adds the 'openclover' plugin to the build script's classpath, making it possible to track code execution during test which can be viewed as an HTML report published at build/reports/clover/index.html.
+
+```gradle -Pclover=true test cloverReport```
+
+#### Troubleshooting report generation
+
+The build forks a new JVM process to run the clover report generation tools (both XML and HTML reports are generated by default). The following properties can be used to specify additional options or adjust JVM memory settings. Default values for these options are:
+
+##### JVM Memory settings - increase if out of memory errors are reported
+
+```cloverReportJVMHeap = 2g```
+
+##### -Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.
+
+```cloverReportJVMArgs = -Dfile.encoding=UTF-8```
+
+##### Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database
+
+```cloverReportHTMLOptions = ```
+
+##### -v for verbose, -d for debug level messages (as above)
+
+```cloverReportXMLOptions = ```
+
+
+_Note_ do not forget to include the -Dfile.encoding=UTF-8 option: this is essential for some platforms in order for Clover to correctly parse some Jalview source files that contain characters that are UTF-8 encoded.
+
+
+---
+[Jalview Development Team](mailto:help@jalview.org)
git://source.jalview.org / jalview.git / blobdiff