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
-### Java 11 JDK
+> The versions and installation methods here are just suggestions (which we have tested
+so are known to work). If you need or wish to use different implementations (particularly
+you might need a bespoke JDK if you are on an exotic architecture) then the general
+build instructions should work with any gradle 5+. You should be able to compile the
+bytecode with any JDK Java 11+. The resulting bytecode (in particular the shadow jar)
+should be runnable in any JRE Java 1.8+. Remember that because Jalview and the getdown launcher
+are Java bytecode you can build on one system where you might have gradle, and run
+on another where you don't (JRE 1.8+ required).
+
+### Java 11 compliant JDK
#### All platforms
We recommend obtaining an OpenJDK JDK 11 (since 11 is the long term support release) from AdoptOpenJDK: <https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot>, either the *Installer* or `.zip`/`.tar.gz` variants whichever you prefer (if you're not sure, choose the *Installer*).
-You can also install adoptopenjdk11 using either `brew` (macOS) or `choco` (Windows):
-
-#### alternative MacOS/Homebrew
-```
-brew tap adoptopenjdk/openjdk
-brew cask install adoptopenjdk11
-```
-
-#### alternative Windows/Chocolatey
-```
-choco install adoptopenjdk11
-```
-
-#### alternative Linux/yum|apt
-
-see <https://adoptopenjdk.net/installation.html#linux-pkg>
+>##### Alternative/CLI install of AdoptOpenJDK 11
+>
+>You can also install adoptopenjdk11 using either `brew` (macOS), `choco` (Windows)
+(see the section on `gradle` and `git` for more informaiton on `brew` and `choco`)
+or `yum` or `apt` (Linux):
+>
+>###### alternative for MacOS and Homebrew
+>```
+>brew tap adoptopenjdk/openjdk
+>brew cask install adoptopenjdk11
+>```
+>
+>###### alternative for Windows and Chocolatey
+>```
+>choco install adoptopenjdk11
+>```
+>
+>###### alternative for Linux with yum/apt
+>
+>see <https://adoptopenjdk.net/installation.html#linux-pkg>
### gradle and git
-You should be able to install the latest (or close to the latest) versions of gradle and git using your OS package manager.
+You should be able to install the latest (or sufficiently recent) versions of gradle and git using your OS package manager.
#### MacOS
we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
brew install gradle git
```
-or
+or if you aready have them installed but need to upgrade the version:
```bash
brew upgrade gradle git
```
-if you already have them installed but need to upgrade the version.
-
#### Windows
we suggest using the **Chocolatey** package manager. See install instructions at <https://chocolatey.org/>, and you will just need
### What's in the source tree?
-Within the `jalview` folder:
-
-| dir/ file | contains|
-|------------|---------|
-| `bin/` | used by eclipse for compiled classes
-| `build/` | the gradle build dir
-| `classes/` | contains the compiled Java classes for the Jalview application
-| `dist/` | assembled `.jar` files needed to run Jalview application
-| `examples/`| example input files usable by Jalview
-| `getdown/` | the libraries used by the Javliew launcher (getdown)
-| `getdown/src/` | our modified source for `getdown`
-| `getdown/website/` | the assembled "download" folder used by getdown for downloads/upgrades
-| `getdown/files/` | the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application
-| `j8lib/` | libraries needed to run Jalview under Java 1.8
-| `j11lib/` | libraries needed to run Jalivew under Java 11
-| `resource/`| non-java resources used in the Jalview application
-| `src/` | the Jalview application source `.java` files
-| `test/` | Test class source files
-| `utils/` | helper applications used in the build process
-| `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
+Jalview is a mature product with its codebase going back many years. As such it doesn't
+have a folder structure that most new gradle projects would have, so you might not
+find everything in the place you might expect. Here's a brief description of what
+you might find in the main folders under the `jalview` tree.
+
+Within the `jalview` folder you will find (of possible interest):
+
+ dir/ or file | contains
+---------------------|----------------------------------------------------------------------------------------------------------------
+ `bin/` | used by eclipse for compiled classes -- no need to touch this
+ `build/` | the gradle build dir
+ `classes/` | contains the compiled Java classes for the Jalview application
+ `dist/` | assembled `.jar` files needed to run Jalview application
+ `examples/` | example input files usable by Jalview
+ `getdown/` | the libraries used by the Javliew launcher (getdown)
+ `getdown/src/` | our modified source for `getdown`
+ `getdown/website/` | the assembled "download" folder used by getdown for downloads/upgrades
+ `getdown/files/` | the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application
+ `help/` | the help documents
+ `j8lib/` | libraries needed to run Jalview under Java 1.8
+ `j11lib/` | libraries needed to run Jalivew under Java 11
+ `resource/` | non-java resources used in the Jalview application
+ `src/` | the Jalview application source `.java` files
+ `test/` | Test class source files
+ `utils/` | helper applications used in the build process
+ `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
Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
```
in the `gradle.properties` file.
-> *You may want to see some of the properties you can easily change at the end of this document.*
+> *You may want to see some of the other properties you can change at the end of this document.*
### Minimal Jalview Build
classpath argument wildcard interpreted by `java`, **not** a shell expansion wildcard interpreted
by the shell.*
-Note that `jalview.bin.Launcher` is a simplified launch class that re-launches `jalview.bin.Jalview`
-with the same classpath and arguments, but with an automatically determined `-Xmx...`
-memory setting.
+Note that `jalview.bin.Launcher` is a simplified launcher class that re-launches `jalview.bin.Jalview`
+with the same JRE (*not* the same JVM instance), classpath and arguments, but with an automatically determined `-Xmx...`
+memory setting if one hasn't been provided.
### Jalview in a Jar File
### Single *shadow* Jar File
-The shadow jar file is a single `.jar` that contains all required classes -- from `jalview.jar`
+The shadow jar file is a single `.jar` that contains all required classes and resources from `jalview.jar`
and all of the supporting libraries in `j11lib/*.jar` merged into one `.jar` archive
file. A default launching class (`MAIN-CLASS: jalview.bin.Launcher`) is specified in the `.jar`
manifest file (`META/MANIFEST.MF`) so a start class doesn't need to be specified.
unzip) as a `-jar` argument so you may find you can launch `jalview-all-11.jar`
just by double-clicking on it)!
-> The shadow jar file represents probably the simplest way to distribute the Jalview application, to machines that already have a Java 11 installed,
+> The `shadowJar` task is not a requirement for any other task, so to build the shadow
+jar file you must specify the `shadowJar` task.
+
+> The shadow jar file represents probably the simplest way to distribute the Jalview application to machines that already have a Java 11 installed,
although without the many and compelling benefits of the `getdown` launcher.
>
>```bash
>cd getdown/src/getdown
->mvn packages
+>mvn clean package -Dgetdown.host.whitelist="jalview.org,*.jalview.org"
>```
> and you will find the required `.jar` files in `core/target/gradle-core-XXX.jar`
-and `launcher/target/gradle-launcher-XXX.jar`. The `gradle-core.jar` should be copied
-to both the `j11lib` folder to `getdown/lib`, whilst the `gradle-launcher.jar` only
+and `launcher/target/gradle-launcher-XXX.jar`. The `gradle-core.jar` should then be copied
+to all three of the `j8lib`, `j11lib` and `getdown/lib` folders, whilst the `gradle-launcher.jar` only
needs to be copied to `getdown/lib`.
+>
+>The `mvn` command should ideally include the `-Dgetdown.host.whitelist=*.jalview.org` setting.
+ This, and the necessary file copying commands, can be found in `getdown/src/getdown/mvn_cmd`.
To assemble Jalview with `getdown` use the following gradle task:
gradle test
```
-These normally take around 5 - 10 minutes to complete and outputs its results into
-the `tests/` folder.
+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*
in `build.gradle` file to point to your installation of *install4j* and also to bundled
JREs if you want to bundle those into the installers.
-If you want more details, get in touch on our development mailing list at <http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev>.
+If you want more details, get in touch on our development mailing list <jalview-dev@jalview.org>.
+Sign up at <http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev>.
## Building in Eclipse
>
`TestNG Eclipse Composite P2 Repo - http://beust.com/eclipse-beta`
>
-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
a selection box under the *Name* column.
Select *TestNG* and carry on through the
install process to install the TestNG plugin.
-After installing the plugins, it is good to get Java 11 set up in Eclipse as the default JRE.
+After installing the plugins, it is a good to get Java 11 set up in Eclipse as the default JRE.
-To do this go to Preferences (Eclipse->Preferences in macOS, and File->Preferences
-on Windows or Linux) and find
+To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences
+on Windows or Window->Preferences on Linux) and find
Java -> Installed JREs
and then click on the *Next >* button.
In the following options, it is the *Project Root Directory* you should set to be the
-`jalview` folder that git downloaded. Then you can click on the *Finish* button.
\ No newline at end of file
+`jalview` folder that git downloaded. Then you can click on the *Finish* button.
+
+
+## Gradle properties
+
+There are a lot of properties configured in `gradle.properties` which we strongly recommend
+being left as they are unless you have a specific problem with the build process.
+
+There are a few gradle properties you might want to set on the command line with the
+`-P` flag when building a version of Jalview with specific requirements:
+
+#### `JAVA_VERSION`
+This changes the *target* java bytecode version
+> NOTE that you will need to use a Java 11 (or greater) JDK Java compiler to build
+Jalview for any byte-code target version.
+
+Valid values are `11` and `1.8`.
+
+e.g.
+
+```bash
+gradle shadowJar -PJAVA_VERSION=1.8
+```
+
+When using `-PJAVA_VERSION=1.8` the libraries from `j8lib` (instead of `j11lib`) will be used in the compile
+and runtime classpath and also used in the `makeDist` build step. Where a Java version of `11` is used in folder and file names, it will
+instead use `1.8`. Also if you are building installer packages with *install4j* the
+package builder will look for JRE 1.8 bundles to package in the installers.
+
+> Note that continued development of Jalview will assume a Java 11+ runtime environment,
+the 2.11.0 release will run under a Java 1.8 JRE with a few minor features disabled.
+
+#### `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 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-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=SCRATCH-my_test_version
+```
+
+#### `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.
+
+Currently the valid values are
+`linuxDeb`,
+`linuxRPM`,
+`macosArchive`,
+`unixArchive`,
+`unixInstaller`,
+`windows`
+
+The default value is all of them.
+
+e.g.
+```bash
+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.
+
+
+---
+[Jalview Development Team](mailto:help@jalview.org)
git://source.jalview.org / jalview.git / blobdiff