+- Setting up in Eclipse IDE
+
@@ -813,27 +822,27 @@ brew cask install adoptopenjdk11
You should be able to install the latest (or sufficiently recent) versions of gradle and git using your OS package manager.
MacOS
we recommend using brew, which can be installed following the instructions at https://brew.sh/. After installing brew, open a Terminal window and type in (using an Administrator privileged user):
-
+
or if you aready have them installed but need to upgrade the version:
-
+
Windows
we suggest using the Chocolatey package manager. See install instructions at https://chocolatey.org/, and you will just need
-
+choco install gradle
+choco install git
Alternatively, you could install a real bash shell and install both gradle and git through apt-get. See https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/ for how to install the ubuntu bash shell in Windows 10.
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/. Getting the individual installs working together on the command line will be trickier so we recommend using Chocolatey or bash.
Linux
this will depend on which distribution youâre using.
For Debian based distributions (e.g. Mint, Ubuntu, Debian)
run
-
+ sudo apt-get install gradle git
for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
run
-
+sudo yum install gradle git
If you have some other version of linux youâll probably be able to work it out!
Downloading the Jalview source tree
This can be done with git. On the command line, change directory to where you want to download Jalviewâs build-tree top level directory. Then run
-
+git clone http://source.jalview.org/git/jalview.git
Youâll get some progress output and after a minute or two you should have the full Jalview build-tree in the folder jalview.
Whatâs in the source tree?
Jalview is a mature product with its codebase going back many years. As such it doesnât have a folder structure that most new gradle projects would have, so you might not find everything in the place you might expect. Hereâs a brief description of what you might find in the main folders under the jalview tree.
@@ -942,33 +951,33 @@ brew cask install adoptopenjdk11
Minimal Jalview Build
To compile the necessary class files, just run
-
+
to compile the classes into the classes folder. You should now be able to run the Jalview application directly with
-
+java -cp "classes:resources:help:j11lib/*" jalview.bin.Jalview
You can also run with an automatic large memory setting (which will set the maximum memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting (if possible in your OS) with
-
+java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher
You must use just âj11lib/*â and not âj11lib/*.jarâ as this is a special Java classpath argument wildcard interpreted by java, not a shell expansion wildcard interpreted by the shell.
Note that jalview.bin.Launcher is a simplified launcher class that re-launches jalview.bin.Jalview with the same JRE (not the same JVM instance), classpath and arguments, but with an automatically determined -Xmx... memory setting if one hasnât been provided.
Jalview in a Jar File
To package the classes, resources, and help into one jar, you can run
-
+
which assembles the Jalview classes and resources into dist/jalview.jar
To run this, use
-
+java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
Distributed Jar Files
To simplify this, all required .jar files can be assembled into the dist folder using
-
+
which puts all required jar files into dist so you can run with
-
+java -cp "dist/*" jalview.bin.Jalview
Single shadow Jar File
The shadow jar file is a single .jar that contains all required classes and resources from jalview.jar and all of the supporting libraries in j11lib/*.jar merged into one .jar archive file. A default launching class (MAIN-CLASS: jalview.bin.Launcher) is specified in the .jar manifest file (META/MANIFEST.MF) so a start class doesnât need to be specified.
Build the shadow jar file in build/libs/jalview-all-VERSION-j11.jar with
-
+
NB VERSION will be replaced with a version number or âDEVELOPMENTâ depending on how the branch is set up.
Run it with
-
+java -jar build/libs/jalview-all-VERSION-j11.jar
Because no arguments are required, most OSes will associate a .jar file with the java application (if this has been installed through the OS and not just a local unzip) as a -jar argument so you may find you can launch jalview-all-VERSION-j11.jar just by double-clicking on it)!
The shadowJar task is not a requirement for any other task, so to build the shadow jar file you must specify the shadowJar task.
@@ -980,36 +989,36 @@ brew cask install adoptopenjdk11
We have made significant customisations to the getdown launcher which you can find in getdown/src/getdown.
You donât need to build this afresh as the required getdown-core.jar and getdown-launcher.jar files are already distributed in j11lib and getdown/lib but if you want to, then youâll need a working Maven and also a Java 8 JDK. Ensure the Java 8 javac is forefront in your path and do
-
+cd getdown/src/getdown
+mvn clean package -Dgetdown.host.whitelist="jalview.org,*.jalview.org"
and you will find the required .jar files in core/target/getdown-core-XXX.jar and launcher/target/getdown-launcher-XXX.jar. The getdown-core.jar should then be copied to all three of the j8lib, j11lib and getdown/lib folders, whilst the getdown-launcher.jar only needs to be copied to getdown/lib.
The mvn command should ideally include the -Dgetdown.host.whitelist=*.jalview.org setting. This, and the necessary file copying commands, can be found in getdown/src/getdown/mvn_cmd.
To assemble Jalview with getdown use the following gradle task:
-
+
This puts all the necessary files to launch Jalview with getdown into getdown/website/11/. This could be treated as the reference folder for getdown, which is where a getdown launcher will check to see if the Jalview application files it has are up to date, and download if they arenât or it simply doesnât have them.
A minimal getdown-launcher can be found in getdown/files/11/ which checks its up-to-date status with (the absolute path to) getdown/website/11/.
This can be launched with
-
+java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
Weâve already met the -jar file.jar arguments. The next argument is the working folder for getdown, and the final argument, âjalviewâ, is a getdown application id (only âjalviewâ is defined here).
The command line sequence for building and relocating the getdown artifacts can be executed as a script via getdown/src/getdown/mvn_cmd. Please make sure this script is kept up to date should the getdown build instructions change.
Running tests
There are substantial tests written for Jalview that use TestNG, which you can run with
-
+
These normally take around 5 - 10 minutes to complete and outputs its full results into the tests/ folder. A summary of results should appear in your console.
You can run different defined groups of tests with
-
+gradle test -PtestngGroups=Network
Available groups include Functional (default), Network, External.
Excluding some tests
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.
To exclude one or more groups of tests, add them as a comma separated list in testngExcludedGroups.
-
+gradle test -PtestngExcludedGroups=Not-bamboo
Installer packaging with install4j
Jalview is currently using install4j https://www.ej-technologies.com/products/install4j/overview.html as its installer packaging tool.
If you have a licensed installation of install4j you can build Jalview installers by running
-
+
though you may need to fiddle with the install4j and copyInstall4jTemplate tasks in build.gradle file to point to your installation of install4j and also to bundled JREs if you want to bundle those into the installers.
If you want more details, get in touch on our development mailing list jalview-dev@jalview.org. Sign up at http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev.
Gradle properties
@@ -1019,7 +1028,7 @@ brew cask install adoptopenjdk11
This changes the target java bytecode version > NOTE that you will need to use a Java 11 (or greater) JDK Java compiler to build Jalview for any byte-code target version.
Valid values are 11 and 1.8.
e.g.
-
+gradle shadowJar -PJAVA_VERSION=1.8
When using -PJAVA_VERSION=1.8 the libraries from j8lib (instead of j11lib) will be used in the compile
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 instead use 1.8. Also if you are building installer packages with install4j the package builder will look for JRE 1.8 bundles to package in the installers.
@@ -1085,7 +1094,7 @@ and runtime classpath and also used in the makeDist build step. Whe