build: added "building from scratch" doco; better integration of grun…

…t and lodash into nodel-webui-js component

BUILDING.md

@@ -0,0 +1,116 @@
+# Building from scratch
+* **gradle** is the primary build tool for the main Java project (runs on **Java**)
+* **grunt** (runs on **Node.js**, installed via **npm**) is used by the **nodel-webui-js** project component
+
+The steps below describe usage on both Windows and Linux
+* The example refers to **Windows**
+* The section further below shows complete example for **Linux**
+
+---
+
+## STEP 1: ENSURE PRIMARY DEPENDENCIES ARE PRESENT
+  1. **Java JDK 8**, see [latest versions](https://adoptopenjdk.net/releases.html)
+      * latest Windows [OpenJDK8U-jdk_x64_windows_hotspot_8u242b08.zip](https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u242-b08/OpenJDK8U-jdk_x64_windows_hotspot_8u242b08.zip)
+      * latest Linux [OpenJDK8U-jdk_x64_linux_hotspot_8u242b08.tar.gz](https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u242-b08/OpenJDK8U-jdk_x64_linux_hotspot_8u242b08.tar.gz)
+  2. **Node.js**, see [latest versions](https://nodejs.org/en/download/)
+      * latest Windows [node-v12.16.2-win-x64.zip](https://nodejs.org/dist/v12.16.2/node-v12.16.2-win-x64.zip)
+      * latest Linux [node-v12.16.2-linux-x64.tar.xz](https://nodejs.org/dist/v12.16.2/node-v12.16.2-linux-x64.tar.xz)
+  3. **Git**, see [latest versions](https://git-scm.com/download)
+      * latest Windows [PortableGit-2.26.0-64-bit.7z.exe](https://github.com/git-for-windows/git/releases/download/v2.26.0.windows.1/PortableGit-2.26.0-64-bit.7z.exe)
+      * Linux install `apt-get install git`
+
+ * all support "portable" installation, examples here are extracted to `C:\Apps`
+
+## STEP 2: ENSURE SECONDARY DEPENDENCIES ARE 'INSTALLED'
+* ensure primary dependencies, above, are on path, e.g. on Windows:
+```bat
+set PATH=%PATH%;C:\Apps\node-v12.16.2-win-x64;C:\Apps\git\bin;C:\Apps\jdk8u242-b08\bin
+```
+* install **grunt** and **lodash** into the "global" location (sits alongside **Node.js** binaries)
+   * `npm install -g grunt-cli lodash-cli`
+
+## STEP 3: ENSURE REPOSITORY IS CLONED
+* ensure primary dependencies, above, are on path (see example in STEP 2, above)
+* then Clone! e.g. cloning into `c:\temp\nodel-build` directory:
+```bat
+git clone https://github.com/museumsvictoria/nodel c:\temp\nodel-build
+```
+
+## STEP 4: EXECUTE BUILD
+* Build! Example, from the `c:\temp\nodel-build` directory:
+```bat
+cd  c:\Temp\nodel-build
+gradlew build
+```
+* check `nodel-jyhost/build/distributions/standalone` directory for binary release e.g. `nodelhost-dev-2.2.1-rev407.jar`
+
+---
+
+**Full example using clean Linux environment¹**
+
+```bash
+# download and extract Java
+wget https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u242-b08/OpenJDK8U-jdk_x64_linux_hotspot_8u242b08.tar.gz
+tar xf OpenJDK8U-jdk_x64_linux_hotspot_8u242b08.tar.gz
+# ends up in ./jdk8u242-b08
+
+# download and extract Node.js (and npm)
+wget https://nodejs.org/dist/v12.16.2/node-v12.16.2-linux-x64.tar.xz
+tar xf node-v12.16.2-linux-x64.tar.xz
+# ends up in ./node-v12.16.2-linux-x64
+
+# (git is normally already available)
+
+# adjust PATH
+export PATH=$PATH:~/jdk8u242-b08/bin/:~/node-v12.16.2-linux-x64/bin/
+
+# install 'grunt' and 'lodash' in "global" location
+npm install -g grunt-cli lodash-cli
+
+# quickly verify versions of all dependencies
+java -version 
+# e.g. >> openjdk version "1.8.0_242"
+node --version
+# e.g. >> v12.16.2
+git version
+# e.g. >> git version 2.25.1
+grunt --version
+# e.g. >> grunt-cli v1.3.2
+lodash --version
+# e.g. >> 4.17.5
+
+# clone repo
+git clone https://github.com/museumsvictoria/nodel nodel-build
+
+# execute full build
+cd ~/nodel-build
+./gradlew build
+
+# check output (standalone JAR file)
+ls ~/nodel-build/nodel-jyhost/build/distributions/standalone/
+
+# run Nodel (optional)
+java -jar ~/nodel-build/nodel-jyhost/build/distributions/standalone/nodelhost-dev-2.2.1-rev407.jar -p 0
+```
+
+**Source update, clean and build re-run**
+```
+cd ~/nodel-build
+git pull
+
+./gradlew clean
+# or
+git clean -fxd
+
+./gradlew build
+```
+
+**Full cleanup**
+```bash
+rm -fr ~/jdk8u242-b08
+rm -fr ~/node-v12.16.2-linux-x64
+rm -fr ~/nodel-build
+```
+
+---
+¹ For OSX, adjust to suit.

README.md

@@ -100,15 +100,13 @@ Quick start
 
 Building and releases
 =====================
-* Latest releases can be found in [github releases](https://github.com/museumvictoria/nodel/releases)
-* To build from scratch, clone repository and use [Gradle](http://www.gradle.org/):
-  * `gradle :nodel-jyhost-java:build`
-  * Check `nodel-jyhost-java\build\distributions\standalone` directory
+* Latest releases can be found in [github releases](https://github.com/museumsvictoria/nodel/releases)
+* Can be easily built from scratch using these [instructions](BUILDING.md)
 
 Notes
 =====
 * thoroughly road tested with Java 8 (available from [AdoptOpenJDK](https://adoptopenjdk.net/))
-* for service / daemon use, see [wiki pages](https://github.com/museumvictoria/nodel/wiki)
+* for service / daemon use, see [wiki pages](https://github.com/museumsvictoria/nodel/wiki)
 * check `bootstrap` files for startup config
 
 Licenses
@@ -120,6 +118,6 @@ Licenses
 Credits
 =======
 
-Nodel is a joint venture established between [Museums Victoria](http://museumvictoria.com.au) and [Automatic](http://automatic.com.au). It was imagined as a replacement for Museum Victoria’s gallery control system at the time.
+Nodel is a joint venture established between [Museums Victoria](http://museumsvictoria.com.au) and [Automatic](http://automatic.com.au). It was imagined as a replacement for Museum Victoria’s gallery control system at the time.
 
-You may find out more about the Nodel project on the [White Paper](https://raw.githubusercontent.com/museumvictoria/nodel/gh-pages/docs/White_Paper-Nodel.pdf).
+You may find out more about the Nodel project on the [White Paper](https://raw.githubusercontent.com/museumsvictoria/nodel/gh-pages/docs/White_Paper-Nodel.pdf).

nodel-webui-js/build.gradle

@@ -60,12 +60,28 @@ def buildSummary = gitId.output();
 if (!branch.equals("stable"))
     version project.version + "-" + branch + "_r" + rev
 
+// <!-- grunt is embedded (via npm via node.js)
+
+task npmInstall(type:Exec) {  
+  if (System.getProperty('os.name').toLowerCase(Locale.ROOT).contains('windows'))
+    commandLine 'npm.cmd', 'install'
+  else
+    commandLine 'npm', 'install'
+}
+
 task grunt(type:Exec) {  
   if (System.getProperty('os.name').toLowerCase(Locale.ROOT).contains('windows'))
     commandLine 'grunt.cmd'
   else
     commandLine 'grunt'
-} 
+}
+
+clean.doFirst {
+    delete "${projectDir}/node_modules/"
+    delete "${projectDir}/temp/"
+}
+
+// grunt --!>
 
 task copyContent(type: Copy) {
     from new File(project.buildDir, 'grunt')
@@ -112,6 +128,7 @@ task preBuild << {
     tasks.cleanZipContentInterface.execute()
     tasks.cleanCopyContent.execute()
 
+    tasks.npmInstall.execute()
     tasks.grunt.execute()
 
     tasks.copyContent.execute()