doc/building.md

   1 # Building Jalview from Source
   2
   3 ## What you will need
   4
   5 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.
   6
   7 * Java 11 compliant JDK
   8 * gradle 5.1 or above
   9 * git
  10
  11 ### Java 11 JDK
  12 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*).
  13
  14 ### gradle and git
  15 You should be able to install the latest (or close to the latest) versions of gradle and git using your OS package manager.
  16
  17 #### For **macOS**
  18 we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
  19 After installing `brew`, open a Terminal window and type in (using an Administrator privileged user):
  20
  21 ```
  22 brew install gradle git
  23 ```
  24
  25 or
  26
  27 ```
  28 brew upgrade gradle git
  29 ```
  30
  31 if you already have them installed but need to upgrade the version.
  32
  33 #### For **linux**
  34 this will depend on which distribution you're using.
  35
  36 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
  37 run
  38
  39 ```
  40  sudo apt-get install gradle git
  41 ```
  42
  43 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
  44 run (probably)
  45
  46 ```
  47 sudo yum install gradle git
  48 ```
  49
  50 If you have some other version of linux you'll probably be able to work it out!
  51
  52
  53 #### For **Windows**
  54
  55 we suggest using the **Chocolatey** package manager.  See install instructions at <https://chocolatey.org/>, and you will just need
  56
  57 ```
  58 choco install gradle git
  59 ```
  60
  61 Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
  62 See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/>
  63 for how to install the ubuntu bash shell in Windows 10.
  64
  65 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/>.
  66
  67 ## Downloading the Jalview source tree
  68
  69 This can be done with `git`.
  70 On the command line, change directory to where you want to download Jalview's build-tree
  71 top level directory.  Then run
  72
  73 ```
  74 git clone http://source.jalview.org/git/jalview.git
  75 ```
  76
  77 You'll get some progress output and after a minute or two you should have the full
  78 Jalview build-tree in the folder `jalview`.
  79
  80 ## What's in the source tree?
  81
  82 Change directory into the `jalview` folder:
  83
  84 ```
  85 cd jalview
  86 ```
  87 and you'll find most of the Jalview source files under `src`. Some important resource
  88 files can be found under `resources`.  The helper jar libraries can currently be found
  89 in `j8lib` for Java 1.8 runtime and `j11lib` for Java 11 runtime.
  90
  91
  92
  93
  94
  95
  96 and then you can build the Jalview jar file using gradle.