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
30 > The versions and installation methods here are just suggestions (which we have tested
31 so are known to work). If you need or wish to use different implementations (particularly
32 you might need a bespoke JDK if you are on an exotic architecture) then the general
33 build instructions should work with any gradle 5+. You should be able to compile the
34 bytecode with any JDK Java 11+. The resulting bytecode (in particular the shadow jar)
35 should be runnable in any JRE Java 1.8+. Remember that because Jalview and the getdown launcher
36 are Java bytecode you can build on one system where you might have gradle, and run
37 on another where you don't (JRE 1.8+ required).
39 ### Java 11 compliant JDK
42 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*).
44 >##### Alternative/CLI install of AdoptOpenJDK 11
46 >You can also install adoptopenjdk11 using either `brew` (macOS), `choco` (Windows)
47 (see the section on `gradle` and `git` for more informaiton on `brew` and `choco`)
48 or `yum` or `apt` (Linux):
50 >###### alternative for MacOS and Homebrew
52 >brew tap adoptopenjdk/openjdk
53 >brew cask install adoptopenjdk11
56 >###### alternative for Windows and Chocolatey
58 >choco install adoptopenjdk11
61 >###### alternative for Linux with yum/apt
63 >see <https://adoptopenjdk.net/installation.html#linux-pkg>
67 You should be able to install the latest (or sufficiently recent) versions of gradle and git using your OS package manager.
70 we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
71 After installing `brew`, open a Terminal window and type in (using an Administrator privileged user):
74 brew install gradle git
77 or if you aready have them installed but need to upgrade the version:
80 brew upgrade gradle git
85 we suggest using the **Chocolatey** package manager. See install instructions at <https://chocolatey.org/>, and you will just need
92 Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
93 See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/>
94 for how to install the ubuntu bash shell in Windows 10.
96 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/>.
97 Getting the individual installs working together on the command line will be trickier
98 so we recommend using Chocolatey or bash.
102 this will depend on which distribution you're using.
104 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
108 sudo apt-get install gradle git
111 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
115 sudo yum install gradle git
118 If you have some other version of linux you'll probably be able to work it out!
123 ## Downloading the Jalview source tree
125 This can be done with `git`.
126 On the command line, change directory to where you want to download Jalview's build-tree
127 top level directory. Then run
130 git clone http://source.jalview.org/git/jalview.git
133 You'll get some progress output and after a minute or two you should have the full
134 Jalview build-tree in the folder `jalview`.
136 ### What's in the source tree?
138 Jalview is a mature product with its codebase going back many years. As such it doesn't
139 have a folder structure that most new gradle projects would have, so you might not
140 find everything in the place you might expect. Here's a brief description of what
141 you might find in the main folders under the `jalview` tree.
143 Within the `jalview` folder you will find (of possible interest):
145 dir/ or file | contains
146 ---------------------|----------------------------------------------------------------------------------------------------------------
147 `bin/` | used by eclipse for compiled classes -- no need to touch this
148 `build/` | the gradle build dir
149 `classes/` | contains the compiled Java classes for the Jalview application
150 `dist/` | assembled `.jar` files needed to run Jalview application
151 `examples/` | example input files usable by Jalview
152 `getdown/` | the libraries used by the Javliew launcher (getdown)
153 `getdown/src/` | our modified source for `getdown`
154 `getdown/website/` | the assembled "download" folder used by getdown for downloads/upgrades
155 `getdown/files/` | the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application
156 `help/` | the help documents
157 `j8lib/` | libraries needed to run Jalview under Java 1.8
158 `j11lib/` | libraries needed to run Jalivew under Java 11
159 `resource/` | non-java resources used in the Jalview application
160 `src/` | the Jalview application source `.java` files
161 `test/` | Test class source files
162 `utils/` | helper applications used in the build process
163 `utils/install4j/` | files used by the packaging tool, install4j
164 `build.gradle` | the build file used by gradle
165 `gradle.properties` | configurable properties for the build process
167 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
172 You will need to have the Java 11 `javac` in your path, or alternatively you can configure
173 gradle to know where this is by putting
176 org.gradle.java.home=/path_to_jdk_directory
178 in the `gradle.properties` file.
180 > *You may want to see some of the other properties you can change at the end of this document.*
182 ### Minimal Jalview Build
184 To compile the necessary class files, just run
189 to compile the classes into the `classes` folder.
190 You should now be able to run the Jalview application directly with
193 java -cp "classes:resources:help:j11lib/*" jalview.bin.Jalview
196 You can also run with an automatic large memory setting (which will set the maximum
197 memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting
198 (if possible in your OS) with
201 java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher
204 >*You must use just "`j11lib/*`" and not "`j11lib/*.jar`" as this is a special Java
205 classpath argument wildcard interpreted by `java`, **not** a shell expansion wildcard interpreted
208 Note that `jalview.bin.Launcher` is a simplified launcher class that re-launches `jalview.bin.Jalview`
209 with the same JRE (*not* the same JVM instance), classpath and arguments, but with an automatically determined `-Xmx...`
210 memory setting if one hasn't been provided.
212 ### Jalview in a Jar File
214 To package the `classes`, `resources`, and `help` into one jar, you can run
219 which assembles the Jalview classes and resources into `dist/jalview.jar`
224 java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
227 ### Distributed Jar Files
229 To simplify this, all required `.jar` files can be assembled into the `dist` folder
235 which puts all required jar files into `dist` so you can run with
238 java -cp "dist/*" jalview.bin.Jalview
241 ### Single *shadow* Jar File
243 The shadow jar file is a single `.jar` that contains all required classes and resources from `jalview.jar`
244 and all of the supporting libraries in `j11lib/*.jar` merged into one `.jar` archive
245 file. A default launching class (`MAIN-CLASS: jalview.bin.Launcher`) is specified in the `.jar`
246 manifest file (`META/MANIFEST.MF`) so a start class doesn't need to be specified.
248 Build the shadow jar file in `build/lib/jalview-all-11.jar` with
256 java -jar build/lib/jalview-all-11.jar
259 Because no arguments are required, most OSes will associate a `.jar` file with the
260 `java` application (if this has been installed through the OS and not just a local
261 unzip) as a `-jar` argument so you may find you can launch `jalview-all-11.jar`
262 just by double-clicking on it)!
264 > The `shadowJar` task is not a requirement for any other task, so to build the shadow
265 jar file you must specify the `shadowJar` task.
267 > The shadow jar file represents probably the simplest way to distribute the Jalview application to machines that already have a Java 11 installed,
268 although without the many and compelling benefits of the `getdown` launcher.
271 ### Building the `getdown` launcher
273 We have made significant customisations to the `getdown` launcher which you can find
274 in `getdown/src/getdown`.
276 > You don't need to build this afresh as the required `gradle-core.jar`
277 and `gradle-launcher.jar` files are already distributed in `j11lib` and `getdown/lib` but if you want to, then
278 you'll need a working Maven and also a Java 8 JDK. Ensure the Java 8 `javac` is forefront
282 >cd getdown/src/getdown
283 >mvn clean package -Dgetdown.host.whitelist="jalview.org,*.jalview.org"
285 > and you will find the required `.jar` files in `core/target/gradle-core-XXX.jar`
286 and `launcher/target/gradle-launcher-XXX.jar`. The `gradle-core.jar` should then be copied
287 to all three of the `j8lib`, `j11lib` and `getdown/lib` folders, whilst the `gradle-launcher.jar` only
288 needs to be copied to `getdown/lib`.
290 >The `mvn` command should ideally include the `-Dgetdown.host.whitelist=*.jalview.org` setting.
291 This, and the necessary file copying commands, can be found in `getdown/src/getdown/mvn_cmd`.
293 To assemble Jalview with `getdown` use the following gradle task:
299 This puts all the necessary files to launch Jalview with `getdown`
300 into `getdown/website/11/`. This could be treated as the reference folder
301 for `getdown`, which is where a getdown launcher will check to see if the Jalview application
302 files it has are up to date, and download if they aren't or it simply doesn't have
305 A minimal getdown-launcher can be found in `getdown/files/11/` which checks its up-to-date
306 status with (the absolute path to) `getdown/website/11/`.
308 This can be launched with
311 java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
314 > We've already met the `-jar file.jar` arguments. The next argument is the working folder for
315 getdown, and the final argument, "`jalview`", is a getdown application id (only "`jalview`"
321 There are substantial tests written for Jalview that use TestNG, which you can run with
327 These normally take around 5 - 10 minutes to complete and outputs its full results into
328 the `tests/` folder. A summary of results should appear in your console.
330 You can run different defined groups of tests with
333 gradle test -PtestngGroups=Network
336 Available groups include Functional (default), Network, External.
338 #### Excluding some tests
340 Some of Jalview's Functional tests don't pass reliably in all environments. We tag these tests with a group like 'Not-bamboo' to mark them for exclusion when we run tests as part of continuous integration.
342 To exclude one or more groups of tests, add them as a comma separated list in testngExcludedGroups.
345 gradle test -PtestngExcludedGroups=Not-bamboo
349 ### Installer packaging with *install4j*
351 Jalview is currently using *install4j* <https://www.ej-technologies.com/products/install4j/overview.html>
352 as its installer packaging tool.
354 If you have a licensed installation of *install4j* you can build Jalview installers
361 though you may need to fiddle with the `install4j` and `copyInstall4jTemplate` tasks
362 in `build.gradle` file to point to your installation of *install4j* and also to bundled
363 JREs if you want to bundle those into the installers.
365 If you want more details, get in touch on our development mailing list <jalview-dev@jalview.org>.
366 Sign up at <http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev>.
369 ## Building in Eclipse
371 We develop in Eclipse, and support settings to develop and save Jalview source code
372 in our preferred style. We also support running the Jalview application, debugging
373 and running tests with TestNG from within Eclipse.
375 To get Jalview set up as a project in Eclipse, we recommend using at least the 2019-03
376 version of Eclipse IDE for Java Developers which you can download from the Eclipse
377 website: <https://www.eclipse.org/downloads/>
379 Once installed, we also recommend installing several plugins from the Eclipse Marketplace.
381 To do so, launch Eclipse, and go to Help->Eclipse Marketplace...
383 Search for and install:
385 1. Buildship Gradle Integration 3.0 (or greater)
386 1. Groovy Development Tools 3.4.0 (or greater)
387 1. TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)
389 > At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace
390 as the latest released version does not install in Eclipse 2019-03.
391 However, you can install a working beta of TestNG for Eclipse by going to
393 Help->Install New Software...
397 `TestNG Eclipse Composite P2 Repo - http://beust.com/eclipse-beta`
399 into the *Work with* box and click on the *Add...* button.
401 Eclipse might pause for a bit with the word *Pending* in the table below at this point, but it will eventually list TestNG with
402 a selection box under the *Name* column.
404 Select *TestNG* and carry on through the
405 install process to install the TestNG plugin.
407 After installing the plugins, it is a good to get Java 11 set up in Eclipse as the default JRE.
409 To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences
410 on Windows or Window->Preferences on Linux) and find
412 Java -> Installed JREs
414 If your Java 11 installation is not listed, click on
416 *Add* -> Standard VM -> *Next*
418 and enter the JRE home. You can browse to where it was installed. Give it a name (like "AdoptOpenJDK 11"). Select this JDK
419 as the default JRE and click on *Apply and Close*.
422 You can now import Jalview. It is important to import
423 Jalview as a Gradle project (not as a Java project), so go to
429 Gradle->Existing Gradle Project
431 and then click on the *Next >* button.
433 In the following options, it is the *Project Root Directory* you should set to be the
434 `jalview` folder that git downloaded. Then you can click on the *Finish* button.
439 There are a lot of properties configured in `gradle.properties` which we strongly recommend
440 being left as they are unless you have a specific problem with the build process.
442 There are a few gradle properties you might want to set on the command line with the
443 `-P` flag when building a version of Jalview with specific requirements:
446 This changes the *target* java bytecode version
447 > NOTE that you will need to use a Java 11 (or greater) JDK Java compiler to build
448 Jalview for any byte-code target version.
450 Valid values are `11` and `1.8`.
455 gradle shadowJar -PJAVA_VERSION=1.8
458 When using `-PJAVA_VERSION=1.8` the libraries from `j8lib` (instead of `j11lib`) will be used in the compile
459 and runtime classpath and also used in the `makeDist` build step. Where a Java version of `11` is used in folder and file names, it will
460 instead use `1.8`. Also if you are building installer packages with *install4j* the
461 package builder will look for JRE 1.8 bundles to package in the installers.
463 > Note that continued development of Jalview will assume a Java 11+ runtime environment,
464 the 2.11.0 release will run under a Java 1.8 JRE with a few minor features disabled.
467 This changes the `appbase` setting in `getdown.txt` (`appbase` is where the getdown launcher
468 looks to see if there's an updated file) to point to a particular Jalview channel or some other appropriate
469 place to look for required files. If the selected channel type requires the getdown `appbase` to be a local
470 directory on the filesystem (instead of a website URL) then a modified version of the `getdown-launcher.jar` will
471 be used to allow this. The two versions of the `getdown-launcher.jar` can be found in `getdown/lib`.
472 Some other variables used in the build process might also be set differently depending on the value of `CHANNEL`
473 to allow smooth operation of getdown in the given context.
475 There are several values of `CHANNEL` that can be chosen, with a default of `LOCAL`. Here's what they're for and what they do:
477 * `LOCAL`: This is for running the compiled application from the development directory.
479 - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION`
480 (e.g. `file://home/user/git/jalview/getdown/files/11`)
481 - application subdir as `alt`
482 - Getdown launcher can use a `file://` scheme appbase.
483 * `BUILD`: This is for creating an appbase channel on the build server by an automatic or manually started build.
485 - `appbase` as `https://builds.jalview.org/browse/${bamboo_planKey}/latest/artifact/shared/getdown-channel/JAVA_VERSION`
486 Note that bamboo_planKey should be set by the build plan with `-Pbamboo_planKey=${bamboo.planKey}`
487 - application subdir as `alt`
488 - Getdown launcher cannot use a `file://` scheme appbase.
489 * `DEVELOP`: This is for creating a `develop` appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server.
491 - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
492 - application subdir as `alt`
493 - Getdown launcher cannot use a `file://` scheme appbase.
494 * `SCRATCH-NAME`: This is for creating a temporary scratch appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels. The value of `NAME` can be any "word-character" [A-Za-z0-9\_]
496 - `appbase` as `http://www.jalview.org/getdown/SCRATCH-NAME/JAVA_VERSION`
497 - application subdir as `alt`
498 - Getdown launcher cannot use a `file://` scheme appbase.
499 * `TEST-LOCAL`: Like `SCRATCH` but with a specific `test-local` channel name and a local filesystem appbase. This is meant for testing an over-the-air update on the local filesystem. An extra property `LOCALDIR` must be given (e.g. `-PLOCALDIR=/home/user/tmp/test`)
501 - `appbase` as `file://${LOCALDIR}`
502 - application subdir as `alt`
503 - Getdown launcher can use a `file://` scheme appbase.
504 * `TEST-RELEASE`: Like `SCRATCH` but with a specific `test-release` channel name. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels.
506 - `appbase` as `http://www.jalview.org/getdown/test-release/JAVA_VERSION`
507 - application subdir as `alt`
508 - Getdown launcher cannot use a `file://` scheme appbase.
509 * `RELEASE`: This is for an actual release build, and will use an appbase on the main web server with the main `release` channel name. This won't become live until the actual getdown artefact is synced to the web server.
511 - `appbase` as `http://www.jalview.org/getdown/release/JAVA_VERSION`
512 - application subdir as `release`
513 - Getdown launcher cannot use a `file://` scheme appbase.
514 * `ARCHIVE`: This is a helper to create a channel for a specific release version, and will use an appbase on the main web server with a specific `archive/JALVIEW_VERSION` channel name. This won't become live until the actual getdown artefact is synced to the web server.
515 You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
517 - `appbase` as `http://www.jalview.org/getdown/archive/JALVIEW_VERSION/JAVA_VERSION`
518 - application subdir as `alt`
519 - Getdown launcher cannot use a `file://` scheme appbase.
520 * `ARCHIVELOCAL`: Like `ARCHIVE` but with a local filesystem appbase for local testing.
521 You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
523 - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION` (where the old jars will have been copied and digested)
524 - application subdir as `alt`
525 - Getdown launcher can use a `file://` scheme appbase.
529 gradle getdown -PCHANNEL=SCRATCH-my_test_version
532 #### `install4jMediaTypes`
533 If you are building *install4j* installers (requires *install4j* to be installed) then this property specifies a comma-separated
534 list of media types (i.e. platform specific installers) *install4j* should actually build.
536 Currently the valid values are
544 The default value is all of them.
548 gradle installers -PJAVA_VERSION=1.8 -Pinstall4jMediaTypes=macosArchive
551 To get an up-to-date list of possible values, you can run
554 perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j/install4j_template.install4j | sort -u
556 in the `jalview` root folder.
559 ## Enabling Code Coverage with OpenClover
561 Bytecode instrumentation tasks are enabled by specifying 'true' (or just a non-whitespace non-numeric word) in the 'clover' property. This adds the 'openclover' plugin to the build script's classpath, making it possible to track code execution during test which can be viewed as an HTML report published at build/reports/clover/index.html.
563 ```gradle -Pclover=true test cloverReport```
565 #### Troubleshooting report generation
567 The build forks a new JVM process to run the clover report generation tools (both XML and HTML reports are generated by default). The following properties can be used to specify additional options or adjust JVM memory settings. Default values for these options are:
569 ##### JVM Memory settings - increase if out of memory errors are reported
571 ```cloverReportJVMHeap = 2g```
573 ##### -Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.
575 ```cloverReportJVMArgs = -Dfile.encoding=UTF-8```
577 ##### Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database
579 ```cloverReportHTMLOptions = ```
581 ##### -v for verbose, -d for debug level messages (as above)
583 ```cloverReportXMLOptions = ```
586 _Note_ do not forget to include the -Dfile.encoding=UTF-8 option: this is essential for some platforms in order for Clover to correctly parse some Jalview source files that contain characters that are UTF-8 encoded.
590 [Jalview Development Team](mailto:help@jalview.org)