1 # Building Jalview from Source
7 git clone http://source.jalview.org/git/jalview.git
12 java -jar build/libs/jalview-all-11.jar
14 # and/or create launcher
18 java -jar getdown-launcher.jar . jalview
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.
26 * Java 11 compliant JDK
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*).
35 You can also install adoptopenjdk11 using either `brew` (macOS) or `choco` (Windows):
37 #### alternative MacOS/Homebrew
39 brew tap adoptopenjdk/openjdk
40 brew cask install adoptopenjdk11
43 #### alternative Windows/Chocolatey
45 choco install adoptopenjdk11
48 #### alternative Linux/yum|apt
50 see <https://adoptopenjdk.net/installation.html#linux-pkg>
54 You should be able to install the latest (or close to the latest) versions of gradle and git using your OS package manager.
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):
61 brew install gradle git
67 brew upgrade gradle git
70 if you already have them installed but need to upgrade the version.
74 we suggest using the **Chocolatey** package manager. See install instructions at <https://chocolatey.org/>, and you will just need
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.
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.
91 this will depend on which distribution you're using.
93 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
97 sudo apt-get install gradle git
100 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
104 sudo yum install gradle git
107 If you have some other version of linux you'll probably be able to work it out!
112 ## Downloading the Jalview source tree
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
119 git clone http://source.jalview.org/git/jalview.git
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`.
125 ### What's in the source tree?
127 Within the `jalview` folder:
129 | dir/ file | contains|
130 |------------|---------|
131 | `bin/` | used by eclipse for compiled classes
132 | `build/` | the gradle build dir
133 | `classes/` | contains the compiled Java classes for the Jalview application
134 | `dist/` | assembled `.jar` files needed to run Jalview application
135 | `examples/`| example input files usable by Jalview
136 | `getdown/` | the libraries used by the Javliew launcher (getdown)
137 | `getdown/src/` | our modified source for `getdown`
138 | `getdown/website/` | the assembled "download" folder used by getdown for downloads/upgrades
139 | `getdown/files/` | the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application
140 | `j8lib/` | libraries needed to run Jalview under Java 1.8
141 | `j11lib/` | libraries needed to run Jalivew under Java 11
142 | `resource/`| non-java resources used in the Jalview application
143 | `src/` | the Jalview application source `.java` files
144 | `test/` | Test class source files
145 | `utils/` | helper applications used in the build process
146 | `utils/install4j/` | files used by the packaging tool, install4j
147 | `build.gradle` | the build file used by gradle
148 | `gradle.properties` | configurable properties for the build process
150 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
155 You will need to have the Java 11 `javac` in your path, or alternatively you can configure
156 gradle to know where this is by putting
159 org.gradle.java.home=/path_to_jdk_directory
161 in the `gradle.properties` file.
163 > *You may want to see some of the properties you can easily change at the end of this document.*
165 ### Minimal Jalview Build
167 To compile the necessary class files, just run
172 to compile the classes into the `classes` folder.
173 You should now be able to run the Jalview application directly with
176 java -cp "classes:resources:help:j11lib/*" jalview.bin.Jalview
179 You can also run with an automatic large memory setting (which will set the maximum
180 memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting
181 (if possible in your OS) with
184 java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher
187 >*You must use just "`j11lib/*`" and not "`j11lib/*.jar`" as this is a special Java
188 classpath argument wildcard interpreted by `java`, **not** a shell expansion wildcard interpreted
191 Note that `jalview.bin.Launcher` is a simplified launch class that re-launches `jalview.bin.Jalview`
192 with the same classpath and arguments, but with an automatically determined `-Xmx...`
195 ### Jalview in a Jar File
197 To package the `classes`, `resources`, and `help` into one jar, you can run
202 which assembles the Jalview classes and resources into `dist/jalview.jar`
207 java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
210 ### Distributed Jar Files
212 To simplify this, all required `.jar` files can be assembled into the `dist` folder
218 which puts all required jar files into `dist` so you can run with
221 java -cp "dist/*" jalview.bin.Jalview
224 ### Single *shadow* Jar File
226 The shadow jar file is a single `.jar` that contains all required classes -- from `jalview.jar`
227 and all of the supporting libraries in `j11lib/*.jar` merged into one `.jar` archive
228 file. A default launching class (`MAIN-CLASS: jalview.bin.Launcher`) is specified in the `.jar`
229 manifest file (`META/MANIFEST.MF`) so a start class doesn't need to be specified.
231 Build the shadow jar file in `build/lib/jalview-all-11.jar` with
239 java -jar build/lib/jalview-all-11.jar
242 Because no arguments are required, most OSes will associate a `.jar` file with the
243 `java` application (if this has been installed through the OS and not just a local
244 unzip) as a `-jar` argument so you may find you can launch `jalview-all-11.jar`
245 just by double-clicking on it)!
247 > The shadow jar file represents probably the simplest way to distribute the Jalview application, to machines that already have a Java 11 installed,
248 although without the many and compelling benefits of the `getdown` launcher.
251 ### Building the `getdown` launcher
253 We have made significant customisations to the `getdown` launcher which you can find
254 in `getdown/src/getdown`.
256 > You don't need to build this afresh as the required `gradle-core.jar`
257 and `gradle-launcher.jar` files are already distributed in `j11lib` and `getdown/lib` but if you want to, then
258 you'll need a working Maven and also a Java 8 JDK. Ensure the Java 8 `javac` is forefront
262 >cd getdown/src/getdown
265 > and you will find the required `.jar` files in `core/target/gradle-core-XXX.jar`
266 and `launcher/target/gradle-launcher-XXX.jar`. The `gradle-core.jar` should be copied
267 to both the `j11lib` folder to `getdown/lib`, whilst the `gradle-launcher.jar` only
268 needs to be copied to `getdown/lib`.
270 To assemble Jalview with `getdown` use the following gradle task:
276 This puts all the necessary files to launch Jalview with `getdown`
277 into `getdown/website/11/`. This could be treated as the reference folder
278 for `getdown`, which is where a getdown launcher will check to see if the Jalview application
279 files it has are up to date, and download if they aren't or it simply doesn't have
282 A minimal getdown-launcher can be found in `getdown/files/11/` which checks its up-to-date
283 status with (the absolute path to) `getdown/website/11/`.
285 This can be launched with
288 java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
291 > We've already met the `-jar file.jar` arguments. The next argument is the working folder for
292 getdown, and the final argument, "`jalview`", is a getdown application id (only "`jalview`"
298 There are substantial tests written for Jalview that use TestNG, which you can run with
304 These normally take around 5 - 10 minutes to complete and outputs its results into
308 ### Installer packaging with *install4j*
310 Jalview is currently using *install4j* <https://www.ej-technologies.com/products/install4j/overview.html>
311 as its installer packaging tool.
313 If you have a licensed installation of *install4j* you can build Jalview installers
320 though you may need to fiddle with the `install4j` and `copyInstall4jTemplate` tasks
321 in `build.gradle` file to point to your installation of *install4j* and also to bundled
322 JREs if you want to bundle those into the installers.
324 If you want more details, get in touch on our development mailing list at <http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev>.
327 ## Building in Eclipse
329 We develop in Eclipse, and support settings to develop and save Jalview source code
330 in our preferred style. We also support running the Jalview application, debugging
331 and running tests with TestNG from within Eclipse.
333 To get Jalview set up as a project in Eclipse, we recommend using at least the 2019-03
334 version of Eclipse IDE for Java Developers which you can download from the Eclipse
335 website: <https://www.eclipse.org/downloads/>
337 Once installed, we also recommend installing several plugins from the Eclipse Marketplace.
339 To do so, launch Eclipse, and go to Help->Eclipse Marketplace...
341 Search for and install:
343 1. Buildship Gradle Integration 3.0 (or greater)
344 1. Groovy Development Tools 3.4.0 (or greater)
345 1. TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)
347 > At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace
348 as the latest released version does not install in Eclipse 2019-03.
349 However, you can install a working beta of TestNG for Eclipse by going to
351 Help->Install New Software...
355 `TestNG Eclipse Composite P2 Repo - http://beust.com/eclipse-beta`
357 into the *Work with* box and click on the Add... button.
359 Eclipse might pause for a bit with the word *Pending* in the table below at this point, but it will eventually list TestNG with
360 a selection box under the *Name* column.
362 Select *TestNG* and carry on through the
363 install process to install the TestNG plugin.
365 After installing the plugins, it is good to get Java 11 set up in Eclipse as the default JRE.
367 To do this go to Preferences (Eclipse->Preferences in macOS, and File->Preferences
368 on Windows or Linux) and find
370 Java -> Installed JREs
372 If your Java 11 installation is not listed, click on
374 *Add* -> Standard VM -> *Next*
376 and enter the JRE home. You can browse to where it was installed. Give it a name (like "AdoptOpenJDK 11"). Select this JDK
377 as the default JRE and click on *Apply and Close*.
380 You can now import Jalview. It is important to import
381 Jalview as a Gradle project (not as a Java project), so go to
387 Gradle->Existing Gradle Project
389 and then click on the *Next >* button.
391 In the following options, it is the *Project Root Directory* you should set to be the
392 `jalview` folder that git downloaded. Then you can click on the *Finish* button.