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
-
The shadowJar
task is not a requirement for any other task, so to build the shadow jar file you must specify the shadowJar
task.
@@ -970,63 +943,38 @@ brew cask install adoptopenjdk11
Building the getdown
launcher
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 gradle-core.jar
and gradle-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
-
+You don't need to build this afresh as the required gradle-core.jar
and gradle-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/gradle-core-XXX.jar
and launcher/target/gradle-launcher-XXX.jar
. The gradle-core.jar
should then be copied to all three of the j8lib
, j11lib
and getdown/lib
folders, whilst the gradle-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.
+
+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).
+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).
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.
-Building in Eclipse
-We develop in Eclipse, and support settings to develop and save Jalview source code in our preferred style. We also support running the Jalview application, debugging and running tests with TestNG from within Eclipse.
-To get Jalview set up as a project in Eclipse, we recommend using at least the 2019-03 version of Eclipse IDE for Java Developers which you can download from the Eclipse website: https://www.eclipse.org/downloads/
-Once installed, we also recommend installing several plugins from the Eclipse Marketplace.
-To do so, launch Eclipse, and go to Help->Eclipse Marketplaceâ¦
-Search for and install:
-
-- Buildship Gradle Integration 3.0 (or greater)
-- Groovy Development Tools 3.4.0 (or greater)
-- TestNG for Eclipse (optional â only needed if you want to run tests from Eclipse)
-
-
-At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace as the latest released version does not install in Eclipse 2019-03. However, you can install a working beta of TestNG for Eclipse by going to
-Help->Install New Softwareâ¦
-and entering
-TestNG Eclipse Composite P2 Repo - http://beust.com/eclipse-beta
-into the Work with box and click on the Add⦠button.
-Eclipse might pause for a bit with the word Pending in the table below at this point, but it will eventually list TestNG with a selection box under the Name column.
-Select TestNG and carry on through the install process to install the TestNG plugin.
-
-After installing the plugins, it is a good to get Java 11 set up in Eclipse as the default JRE.
-To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences on Windows or Window->Preferences on Linux) and find
-Java -> Installed JREs
-If your Java 11 installation is not listed, click on
-Add -> Standard VM -> Next
-and enter the JRE home. You can browse to where it was installed. Give it a name (like âAdoptOpenJDK 11â). Select this JDK as the default JRE and click on Apply and Close.
-You can now import Jalview. It is important to import Jalview as a Gradle project (not as a Java project), so go to
-File->Importâ¦
-find and select
-Gradle->Existing Gradle Project
-and then click on the Next > button.
-In the following options, it is the Project Root Directory you should set to be the jalview
folder that git downloaded. Then you can click on the Finish button.
+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
There are a lot of properties configured in gradle.properties
which we strongly recommend being left as they are unless you have a specific problem with the build process.
There are a few gradle properties you might want to set on the command line with the -P
flag when building a version of Jalview with specific requirements:
@@ -1034,26 +982,179 @@ 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.
Note that continued development of Jalview will assume a Java 11+ runtime environment, the 2.11.0 release will run under a Java 1.8 JRE with a few minor features disabled.
CHANNEL
-This changes the appbase
setting in getdown.txt
(appbase
is where the getdown launcher looks to see if thereâs an updated file) to point to a particular Jalview channel. Expected values are FILE
, STABLE
, DEVELOPMENT
, or a specific version of Jalview like 2.11
or 2.10.5
.
-A value of FILE
behaves differently to the other expected values and will use a local file-system scheme URI instead of a Jalview release channel. This file:
scheme URI uses an absolute path to the getdown/website/<JAVA_VERSION>
-On a regular development machine, this property will default to LOCAL
.
+This changes the appbase
setting in getdown.txt
(appbase
is where the getdown launcher looks to see if there's an updated file) to point to a particular Jalview channel or some other appropriate place to look for required files. If the selected channel type requires the getdown appbase
to be a local directory on the filesystem (instead of a website URL) then a modified version of the getdown-launcher.jar
will be used to allow this. The two versions of the getdown-launcher.jar
can be found in getdown/lib
. Some other variables used in the build process might also be set differently depending on the value of CHANNEL
to allow smooth operation of getdown in the given context.
+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:
+
+LOCAL
: This is for running the compiled application from the development directory. It will set
+
+appbase
as file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION
(e.g. file://home/user/git/jalview/getdown/files/11
)
+- application subdir as
alt
+- Getdown launcher can use a
file://
scheme appbase.
+
+BUILD
: This is for creating an appbase channel on the build server by an automatic or manually started build. It will set
+
+appbase
as https://builds.jalview.org/browse/${bamboo_planKey}/latest/artifact/shared/getdown-channel/JAVA_VERSION
Note that bamboo_planKey should be set by the build plan with -Pbamboo_planKey=${bamboo.planKey}
+- application subdir as
alt
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+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. It will set
+
+appbase
as http://www.jalview.org/getdown/develop/JAVA_VERSION
+- application subdir as
alt
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+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_] It will set
+
+appbase
as http://www.jalview.org/getdown/SCRATCH-NAME/JAVA_VERSION
+- application subdir as
alt
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+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
) It will set
+
+appbase
as file://${LOCALDIR}
+- application subdir as
alt
+- Getdown launcher can use a
file://
scheme appbase.
+
+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. It will set
+
+appbase
as http://www.jalview.org/getdown/test-release/JAVA_VERSION
+- application subdir as
alt
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+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. It will set
+
+appbase
as http://www.jalview.org/getdown/release/JAVA_VERSION
+- application subdir as
release
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+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. 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. It will set
+
+appbase
as http://www.jalview.org/getdown/archive/JALVIEW_VERSION/JAVA_VERSION
+- application subdir as
alt
+- Getdown launcher cannot use a
file://
scheme appbase.
+
+ARCHIVELOCAL
: Like ARCHIVE
but with a local filesystem appbase for local testing. 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. It will set
+
+appbase
as file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION
(where the old jars will have been copied and digested)
+- application subdir as
alt
+- Getdown launcher can use a
file://
scheme appbase.
+
+
e.g.
-
-
-If you are building install4j installers (requires install4j to be installed) then this property specifies a comma-separated list of media types (i.e. platform specific installers) install4j should actually build.
+gradle getdown -PCHANNEL=SCRATCH-my_test_version
+
+If you are building install4j installers (requires install4j to be installed) then this property specifies a comma-separated list of media types (i.e. platform specific installers) install4j should actually build.
Currently the valid values are linuxDeb
, linuxRPM
, macosArchive
, unixArchive
, unixInstaller
, windows
The default value is all of them.
e.g.
-
+gradle installers -PJAVA_VERSION=1.8 -Pinstall4jMediaTypes=macosArchive
To get an up-to-date list of possible values, you can run
-
+perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j/install4j_template.install4j | sort -u
in the jalview
root folder.
+Enabling Code Coverage with OpenClover
+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.
+gradle -Pclover=true test cloverReport
+Troubleshooting report generation
+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:
+JVM Memory settings - increase if out of memory errors are reported
+cloverReportJVMHeap = 2g
+-Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.
+cloverReportJVMArgs = -Dfile.encoding=UTF-8
+Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database
+cloverReportHTMLOptions =
+-v for verbose, -d for debug level messages (as above)
+cloverReportXMLOptions =
+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.
+Setting up in Eclipse IDE
+Installing Eclipse IDE
+We develop in Eclipse, and support settings to develop and save Jalview source code in our preferred style. We also support running the Jalview application, debugging and running tests with TestNG from within Eclipse.
+To get Jalview set up as a project in Eclipse, we recommend using at least the 2019-12 version of Eclipse IDE for Java Developers which you can download from the Eclipse website: https://www.eclipse.org/downloads/. Since Eclipse 2020-03 you are encouraged to use the Eclipse Installer (see the Eclipse Downloads page). In the installer, when given a choice of packages for Eclipse you should choose the "Eclipse IDE for Enterprise Java Developers" package.
+
+Once Eclipse is installed, we also recommend installing several plugins from the Eclipse Marketplace.
+Some of these should already be installed with the Enterprise Java Developer package:
+
+- Buildship Gradle Integration 3.0 (or greater)
+- EclEmma Java Code Coverage
+- Egit - Git Integration for Eclipse
+
+To install the others, launch Eclipse, and go to Help->Eclipse Marketplace...
+Search for and install:
+
+- Groovy Development Tools 3.4.0 (or greater)
+- Checkstyle Plug-in (optional)
+- TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)
+
+
+At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace as the latest released version does not install in Eclipse 2019-03. However, you can install a working release of TestNG for Eclipse by going to
+Help->Install New Software...
+and entering
+TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release
+into the Work with box and click on the Add... button.
+Eclipse might pause for a bit with the word Pending in the table below at this point, but it will eventually list TestNG with a selection box under the Name column.
+Select TestNG and carry on through the install process to install the TestNG plugin.
+
+After installing the plugins, check that Java 11 is set up in Eclipse as the default JRE (see section Java 11 compliant JDK).
+To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences on Windows or Window->Preferences on Linux) and find
+Java -> Installed JREs
+If your Java 11 installation is not listed, click on
+Add -> Standard VM -> Next
+and enter the JRE home. You can browse to where it is installed. Give it a name (like "AdoptOpenJDK 11"). Select this JDK as the default JRE and click on Apply and Close.
+You can now import Jalview.
+Importing Jalview as an Eclipse project
+Importing an already downloaded git repo
+If you have already downloaded Jalview using git clone
then you can import this folder into Eclipse directly.
+It is important to import Jalview as a Gradle project (not as a Java project), so go to
+File->Import...
+find and select
+Gradle->Existing Gradle Project
+and then click on the Next button.
+In the following options, it is the Project Root Directory you should set to be the jalview
folder that git downloaded. Then you can click on the Finish button.
+Using Eclipse IDE to download the git repo
+If you don't have git as a command line tool or would prefer to work entirely within Eclipse IDE then Eclipse's eGit plugin can set up a git repo of the jalview source. Go to
+File->Import...
+Find and select
+Git->Projects from Git
+and then click on the Next button.
+Then select Clone URI and click on Next.
+In the next window (Source Git Repository) you should put the git clone
URL in the text box labelled URI
. If you have a Jalview developer account (with a username and password for the Jalview git repository) then you should enter https://source.jalview.org/git/jalview.git
. If you do not have a Jalview developer account then you should enter http://source.jalview.org/git/jalview.git
. You will not be able to push any of your changes back to the Jalview git repository. However you can still pull all branches of the Jalview source code to your computer and develop the code there. > You can sign up for a Jalview developer account at https://source.jalview.org/crucible/
+If you have a Jalview developer account, enter the username and password and decide if you want to use Eclipse's secure storage. If you don't have an account you can leave the Authentication section blank.
+
+Click on the Next button.
+The next window (Branch Selection) gives a list of the many Jalview branches, which by default will be all checked. You probably only want to download one branch (you can always download others at a later time). This is likely to be the develop
branch so you can click on the Deselect All button, find the develop
branch (the filter text helps), select that, and then click on the Next button.
+Choose a directory to your copy of the git repo in, and leave the other options as they are and click on the Next button. The next stage may take a minute or two as it checks out the selected branch(es) from the Jalview git repository.
+When it has finished it is important to select Import as general project and then click on Next. > Ideally there would be an Import as gradle project here but there isn't -- we'll sort that out later.
+
+Click on the Next button.
+You can change the project name here. By default it will show as jalview which is fine unless you have another instance of the a Jalview project also called jalview, in which case you could change this project's name now to avoid a conflict within Eclipse.
+Click on Finish!
+However, we haven't finished...
+You should now see, and be able to expand, the jalview project in the Project Explorer. We need to tell eclipse that this is a Gradle project, which will then allow the Eclipse Buildship plugin to automatically configure almost everything else!
+Right click on the project name (jalview) in the Project Explorer and find Configure towards the bottom of this long context menu, then choose Add Gradle Nature.
+
+The project should now reconfigure itself using the build.gradle
file to dynamically set various aspects of the project including classpath.
+Additional views
+Some views that are automatically added when Importing a Gradle Project are not added when simply Adding a Gradle Nature, but we can add these manually by clicking on Window->Show View->Console and Window->Show View->Other... Filter with the word "gradle" and choose both Gradle Executions and Gradle Tasks and then click on the Open button.
+Okay, ready to code! Use of Eclipse is beyond the scope of this document, but you can find more information about developing jalview and our developer workflow in the google doc https://docs.google.com/document/d/1lZo_pZRkazDBJGNachXr6qCVlw8ByuMYG6e9SZlPUlQ/edit?usp=sharing
+
+Jalview Development Team