* gradle 5.1 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.
### 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. 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`.
+
+e.g.
+```bash
+gradle getdown -PCHANNEL=DEVELOPMENT
+```
+
+#### `MEDIA_TYPES`
+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 -PMEDA_TYPE=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
git://source.jalview.org / jalview.git / blobdiff