From 89465d8abd0f97aee57b1f650835bd8ecf8741d6 Mon Sep 17 00:00:00 2001 From: Ben Soares Date: Mon, 10 Jun 2019 11:38:40 +0100 Subject: [PATCH] JAL-3248 Building from source documentation in markdown and converted to HTML --- doc/building.html | 1074 ++++++++++++++++++++++++++++++++++++++++++- doc/building.md | 217 ++++++--- doc/convert.sh | 2 + doc/github.css | 662 ++++++++++++++++++++++++++ getdown/src/getdown/mvn_cmd | 2 +- 5 files changed, 1874 insertions(+), 83 deletions(-) create mode 100644 doc/convert.sh create mode 100644 doc/github.css diff --git a/doc/building.html b/doc/building.html index 7114fa3..615f8ba 100644 --- a/doc/building.html +++ b/doc/building.html @@ -1,29 +1,1059 @@ - - - - - - - - - + + + + + + + Building Jalview from Source + + + + + + +

Building Jalview from Source

What you will need

tl;dr

# download
+git clone http://source.jalview.org/git/jalview.git
+# compile
+cd jalview
+gradle shadowJar
+# run
+java -jar build/libs/jalview-all-11.jar
+
+# and/or create launcher
+gradle getdown
+# use launcher
+cd getdown/files
+java -jar getdown-launcher.jar . jalview

Setting up

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
git

Java 11 JDK

We recommend obtaining an OpenJDK JDK 11 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).

