JAVA-11-README

   1 2019-07-01 (pre 2.11.0 release)
   2 Notes below are out of date, but might be useful for future development with Java 11
   3
   4 Presently the Java 11 build of Jalview treats all libraries as libraries on the classpath, and does not use them as modules. The Java 11 JRE prepped for future release is a standard AdoptOpenJDK release (possibly repackaged for getdown/install4j to use).
   5
   6 Future releases might incorporate Java 11 modules into a bespoke Java 11 JRE that can be updated over the air via getdown.This could reduce the size of the distribution but will absolutely need the bespoke JRE.  This would mean Jalview being restricted to platforms that we (can) support, or distributing the modules as libraries in a second distribution (the shadowJar distribution).
   7
   8 build.gradle is written to support compilation of either Java 1.8 or Java 11 compatible bytecode.  Please note that the compilation (and therefore build) process REQUIRES a Java 11 (or above) JDK.  This is because there is Java 11 specific code in some Jalview classes (devolved into separate classes which fail "gracefully" when read by a Java 1.8 JRE).
   9 Java 11 is therefore the default build target, but can be changed simply by specifying the property JAVA_VERSION=1.8 (e.g.
  10
  11 gradle compileJava -PJAVA_VERSION=1.8
  12
  13 ).  Some different versions of supporting libraries are used between Java 1.8 and 11 builds, and can be found in j8lib and j11lib folders respectively.  Note that there are a number of extra libraries used in the Java 11 distribution which are present in the Java 1.8 JRE but not distributed with the Java 11 JRE.
  14
  15 Also see doc/building.md or doc/building.html
  16
  17
  18
  19
  20 Old notes:
  21
  22 Java 11 module replacements
  23
  24 As Java 11 no longer ships with Java EE libraries, which were standard in Java 8, and available (modularised, through the --add-modules CLI mechanism) in Java 9 and 10, third party replacement libraries for these libraries/modules have to be found.
  25
  26 Ideally, these jar files would be packaged as modules (i.e. would contains a module-info.class with the relevant provision and requirements information for that module package).  However, as at time of writing (end Nov 2018) the available packages are not fully mature.
  27 There also seems to be no single place to look when trying to obtain modules jar files.
  28
  29 A couple of good places to start:
  30 https://javaee.github.io/
  31 (see Metro, Glassfish etc)
  32
  33 https://search.maven.org/
  34 (search for e.g. a:javax.activation)
  35
  36 https://mvnrepository.com/
  37 (if the other two fail!)
  38
  39 Unfortunately there seems to be multiple projects providing the same modules, with little indication of which is "best".
  40 Here's an example of what to do with search.maven.org, looking for, say, the java.activation module
  41
  42 Firstly, remember this might be called javax.activation (in fact it is), so searching for
  43
  44 a:javax.activation
  45
  46 shows 3 possible candidates.
  47
  48 The "Updated" date gives a clue if a library might be up-to-date or still being maintained, and of the three listed, com.sun.activation version 1.2.0 was updated in Sep 2017, and is the only one updated in the last 5 years, so it looks like a good candidate.
  49 Click on the arrow in the Download column which gives various download options.  Choose "jar" and this should download straight away.
  50
  51 If you have a peek inside the jar file:
  52
  53 $ jar -tvf ~/Downloads/javax.activation-1.2.0.jar
  54
  55      0 Wed Sep 06 16:13:08 BST 2017 META-INF/
  56   1307 Wed Sep 06 16:13:06 BST 2017 META-INF/MANIFEST.MF
  57      0 Wed Sep 06 14:23:50 BST 2017 javax/
  58      0 Wed Sep 06 14:23:50 BST 2017 javax/activation/
  59      0 Wed Sep 06 14:23:50 BST 2017 com/
  60      0 Wed Sep 06 14:23:50 BST 2017 com/sun/
  61      0 Wed Sep 06 14:23:50 BST 2017 com/sun/activation/
  62 ...
  63   2238 Wed Sep 06 14:23:50 BST 2017 com/sun/activation/registries/LineTokenizer.class
  64  39394 Wed Sep 06 16:13:06 BST 2017 META-INF/LICENSE.txt
  65    581 Wed Sep 06 16:13:06 BST 2017 META-INF/mimetypes.default
  66    292 Wed Sep 06 16:13:06 BST 2017 META-INF/mailcap.default
  67      0 Wed Sep 06 16:13:08 BST 2017 META-INF/maven/
  68      0 Wed Sep 06 16:13:08 BST 2017 META-INF/maven/com.sun.activation/
  69      0 Wed Sep 06 16:13:08 BST 2017 META-INF/maven/com.sun.activation/javax.activation/
  70   6515 Fri Sep 01 16:13:04 BST 2017 META-INF/maven/com.sun.activation/javax.activation/pom.xml
  71    119 Wed Sep 06 14:23:52 BST 2017 META-INF/maven/com.sun.activation/javax.activation/pom.properties
  72
  73
  74 you can see that it doesn't have a module-info.class file, meaning it can only be used as an "automatic" module.  This will probably mean it can't be used with jlink when creating a JRE.
  75 HAVE NO FEAR!
  76 We can semi-manually (urgh!) create a module-info.class for this library and turn it into a module.  This really should be scripted. I might just do it.
  77
  78 So, assuming we downloaded that jar to ~/Downloads/javax.activation-1.2.0.jar, and JAVA_HOME is set to a java distribution, we can do:
  79
  80 mkdir tmp
  81 cd tmp
  82 jar -xvf ~/Downloads/javax.activation-1.2.0.jar
  83 jdeps --generate-module-info . ~/Downloads/javax.activation-1.2.0.jar
  84 # --generate-module-info creates the module-info.java file we are looking for! but for some reason insists on sticking it in a java.activation subdir (even though we ask for '.')
  85 mv java.activation/module-info.java .
  86 rmdir java.activation
  87 javac -d . module-info.java
  88 # we could clean up (rm) module-info.java, but I think it'll be more useful to keep a hold of it in the jar, it's not causing a problem or taking up space
  89 cd ..
  90 jar -cvf javax.activation-1.2.0-MODULE.jar -C ./tmp .
  91 /bin/rm -rf ./tmp
  92
  93 and voila, you have a modulified version of the library in the jar file ./javax.activation-1.2.0-MODULE.jar.  This can be used with jlink.
  94 [ timeout: I scripted this as utils/modulify.sh  Usage: modulify.sh /path/to/jarfile.jar  ... creates /path/to/jarfile-MODULE.jar ]
  95
  96 Once we have enough modulified jar files (note, we kind of keep downloading a new file or files until jalview starts without Exceptions, jdeps could probably provide a better way(!), and jaxws-rt provides quite a few of the needed jar files, hopefully in a coherent way).
  97
  98 A list of module dependencies can be found with (note module-path doesn't need jar files, just the dirs to look in, unlike class-path)
  99
 100 jdeps --class-path="lib/*:j11lib/*" --module-path="$JAVA_HOME/jmods:j11lib" --list-deps dist/jalview.jar libs/*.jar
 101
 102 will end with a list of modules required in the JRE, these need to be comma-separated-listed for jlink.  We /ought/ to be able to do this by using "--print-module-deps" like this
 103
 104 jdeps --class-path="lib/*:j11lib/*" --module-path="$JAVA_HOME/jmods:j11lib" --print-module-deps dist/jalview.jar libs/*.jar
 105
 106 but that ends with an Exception.  Perhaps should look into that...
 107
 108 Anyway, with the list of modules required (in the file "modules") you can do
 109
 110 jlink --module-path $JAVA_HOME/jmods:j11lib --compress=2 --add-modules `cat modules` --no-header-files --no-man-pages --bind-services --output j11jre/openjdk11_platform
 111
 112 To create a Java 11 JRE in j11jre/openjdk11_platform (or whatever you wish to call it).
 113 You can point JAVA_HOME at the JDK11 of a different platform, so long as the jlink in your path is to the jlink for the platform you're running on.
 114