X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=doc%2Fbuilding.md;h=5f5fa6d398ff04a25c8e9a842291dbecbc83da29;hb=32ade06046b53861d495fbd4cc9f6ac92fd3cdd3;hp=2f1dd8672530a4e6ea6dd45bb1a0866bc0111a9d;hpb=19cb2eab37ddf738c73a8e5c6eed4e1091e610bf;p=jalview.git diff --git a/doc/building.md b/doc/building.md index 2f1dd86..5f5fa6d 100644 --- a/doc/building.md +++ b/doc/building.md @@ -24,34 +24,47 @@ java -jar getdown-launcher.jar . jalview 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: , 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 +>##### 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 ### 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 . @@ -61,14 +74,12 @@ After installing `brew`, open a Terminal window and type in (using an Administra 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 , and you will just need @@ -124,28 +135,34 @@ Jalview build-tree in the folder `jalview`. ### 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. @@ -160,7 +177,7 @@ 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.* +> *You may want to see some of the other properties you can change at the end of this document.* ### Minimal Jalview Build @@ -188,9 +205,9 @@ java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher 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 @@ -223,7 +240,7 @@ 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` +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. @@ -244,7 +261,10 @@ Because no arguments are required, most OSes will associate a `.jar` file with t 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. @@ -260,12 +280,15 @@ in your path and do > >```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: @@ -301,8 +324,16 @@ There are substantial tests written for Jalview that use TestNG, which you can r 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* @@ -321,7 +352,8 @@ though you may need to fiddle with the `install4j` and `copyInstall4jTemplate` t 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 . +If you want more details, get in touch on our development mailing list . +Sign up at . ## Building in Eclipse @@ -354,7 +386,7 @@ and entering > `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. @@ -362,10 +394,10 @@ 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 @@ -389,4 +421,81 @@ Gradle->Existing Gradle Project 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/` + +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. + + +--- +[Jalview Development Team](mailto:help@jalview.org)