`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.

For macOS we recommend using brew, which can be installed following the instructions at https://brew.sh/. After installing brew, open a Terminal window and type in (using an Administrator privileged user): brew install gradle git or brew upgrade gradle git if you already have them installed but need to upgrade the version.

For linux this will depend on which distribution you’re using. For debian based distributions (e.g. Mint, Ubuntu, Debian) run sudo apt-get install gradle git whilst for RPM-based distributions run (probably) sudo yum install gradle git If you have some other version of linux you’ll probably be able to work it out!

For Windows users, you might do well by using the Chocolatey package manager. See install instructions at https://chocolatey.org/, and you will just need choco install gradle git Alternatively, you could install a real bash shell and install both gradle and git through apt-get. Another alternative would be to install them separately following the instructions at https://gradle.org/install/, and for git here are a couple of suggestions: Git for Windows https://gitforwindows.org/ or a real bash-shell https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/ !

- - \ No newline at end of file +

+
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).

+
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 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/. After installing brew, open a Terminal window and type in (using an Administrator privileged user):

brew install gradle git

or if you aready have them installed but need to upgrade the version:

brew upgrade gradle git

Windows

we suggest using the Chocolatey package manager. See install instructions at https://chocolatey.org/, and you will just need

choco install gradle
+choco install git

Alternatively, you could install a real bash shell and install both gradle and git through apt-get. See https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/ for how to install the ubuntu bash shell in Windows 10.

Another alternative would be to install them separately. For gradle follow the instructions at https://gradle.org/install/, and for git here are a couple of suggestions: Git for Windows https://gitforwindows.org/. Getting the individual installs working together on the command line will be trickier so we recommend using Chocolatey or bash.

Linux

this will depend on which distribution youâre using.

For Debian based distributions (e.g.Â Mint, Ubuntu, Debian)

run

 sudo apt-get install gradle git

for RPM-based distributions (e.g.Â Fedora, CentOS, RedHat)

run

sudo yum install gradle git

If you have some other version of linux youâll probably be able to work it out!

Downloading the Jalview source tree

This can be done with git. On the command line, change directory to where you want to download Jalviewâs build-tree top level directory. Then run

git clone http://source.jalview.org/git/jalview.git

Youâll get some progress output and after a minute or two you should have the full Jalview build-tree in the folder jalview.

Whatâs in the source tree?

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.

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 other properties you can change at the end of this document.
+

Minimal Jalview Build

To compile the necessary class files, just run

gradle compileJava

to compile the classes into the classes folder. You should now be able to run the Jalview application directly with

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

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 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

To package the classes, resources, and help into one jar, you can run

gradle jar

which assembles the Jalview classes and resources into dist/jalview.jar

To run this, use

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

gradle makeDist

which puts all required jar files into dist so you can run with

java -cp "dist/*" jalview.bin.Jalview

Single shadow Jar File

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.

Build the shadow jar file in build/lib/jalview-all-11.jar with

gradle shadowJar

and run it with

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 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.
+

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
+
cd getdown/src/getdown
+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 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 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

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

gradle test

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

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

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 jalview-dev@jalview.org. Sign up 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:

Buildship Gradle Integration 3.0 (or greater)
Groovy Development Tools 3.4.0 (or greater)
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 a good to get Java 11 set up in Eclipse as the default JRE.

To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences on Windows or Window->Preferences on 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.

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.

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.

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.

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.

gradle installers -PJAVA_VERSION=1.8 -PMEDA_TYPE=macosArchive

To get an up-to-date list of possible values, you can run

perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j/install4j_template.install4j  | sort -u

in the jalview root folder.

+ + diff --git a/doc/building.md b/doc/building.md index 2f1dd86..75c38e1 100644 --- a/doc/building.md +++ b/doc/building.md @@ -27,31 +27,44 @@ The method here is described in terms of using a command line. You can easily d * 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: , 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,8 @@ 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. ### Installer packaging with *install4j* @@ -321,7 +344,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 +378,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 +386,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 +413,77 @@ 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. \ No newline at end of file diff --git a/doc/convert.sh b/doc/convert.sh new file mode 100644 index 0000000..fbfa17d --- /dev/null +++ b/doc/convert.sh @@ -0,0 +1,2 @@ +#!/usr/bin/env bash +pandoc -s -o building.html building.md --metadata pagetitle="Building Jalview from Source" --toc -H github.css diff --git a/doc/github.css b/doc/github.css new file mode 100644 index 0000000..9018d8a --- /dev/null +++ b/doc/github.css @@ -0,0 +1,662 @@ + diff --git a/getdown/src/getdown/mvn_cmd b/getdown/src/getdown/mvn_cmd index d984902..0ce786f 100644 --- a/getdown/src/getdown/mvn_cmd +++ b/getdown/src/getdown/mvn_cmd @@ -1 +1 @@ -mvn clean package -Dgetdown.host.whitelist=jalview.org,*.jalview.org && cp launcher/target/getdown-launcher-1.8.3-SNAPSHOT.jar ../../../getdown/lib/getdown-launcher.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../getdown/lib/getdown-core-1.8.3-SNAPSHOT.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../j8lib/getdown-core.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../j11lib/getdown-core.jar +mvn clean package -Dgetdown.host.whitelist="jalview.org,*.jalview.org" && cp launcher/target/getdown-launcher-1.8.3-SNAPSHOT.jar ../../../getdown/lib/getdown-launcher.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../getdown/lib/getdown-core-1.8.3-SNAPSHOT.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../j8lib/getdown-core.jar && cp core/target/getdown-core-1.8.3-SNAPSHOT.jar ../../../j11lib/getdown-core.jar -- 1.7.10.2

Building Jalview from Source

What you will need

tl;dr

Setting up

Java 11 JDK

gradle and git

Java 11 compliant JDK

All platforms

Alternative/CLI install of AdoptOpenJDK 11

alternative for MacOS and Homebrew

alternative for Windows and Chocolatey

alternative for Linux with yum/apt

gradle and git

MacOS

Windows

Linux

For Debian based distributions (e.g.Â Mint, Ubuntu, Debian)

for RPM-based distributions (e.g.Â Fedora, CentOS, RedHat)

Downloading the Jalview source tree

Whatâs in the source tree?

Building Jalview

Minimal Jalview Build

Jalview in a Jar File

Distributed Jar Files

Single shadow Jar File

Building the getdown launcher

Running tests

Installer packaging with install4j

Building in Eclipse

Gradle properties

JAVA_VERSION

CHANNEL

MEDIA_TYPES

`gradle` and `git`

Whatâs in the source tree?

Building the `getdown` launcher

`JAVA_VERSION`

`CHANNEL`

`MEDIA_TYPES`