[jalview.git] / doc / building.md

# Building Jalview from Source

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

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


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

#### 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):

```bash
brew install gradle git
```

or

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

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

```bash
 sudo apt-get install gradle git
```

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

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

```bash
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?

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

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.

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.