Building Jalview from Source

From: Jim Procter Date: Sun, 7 Feb 2021 16:06:47 +0000 (+0000) Subject: JAL-3816 bump version number and cut release notes X-Git-Tag: Release_2_11_1_4~9^2~5 X-Git-Url: http://source.jalview.org/gitweb/?p=jalview.git;a=commitdiff_plain;h=7ae11f7f7f00549c6fb3af9ee193dc103a3c8de8 JAL-3816 bump version number and cut release notes --- diff --git a/RELEASE b/RELEASE index b5ce6d5..70a7383 100644 --- a/RELEASE +++ b/RELEASE @@ -1,2 +1,2 @@ jalview.release=releases/Release_2_11_1_Branch -jalview.version=2.11.1.3 +jalview.version=2.11.1.4 diff --git a/doc/building.html b/doc/building.html index 28206a6..4f4e1ae 100644 --- a/doc/building.html +++ b/doc/building.html @@ -4,82 +4,86 @@ - Building Jalview from Source - - + -

Building Jalview from Source
- Building Jalview from Source
  - tl;dr
  - Setting up
    - Setting up +
      - Java 11 compliant JDK
      - gradle and git
    - Downloading the Jalview source tree
      - Downloading the Jalview source tree +
        
        Whatâs in the source tree?
      - Building Jalview
        +
        Building Jalview +
        
        Minimal Jalview Build
        
        Jalview in a Jar File
        
        Distributed Jar Files
        @@ -760,7 +768,8 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
        
        Gradle properties
        
        Enabling Code Coverage with OpenClover
        -
        Setting up in Eclipse IDE
        +
        Setting up in Eclipse IDE +
        
        Installing Eclipse IDE
        
        Importing Jalview as an Eclipse project
        
        @@ -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):
        -
        brew install gradle git
        +
        brew install gradle git
        
        or if you aready have them installed but need to upgrade the version:
        -
        brew upgrade gradle git
        +
        brew upgrade gradle git
        
        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
        +
        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
        +
        sudo apt-get install gradle git
        
        for RPM-based distributions (e.g.Â Fedora, CentOS, RedHat)
        
        run
        -
        sudo yum install gradle git
        +
        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
        +
        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
        -
        gradle compileJava
        +
        gradle compileJava
        
        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
        +
        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
        +
        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
        -
        gradle jar
        +
        gradle jar
        
        which assembles the Jalview classes and resources into dist/jalview.jar
        
        To run this, use
        -
        java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
        +
        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
        -
        gradle makeDist
        +
        gradle makeDist
        
        which puts all required jar files into dist so you can run with
        -
        java -cp "dist/*" jalview.bin.Jalview
        +
        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
        -
        gradle shadowJar
        +
        gradle shadowJar
        
        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
        +
        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"
        +
        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:
        -
        gradle getdown
        +
        gradle getdown
        
        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
        +
        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
        -
        gradle test
        +
        gradle test
        
        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
        +
        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
        +
        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
        -
        gradle installers
        +
        gradle installers
        
        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
        +
        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
        
        e.g.
        -
        gradle getdown -PCHANNEL=SCRATCH-my_test_version
        +
        gradle getdown -PCHANNEL=SCRATCH-my_test_version
        
        JALVIEW_VERSION and the RELEASE file
        
        Any Jalview build will include the value of JALVIEW_VERSION in various places, including the âAboutâ and Jalview Desktop window title, and in filenames for the stand-alone executable jar. You can specify a custom version for a build via the JALVIEW_VERSION property, but for most situations, JALVIEW_VERSION will be automatically configured according to the value of the CHANNEL property, using the jalview.version property specified in the RELEASE file: - CHANNEL=RELEASE will set version to jalview.version - CHANNEL=TEST or DEVELOP will append â-testâ or â-developâ to jalview.version
        
        It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.
        @@ -1094,9 +1103,9 @@ and runtime classpath and also used in the makeDist build step. Whe
        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
        +
        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
        +
        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.
        @@ -1170,14 +1179,14 @@ and runtime classpath and also used in the makeDist build step. Whe
        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.
        
        -
        Eclipse eGit connection configuration
        +
        Eclipse eGit connection configuration
        
        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.
        
        -
        Eclipse eGit import choice
        +
        Eclipse eGit import choice
        
        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.
        @@ -1186,7 +1195,7 @@ and runtime classpath and also used in the makeDist build step. Whe
        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.
        
        -
        Eclipse Add Gradle Nature
        +
        Eclipse 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
        diff --git a/help/help/html/releases.html b/help/help/html/releases.html index ec4f041..4c72658 100755 --- a/help/help/html/releases.html +++ b/help/help/html/releases.html @@ -55,6 +55,36 @@ li:before { New Features Issues Resolved + 2.11.1 .4
        + 08/02/2021 + Improved control of + Jalview's use of network services +
        +
        + New .jalview_properties token controlling + launch of the news browser (like -nonews argument) +
        +
        + New .jalview_properties token controlling + download of linkout URLs from + www.jalview.org/services/identifiers +
        +
        + New .jalview_properties token controlling + download of BIOJSHTML templates +
        +
        + New 'Discover Web Services' option to trigger + a one off JABAWS discovery if autodiscovery was disabled +
        +
        + +
        +
        +
        + + 2.11.1 .3

MacOS

Windows

Linux

For Debian based distributions (e.g.Â Mint, Ubuntu, Debian)

for RPM-based distributions (e.g.Â Fedora, CentOS, RedHat)

Downloading the Jalview source tree

Whatâs in the source tree?

Minimal Jalview Build

Jalview in a Jar File

Distributed Jar Files

Single shadow Jar File

Running tests

Excluding some tests

Installer packaging with install4j

Gradle properties

JALVIEW_VERSION and the RELEASE file

Enabling Code Coverage with OpenClover

Additional views