# download
git clone http://source.jalview.org/git/jalview.git
# compile
-cd jalview
+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
# use launcher
-cd getdown/files
+cd ./build/getdown/files/11
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
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
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 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/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
+> 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.
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
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`
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/<channelname>` 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.
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: <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.
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...
+> Help->Install New Software...
>
-and entering
+> and entering
>
-`TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release`
+> `TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release`
>
-into the *Work with* box and click on the *Add...* button.
+> 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
+> 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
+> 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](#java-11-compliant-jdk)).
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
git://source.jalview.org / jalview.git / blobdiff