Within the `jalview` folder:
-| dir | contains|
-|-----------|---------|
-| `src` | the Jalview application source `.java` files
-| `resource`| non-java resources used in the Jalview application |
-| `classes` (after compiling) | contains the compiled Java classes for the Jalview application
-| `bin` | used by eclipse for compiled classes
-| `j8lib` | libraries needed to run Jalview under Java 1.8
-| `j11lib` | libraries needed to run Jalivew under Java 11
-| `build` | the gradle build dir
-| `dist` | assembled `.jar` files needed to run Jalview application
-| `examples`| example input files usable by Jalview
-| |
+| 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
Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
+## Building Jalview
+You will need to have the Java 11 `javac` in your path, or alternatively you can configure
+gradle to know where this is by putting
+```
+org.gradle.java.home=/path_to_jdk_directory
+```
+in the `gradle.properties` file.
+
+> *You may want to see some of the properties you can easily change at the end of this document.*
+
+### Minimal Jalview Build
+
+To compile the necessary class files, just run
+
+```bash
+gradle compileJava
+```
+to compile the classes into the `classes` folder.
+You should now be able to run the Jalview application directly with
+
+```bash
+java -cp "classes:resources:help:j11lib/*" jalview.bin.Jalview
+```
+
+You can also run with an automatic large memory setting (which will set the maximum
+memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting
+(if possible in your OS) with
+
+```bash
+java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher
+```
+
+>*You must use just "`j11lib/*`" and not "`j11lib/*.jar`" as this is a special Java
+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.
+
+### Jalview in a Jar File
+
+To package the `classes`, `resources`, and `help` into one jar, you can run
+
+```bash
+gradle jar
+```
+which assembles the Jalview classes and resources into `dist/jalview.jar`
+
+To run this, use
+
+```bash
+java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
+```
+
+### Distributed Jar Files
+
+To simplify this, all required `.jar` files can be assembled into the `dist` folder
+using
+
+```bash
+gradle makeDist
+```
+which puts all required jar files into `dist` so you can run with
+
+```bash
+java -cp "dist/*" jalview.bin.Jalview
+```
+
+### Single *shadow* Jar File
+
+The shadow jar file is a single `.jar` that contains all required classes -- 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.
+
+Build the shadow jar file in `build/lib/jalview-all-11.jar` with
+
+```bash
+gradle shadowJar
+```
+and run it with
+
+```bash
+java -jar build/lib/jalview-all-11.jar
+```
+
+Because no arguments are required, most OSes will associate a `.jar` file with the
+`java` application (if this has been installed through the OS and not just a local
+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,
+although without the many and compelling benefits of the `getdown` launcher.
+
+
+### Building the `getdown` launcher
+
+We have made significant customisations to the `getdown` launcher which you can find
+in `getdown/src/getdown`.
+
+> You don't need to build this afresh as the required `gradle-core.jar`
+and `gradle-launcher.jar` files are already distributed in `j11lib` and `getdown/lib` but if you want to, then
+you'll need a working Maven and also a Java 8 JDK. Ensure the Java 8 `javac` is forefront
+in your path and do
+>
+>```bash
+>cd getdown/src/getdown
+>mvn packages
+>```
+> 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
+needs to be copied to `getdown/lib`.
+
+To assemble Jalview with `getdown` use the following gradle task:
+
+```bash
+gradle getdown
+```
+
+This puts all the necessary files to launch Jalview with `getdown`
+into `getdown/website/11/`. This could be treated as the reference folder
+for `getdown`, which is where a getdown launcher will check to see if the Jalview application
+files it has are up to date, and download if they aren't or it simply doesn't have
+them.
+
+A minimal getdown-launcher can be found in `getdown/files/11/` which checks its up-to-date
+status with (the absolute path to) `getdown/website/11/`.
+
+This can be launched with
+
+```bash
+java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
+```
+
+> We've already met the `-jar file.jar` arguments. The next argument is the working folder for
+getdown, and the final argument, "`jalview`", is a getdown application id (only "`jalview`"
+is defined here).
+
+
+### Running tests
+
+There are substantial tests written for Jalview that use TestNG, which you can run with
+
+```bash
+gradle test
+```
+
+These normally take around 5 - 10 minutes to complete and outputs its results into
+the `tests/` folder.
+
+
+### Installer packaging with *install4j*
+
+Jalview is currently using *install4j* <https://www.ej-technologies.com/products/install4j/overview.html>
+as its installer packaging tool.
+
+If you have a licensed installation of *install4j* you can build Jalview installers
+by running
+
+```bash
+gradle installers
+```
+
+though you may need to fiddle with the `install4j` and `copyInstall4jTemplate` tasks
+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>.
+
+
+## Building in Eclipse
+
+We develop in Eclipse, and support settings to develop and save Jalview source code
+in our preferred style. We also support running the Jalview application, debugging
+and running tests with TestNG from within Eclipse.
+
+To get Jalview set up as a project in Eclipse, we recommend using at least the 2019-03
+version of Eclipse IDE for Java Developers which you can download from the Eclipse
+website: <https://www.eclipse.org/downloads/>
+
+Once installed, we also recommend installing several plugins from the Eclipse Marketplace.
+
+To do so, launch Eclipse, and go to Help->Eclipse Marketplace...
+
+Search for and install:
+
+1. Buildship Gradle Integration 3.0 (or greater)
+1. Groovy Development Tools 3.4.0 (or greater)
+1. TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)
+
+> At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace
+as the latest released version does not install in Eclipse 2019-03.
+However, you can install a working beta of TestNG for Eclipse by going to
+>
+Help->Install New Software...
+>
+and entering
+>
+`TestNG Eclipse Composite P2 Repo - http://beust.com/eclipse-beta`
+>
+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.
+
+To do this go to Preferences (Eclipse->Preferences in macOS, and File->Preferences
+on Windows or Linux) and find
+
+Java -> Installed JREs
+
+If your Java 11 installation is not listed, click on
+
+*Add* -> Standard VM -> *Next*
+
+and enter the JRE home. You can browse to where it was installed. Give it a name (like "AdoptOpenJDK 11"). Select this JDK
+as the default JRE and click on *Apply and Close*.
+
+
+You can now import Jalview. It is important to import
+Jalview as a Gradle project (not as a Java project), so go to
+
+File->Import...
+
+find and select
+
+Gradle->Existing Gradle Project
+and then click on the *Next >* button.
-and then you can build the Jalview jar file using gradle.
+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
git://source.jalview.org / jalview.git / commitdiff