README_GRADLE_JALVIEWJS-2019-10-22.md

   1 Last updated: 2019-10-22
   2
   3 # TRANSPILING USING ECLIPSE AS AN EXTERNAL CLI TOOL:
   4
   5
   6 1) Download and install a clean eclipse jee-2019-09:
   7
   8 RECOMMEND using the eclipse installer found at https://www.eclipse.org/downloads/packages/installer
   9 and installing in ~/buildtools/eclipse/jee-2019-09 (which is what the gradle.properties property jalviewjs_eclipse_root is set to by default).
  10
  11
  12 2) Check the `jalviewjs_eclipse_root` property in `gradle.properties`:
  13
  14 If you have an eclipse 2019-06 or 2019-09 installed already elsewhere that you want to try and use then change the
  15 ```
  16 jalviewjs_eclipse_root
  17 ```
  18 property in gradle.properties to point to the folder that the application is installed in.  If you are on macOS this is the folder _above_ Eclipse.app (i.e. the folder Eclipse.app is in).
  19 If on Windows or Linux then this can be the folder that the eclipse installer says it is installing too (usually something like `.../jee-2019-09`) (even though it then installs it to a folder `eclipse` under that) or the folder the eclipse binary and plugins folders etc are in (`build.gradle` will check both the folder stated in `jalviewjs_eclipse_root` and `${jalviewjs_eclipse_root}/eclipse`).
  20
  21 You can use a '~' as the first character which will get replaced with `System.getProperty("user.home")`.
  22
  23
  24 3) That's it, but note the following:
  25
  26 i) Note that the gradle task (`jalviewjsEclipseCopyDropins`) will take care of copying the appropriate `net.sf.j2s.core.jar` and the `com.seeq.eclipse.importprojects.jar` into the `dropins` dir (tested on both unix or mac -- not tested on windows yet).
  27
  28 ii) Note that we have two versions of `net.sf.j2s.core.jar`, currently manifesting in two different `utils/jalviewjs/eclipse/dropins_4.1?` folders.  This is because the behaviour of eclipse changed between 2019-06 (4.12) and 2019-09 (4.13) that meant the `src` and `test` BuildContexts are separated during the Eclipse build.  This overwrites the list of classes to be transpiled with the set of classes from the last BuildContext to be compiled (which inevitablt seems to be tests).  The way the file paths are represented must also have changed so that the exclusion from `j2s.ecluded.paths` in the `.j2s` file are not honoured.
  29 I have made a fixed version of `net.sf.j2s.core_3.2.4-FOR_4.13.jar` that ought to be backward compatible, but for unknown reason doesn't work in eclipse 4.12.
  30 Hopefully this is temporary and Bob can incorporate a properly backward compatible fix.
  31
  32 iii) Note that the logs from the transpile go into `build/jalviewjs/j2s-transpile.out` which combines both stdout and stderr.
  33
  34
  35 # CLI
  36
  37 gradle tasks possibly of interest to you:
  38 ```
  39 gradle jalviewjs  # (should build the build/jalviewjs/site dir)
  40
  41 gradle jalviewjsSiteTar  # will produce build/distribution/site.tar.gz
  42
  43 gradle jalviewjsTranspile  # should run a new eclipse compile+transpile
  44
  45 gradle jalviewjsServerStart  # will run a localhost http server to allow you to test the site in a browser.  Just use the URL given in the output.  To stop the server you have to do  gradle --stop  or you can just leave it running until the gradle daemon dies.
  46 ```
  47
  48 If it's working okay, you just need to to
  49 ```
  50 gradle jalviewjs
  51 gradle jalviewjsServer
  52 ```
  53 and go to the localhost URL in the output of the jalviewjsServer task in your web browser (on a mac, just right clicking on the URL in terminal window gives an "Open URL" option which is nice and easy).
  54
  55
  56 # IN ECLIPSE
  57
  58 If you are developing in Eclipse as IDE (which is the natural way to use Eclipse!) and have the plugin installed, then you will obviously not need to run the transpile as a gradle task -- it will be performed automatically.
  59
  60 Some things to remember:
  61 i) You will need the buildship plugin (part of the JEE package).
  62 ii) If you haven't already, remember to run on the CLI
  63 ```
  64 gradle cleanEclipse eclipse jalviewjsCreateJ2sSettings
  65 ```
  66 to create clean jalview `.classpath, .project, .settings/org.eclipse.jdt.core.prefs, .j2s` files.
  67 You should only need to do this once.
  68 Be aware that manual changes to these files will likely be overwritten during some gradle tasks.
  69
  70