From 19cb2eab37ddf738c73a8e5c6eed4e1091e610bf Mon Sep 17 00:00:00 2001 From: Ben Soares Date: Fri, 7 Jun 2019 18:13:11 +0100 Subject: [PATCH] JAL-3248 Almost completed building doc --- build.gradle | 1 + doc/building.md | 269 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 257 insertions(+), 13 deletions(-) diff --git a/build.gradle b/build.gradle index c2c4599..e143b80 100644 --- a/build.gradle +++ b/build.gradle @@ -642,6 +642,7 @@ task cleanDist { } shadowJar { + group = "distribution" dependsOn makeDist from ("$jalviewDir/$libDistDir") { include("*.jar") diff --git a/doc/building.md b/doc/building.md index b47c648..2f1dd86 100644 --- a/doc/building.md +++ b/doc/building.md @@ -126,24 +126,267 @@ Jalview build-tree in the folder `jalview`. 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* +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 . + + +## 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: + +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 -- 1.7.10.2