git://source.jalview.org / jalview.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
close filehandles straight after parse, without setting an error
[jalview.git] / doc / building.md
diff --git a/doc/building.md b/doc/building.md
index 398181a..497e722 100644 (file)
--- 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
 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
 
 # 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
 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 
 * git
 
 > The versions and installation methods here are just suggestions (which we have tested 
@@ -165,6 +165,7 @@ Within the `jalview` folder you will find (of possible interest):
  `utils/install4j/`  | files used by the packaging tool, install4j
  `build.gradle`      | the build file used by gradle
  `gradle.properties` | configurable properties for the build process
  `utils/install4j/`  | files used by the packaging tool, install4j
  `build.gradle`      | the build file used by gradle
  `gradle.properties` | configurable properties for the build process
+ `RELEASE`          | propertyfile configuring JALVIEW_VERSION (from jalview.version) and the release branch (from jalview.release). An alternative file can be specified via JALVIEW_RELEASE_FILE property
 
 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
 
 
 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
 
@@ -247,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.
 
 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
 ```
 
 ```bash
 gradle shadowJar
 ```
-and run it with
+
+__NB__ `VERSION` will be replaced with a version number or "`DEVELOPMENT`" depending on how the branch is set up.
+
+Run it with
 
 ```bash
 
 ```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 
 ```
 
 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 
 just by double-clicking on it)!
 
 > The `shadowJar` task is not a requirement for any other task, so to build the shadow 
@@ -275,8 +279,8 @@ although without the many and compelling benefits of the `getdown` launcher.
 We have made significant customisations to the `getdown` launcher which you can find 
 in `getdown/src/getdown`.
 
 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 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
 >
 you'll need a working Maven and also a Java 8 JDK.  Ensure the Java 8 `javac` is forefront 
 in your path and do
 >
@@ -284,9 +288,9 @@ 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/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 
+> 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. 
 needs to be copied to `getdown/lib`.
 >
 >The `mvn` command should ideally include the `-Dgetdown.host.whitelist=*.jalview.org` setting. 
@@ -317,6 +321,7 @@ java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
 getdown, and the final argument, "`jalview`", is a getdown application id (only "`jalview`" 
 is defined here).
 
 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
 
 
 ### Running tests
 
@@ -422,7 +427,7 @@ There are several values of `CHANNEL` that can be chosen, with a default of `LOC
       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. 
       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.
+* `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`
   It will set
     - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
     - application subdir as `alt`
@@ -465,6 +470,13 @@ 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.
+
 #### `install4jMediaTypes`
 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.
 #### `install4jMediaTypes`
 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.
@@ -528,7 +540,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.
 
 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.
 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.
@@ -552,7 +564,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 
 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...
 However, you can install a working release of TestNG for Eclipse by going to
 >
 Help->Install New Software...
@@ -592,6 +604,14 @@ You can now import Jalview.
 
 If you have already downloaded Jalview using `git clone` then you can import this folder into Eclipse directly.
 
 
 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
 
 It is important to import 
 Jalview as a Gradle project (not as a Java project), so go to