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