X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=doc%2Fbuilding.md;h=8e21d5778379ac7aa8554cb364416b1ecc86eb05;hb=bb5d9c75833e2d0b9ef8f66b8fcd7d5649a3271f;hp=06e796d4d32c983ab0078afce4ebd7144395c0db;hpb=91cf2210f6440d85c8a488c1bd18b0d3feb93f19;p=jalview.git diff --git a/doc/building.md b/doc/building.md index 06e796d..8e21d57 100644 --- a/doc/building.md +++ b/doc/building.md @@ -9,7 +9,7 @@ git clone http://source.jalview.org/git/jalview.git cd jalview gradle shadowJar # run -java -jar build/libs/jalview-all-11.jar +java -jar build/libs/jalview-all-*-j11.jar # and/or create launcher gradle getdown @@ -26,7 +26,7 @@ java -jar getdown-launcher.jar . jalview 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. * Java 11 compliant JDK -* gradle 5.2 or above +* gradle 5.2 or above *(NB gradle 6.6 and above currently produces NullPointerExceptions during the build. This is non-fatal and does not affect the build. Use gradle 6.5.1 to avoid this)* * git > The versions and installation methods here are just suggestions (which we have tested @@ -248,20 +248,23 @@ and all of the supporting libraries in `j11lib/*.jar` merged into one `.jar` arc 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/lib/jalview-all-11.jar` with +Build the shadow jar file in `build/libs/jalview-all-VERSION-j11.jar` with ```bash gradle shadowJar ``` -and run it with + +__NB__ `VERSION` will be replaced with a version number or "`DEVELOPMENT`" or "`TEST`" depending on how the branch is set up. + +Run it with ```bash -java -jar build/lib/jalview-all-11.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-11.jar` +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 @@ -406,17 +409,25 @@ looks to see if there's an updated file) to point to a particular Jalview channe 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`. +Note that the DEVELOP and RELEASE channels will normally use a getdown-launcher.jar that *does not* allow the +`file://` scheme to be used in the appbase. + 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: +There are several values of `CHANNEL` that can be chosen, with no choice leading to 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. +* `LOCAL`: This is for running the compiled application from the development directory and used by default. It will set - - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION` - (e.g. `file://home/user/git/jalview/getdown/files/11`) + - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION` + (e.g. `file://home/user/git/jalview/getdown/website/11`) - application subdir as `alt` - Getdown launcher can use a `file://` scheme appbase. + - Compile jalview with `gradle getdown` or `gradle shadowJar` + - Run Jalview on the command line without using the installers with, + Using getdown, e.g. `java -jar ./getdown/files/11/getdown-launcher.jar ./getdown/files/11 jalview` + or using the shadowJar with, e.g. `java -jar ./build/libs/jalview-all-TEST-j11.jar` * `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` @@ -466,10 +477,28 @@ e.g. gradle getdown -PCHANNEL=SCRATCH-my_test_version ``` +**New `CHANNEL` appearance features 2020-12-10** +There are now differing cosmetics for different channels, including application icons, Getdown splashscreen, +About splashscreen, Installer backgrounds, application name. This is controlled by the files in +``` +utils/channels +``` +In `utils/channels` there are different directories for the different channels. Currently there are directories for +`default`, `develop`, `release`, `test-release`, `jalviewjs` and `jalviewjs-release`. If a specified `CHANNEL` is not one of `DEVELOP`, `RELEASE`, `TEST-RELEASE`, `JALVIEWJS`, `JALVIEWJS-RELEASE` +then it will use the `default` directory. + +Inside the `utils/channels/` directory are: +- a file `channel_gradle.properties`. This will be used by the `build.gradle` script (i.e. any gradle build) to *override* the values found in `gradle.properties`. +- an `images` directory used to store different images referred to in this channels's `channel_gradle.properties`. +- a `resources` directory which is merged into the javliew.jar's own resources directory. Importantly it contains a `channel.props` file and another `images` dir which contains properties and images used by the application (in `jalview.util.ChannelProperties`), such as icon files or banner images, and the `app_name` property used as the display name for the application (e.g. "Jalview Develop") inside the application code. Please see the `getProperty` and `getImage` methods in `jalview.bin.ChannelProperties` to access these channel based resources. + + #### 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 + - `CHANNEL=RELEASE` will set version to jalview.version. + - `CHANNEL=TEST or DEVELOP` will append '-test' or '-develop' to jalview.version. + - `CHANNEL=JALVIEWJS` will use the `channel.props` found in `utils/channels/jalviewjs` but otherwise uses `LOCAL` settings. + - `CHANNEL=JALVIEWJS-RELEASE` uses a symbolic link to `utils/channels/jalviewjs` but otherwise uses `RELEASE` settings. It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property. @@ -536,7 +565,7 @@ We develop in Eclipse, and support settings to develop and save Jalview source c 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 +To get Jalview set up as a project in Eclipse, we recommend using at least the 2020-03 version of Eclipse IDE for Java Developers which you can download from the Eclipse website: . 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. @@ -560,7 +589,7 @@ Search for and install: 1. 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. +as the latest released version does not install in Eclipse 2020-03. However, you can install a working release of TestNG for Eclipse by going to > > Help->Install New Software... @@ -600,6 +629,14 @@ You can now import Jalview. If you have already downloaded Jalview using `git clone` then you can import this folder into Eclipse directly. +__Before importing the cloned git repo you must create the Eclipse project files.__ You can do this by either running + +`gradle eclipse` + +or + +Unzipping the file `utils/eclipse/eclipse_startup_files.zip` in the base repo directory (`jalview`) + It is important to import Jalview as a Gradle project (not as a Java project), so go to