Merge pull request #340 from HistoryAtState/breaking/update-build-too…

…ls-and-dependencies

breaking: Update build tools and dependencies

.gitignore

@@ -11,6 +11,7 @@ resources/scripts/app.min.js
 /templates
 # local properties
 **/local.build.properties
+!example.local.build.properties
 # IDE
 .idea
 .DS_Store

README.md

@@ -2,14 +2,29 @@
 
 ## Prerequisites
 
-You need to have *ant*, *git* and *nodeJS* (version 4 or 5) installed.
+You need to have *ant*, *git* and *nodeJS* (version 10.0.0 or higher) installed.
 
-### For Mac OS X
+### hsg-project users
 
-With **[homebrew](http://brew.sh#install)** installed, do
+All instructions are at https://github.com/HistoryAtState/hsg-project/wiki/Setup.
+
+### For other macOS users
+
+With **[homebrew](http://brew.sh#install)** installed, run:
 
     brew update && brew upgrade
-    brew install ant git node@6
+    brew install ant git node@10
+
+And follow homebrew's instructions to ensure that node 10's executables are 
+run:
+
+> If you need to have node@10 first in your PATH run:
+
+    echo 'export PATH="/usr/local/opt/node@10/bin:$PATH"' >> ~/.bash_profile
+
+Then:
+
+    source ~/.bash_profile
 
 ### Install global node packages
 
@@ -21,23 +36,21 @@ After node is installed just run
 
 1. Clone the repository
 
-    `git clone https://github.com/HistoryAtState/hsg-shell.git`
+        git clone https://github.com/HistoryAtState/hsg-shell.git
 
-1. Install dependencies for the front-end and automation tasks (`npm` & `bower`),
-    Build and copy javascripts, fonts, css and images into the *resources* folder (`gulp`) and
-    generate the *.xar-package* inside the *build* directory
+1. Build the application package
 
-    `ant`
+        ant
 
-1. Switch to the exist Dashboard
+1. Switch to the eXist Dashboard
 
-1. Install the package `build/hsg-shell-x.y.xar` with the Package Manager
+1. Install the package `build/hsg-shell-x.y.z.xar` with the Package Manager
 
 1. Click on the *history.state.gov* icon on the eXist Dashboard
 
 ## Update
 
-To create an up-to-date build package to install in eXistDB, this should do
+To create an up-to-date build package to install in eXist-db, this should do
 
     git pull && ant
 
@@ -54,14 +67,40 @@ To create an up-to-date build package to install in eXistDB, this should do
 
 `gulp deploy` sends the resource folder to a local existDB
 
-`gulp watch` will upload the build files whenever a source file changes
+`gulp watch` will upload the build files whenever a source file changes.
 
 **NOTE:** For the deploy and watch task you may have to edit the DB credentials in `gulpfile.js`.
 
 ## Build
 
 `ant` builds XAR file after running npm install bower install and gulp (build)
 
+## How to update Node and other build & development tools
+
+In order to build a xar package of the app with `ant` and to run scripts, that will build the app files like ie. minified css, js, you'll need to install `node.js`, `npm` and `gulp` in certain versions, that will be specified in this projects `package.json` and `npm-shrinkwrap.json` (for dependency locks).  
+
+### Update node and npm versions
+
+1. Update your system to `node v10.0.0` either via using [nvm](https://github.com/nvm-sh/nvm), or directly from the [node website](https://nodejs.org/en/).
+1. Check your current node version with `node --version`, it should be `v10.0.0` now.
+1. Install (or update to) the latest `npm` version with `npm install -g npm`.
+1. Install bower `npm install -g bower`.
+1. Install gulp `npm install -g gulp`. The project's gulp file depends on `gulp 4` (or higher) syntax, so make sure in the next step, that you'll have gulp 4.x running.
+1. Check the paths, where your node, npm and gulp have been installed (depends on OS) by running `which node`,
+`which npm`, `which gulp`.
+1. Look for file `example.local.build.properties`, copy it, rename it to `local.build.properties` and insert the current paths you just got by running the "which" commands. This file is necessary for pointing the ant task runner to the necessary build tools.
+1. Install the node packages (listed in file `package.json`) by running `npm install` .
+1. If npm errors occur, try fix it either by running `npm update`, or by
+deleting the entire `node_modules` folder from the project and then running `npm install` once again.
+1. Last, you may have to edit the credentials in file `local.node-exist.json` which is needed for configure the automated deployment of files from your local HSG-Shell project to your local existdb. The defaults in this file will generally apply here, unless you have modified the credentials elsewhere.
+
+### Finally check currently installed versions
+1. node: `node -v` => Should output `v10.0.0`
+2. npm: `npm -v` => Should output at least `v6.9.0`
+3. gulp: `gulp -v` => Should output at least `CLI version: 2.2.0, Local version: 4.0.2`
+
+Now, with a running eXist-db you're ready to run either `ant` or `gulp` to test if your update was successful.
+
 ### Production
 
 If `NODE_ENV` environment variable is set to **production** the XAR is build with

build.properties

@@ -3,7 +3,14 @@
 # edit that.
 #
 
-# paths to executables
-npm=/usr/local/opt/node@6/bin/npm
+# Note: Building and installing packages via the External Tools defined in the 
+# hsg-project.xpr oXygen project file requires that absolute paths be provided 
+# for npm and gulp. For command line execution, simply providing "npm" and 
+# "gulp" is sufficient, and any custom path variable that resolves the locations 
+# of these commands is sufficient. The default values provided here assume the 
+# hsg-project setup. For other environemnts, create a local.build.properties 
+# file with your values.
+
+npm=/usr/local/opt/node@10/bin/npm
 gulp=/usr/local/bin/gulp
-node.PATH=/usr/local/opt/node@6/bin:/usr/local/bin
+node.PATH=/usr/local/opt/node@10/bin:/usr/local/bin

build.xml

@@ -29,7 +29,7 @@
         <echo message="${npm.output}"/>
         <echo message="Creating xar package..."/>
         <zip basedir="." destfile="${build.dir}/${project.app}-${project.version}.xar"
-            excludes="${build.dir}/** node_modules/** package.json gulpfile.js .*"/>
+            excludes="${build.dir}/** node_modules/** package.json gulpfile.js .idea/** .* example.local.build.properties npm-shrinkwrap.json"/>
     </target>
     <target name="clean">
         <echo message="Calling gulp clean..."/>

example.local.build.properties

@@ -0,0 +1,14 @@
+# THIS IS AN EXAMPLE FILE. Read the note below and save your changes to a new
+# "local.build.properties" file.
+
+# Note: Building and installing packages via the External Tools defined in the 
+# hsg-project.xpr oXygen project file requires that absolute paths be provided 
+# for npm and gulp. For command line execution, simply providing "npm" and 
+# "gulp" is sufficient, and any custom path variable that resolves the locations 
+# of these commands is sufficient. The default values provided here assume the 
+# hsg-project setup. For other environemnts, create a local.build.properties 
+# file with your values.
+
+npm=/usr/local/opt/node@10/bin/npm
+gulp=/usr/local/bin/gulp
+node.PATH=/usr/local/opt/node@10/bin:/usr/local/bin

expath-pkg.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <package xmlns="http://expath.org/ns/pkg" name="http://history.state.gov/ns/site/hsg"
-    abbrev="hsg-shell" version="1.0.1" spec="1.0">
+    abbrev="hsg-shell" version="2.0.1" spec="1.0">
     <title>history.state.gov 3.0 shell</title>
     <dependency package="http://exist-db.org/apps/shared"/>
     <dependency package="http://www.tei-c.org/tei-simple"/>