X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=doc%2Fbuilding.md;h=b47c6488f6e520b168b114d12a91d55331222533;hb=7902f34ff30893572065d9225d397e5c88b853f0;hp=ae76ced787bd67cdad176104a40fb80a05e58bb9;hpb=f7ee28904ba53bbc34858612a2598fbdf10b3049;p=jalview.git

diff --git a/doc/building.md b/doc/building.md
index ae76ced..b47c648 100644
--- a/doc/building.md
+++ b/doc/building.md
@@ -5,16 +5,21 @@
 ```
 # download
 git clone http://source.jalview.org/git/jalview.git
-#compile
+# compile
 cd jalview
-gradle getdown
+gradle shadowJar
 # run
-cd getdown/files/11
-java -jar gradle-launcher.jar . jalview
+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
 ```
 
 
-## What you will need
+## 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.
 
@@ -23,60 +28,86 @@ The method here is described in terms of using a command line.  You can easily d
 * 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*).
+
+#### 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.
 
-#### For **macOS**
+#### 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.
 
-#### For **linux**
+#### 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 (probably)
+run
 
-```
+```bash
 sudo yum install gradle git
 ```
 
 If you have some other version of linux you'll probably be able to work it out!
 
 
-#### For **Windows**
-
-we suggest 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`.
-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/>.
 
 ## Downloading the Jalview source tree
 
@@ -84,23 +115,31 @@ 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?
+### What's in the source tree?
 
-Change directory into the `jalview` folder:
+Within the `jalview` folder:
 
-```
-cd jalview
-```
-and you'll find most of the Jalview source files under `src`. Some important resource 
-files can be found under `resources`.  The helper jar libraries can currently be found 
-in `j8lib` for Java 1.8 runtime and `j11lib` for Java 11 runtime.
+|  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.