doc/building.md

   1 # Building Jalview from Source
   2
   3 ## tl;dr
   4
   5 ```
   6 # download
   7 git clone http://source.jalview.org/git/jalview.git
   8 # compile
   9 cd jalview
  10 gradle shadowJar
  11 # run
  12 java -jar build/libs/jalview-all-11.jar
  13
  14 # and/or create launcher
  15 gradle getdown
  16 # use launcher
  17 cd getdown/files
  18 java -jar getdown-launcher.jar . jalview
  19 ```
  20
  21
  22 ## Setting up
  23
  24 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.
  25
  26 * Java 11 compliant JDK
  27 * gradle 5.1 or above
  28 * git
  29
  30 ### Java 11 JDK
  31
  32 #### All platforms
  33 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*).
  34
  35 You can also install adoptopenjdk11 using either `brew` (macOS) or `choco` (Windows):
  36
  37 #### alternative MacOS/Homebrew
  38 ```
  39 brew tap adoptopenjdk/openjdk
  40 brew cask install adoptopenjdk11
  41 ```
  42
  43 #### alternative Windows/Chocolatey
  44 ```
  45 choco install adoptopenjdk11
  46 ```
  47
  48 #### alternative Linux/yum|apt
  49
  50 see <https://adoptopenjdk.net/installation.html#linux-pkg>
  51
  52
  53 ### gradle and git
  54 You should be able to install the latest (or close to the latest) versions of gradle and git using your OS package manager.
  55
  56 #### MacOS
  57 we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
  58 After installing `brew`, open a Terminal window and type in (using an Administrator privileged user):
  59
  60 ```bash
  61 brew install gradle git
  62 ```
  63
  64 or
  65
  66 ```bash
  67 brew upgrade gradle git
  68 ```
  69
  70 if you already have them installed but need to upgrade the version.
  71
  72 #### Windows
  73
  74 we suggest using the **Chocolatey** package manager.  See install instructions at <https://chocolatey.org/>, and you will just need
  75
  76 ```bash
  77 choco install gradle
  78 choco install git
  79 ```
  80
  81 Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
  82 See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/>
  83 for how to install the ubuntu bash shell in Windows 10.
  84
  85 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/>.
  86 Getting the individual installs working together on the command line will be trickier
  87 so we recommend using Chocolatey or bash.
  88
  89
  90 #### Linux
  91 this will depend on which distribution you're using.
  92
  93 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
  94 run
  95
  96 ```bash
  97  sudo apt-get install gradle git
  98 ```
  99
 100 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
 101 run
 102
 103 ```bash
 104 sudo yum install gradle git
 105 ```
 106
 107 If you have some other version of linux you'll probably be able to work it out!
 108
 109
 110
 111
 112 ## Downloading the Jalview source tree
 113
 114 This can be done with `git`.
 115 On the command line, change directory to where you want to download Jalview's build-tree
 116 top level directory.  Then run
 117
 118 ```bash
 119 git clone http://source.jalview.org/git/jalview.git
 120 ```
 121
 122 You'll get some progress output and after a minute or two you should have the full
 123 Jalview build-tree in the folder `jalview`.
 124
 125 ### What's in the source tree?
 126
 127 Within the `jalview` folder:
 128
 129 |  dir      | contains|
 130 |-----------|---------|
 131 | `src`     | the Jalview application source `.java` files
 132 | `resource`| non-java resources used in the Jalview application |
 133 | `classes` (after compiling) | contains the compiled Java classes for the Jalview application
 134 | `bin`     | used by eclipse for compiled classes
 135 | `j8lib`   | libraries needed to run Jalview under Java 1.8
 136 | `j11lib`  | libraries needed to run Jalivew under Java 11
 137 | `build`   | the gradle build dir
 138 | `dist`    | assembled `.jar` files needed to run Jalview application
 139 | `examples`| example input files usable by Jalview
 140 | |
 141
 142 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
 143
 144
 145
 146
 147
 148
 149 and then you can build the Jalview jar file using gradle.