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

Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.






and then you can build the Jalview jar file using gradle.