From 4753dd3b49c365e4add16193d94985e007c4f773 Mon Sep 17 00:00:00 2001
From: Carl Eberhard <carlfeberhard@gmail.com>
Date: Wed, 17 Sep 2014 11:28:16 -0400
Subject: [PATCH] Client build system, pack_scripts: the build system will now
 call pack_scripts on all files in static/scripts when called via 'grunt' or
 'grunt pack', and pack_scripts automatically only on those that have changed
 when using 'grunt watch'; add README.txt

---
 client/GruntFile.js | 34 ++++++++++++++++++++++++++++++++--
 client/README.txt   | 42 ++++++++++++++++++++++++++++++++++++++++++
 client/package.json |  3 ++-
 3 files changed, 76 insertions(+), 3 deletions(-)
 create mode 100644 client/README.txt

diff --git a/client/GruntFile.js b/client/GruntFile.js
index 08028fb11a2..9d42d7dcb33 100644
--- a/client/GruntFile.js
+++ b/client/GruntFile.js
@@ -19,11 +19,31 @@ module.exports = function(grunt) {
       }
     },
 
+    // use 'grunt pack' to call pack_scripts.py to pack all or selected files in static/scripts
+    exec: {
+      packScripts: {
+        cwd: '../static/scripts',
+        target: [],
+        cmd: function(){
+          var targets = grunt.config( 'exec.packScripts.target' );
+          // if nothing was passed in pack all scripts
+          if( !targets.length ){
+            return './pack_scripts.py';
+          }
+
+          grunt.log.write( 'packing: ' + targets + '\n' );
+          return targets.map( function( target ){
+            return './pack_scripts.py ' + target;
+          }).join( '; ' );
+        }
+      }
+    },
+
     // use 'grunt watch' (from a new tab in your terminal) to have grunt re-copy changed files automatically
     watch: {
         // watch for changes in the src dir
         files: [ 'galaxy/scripts/**' ],
-        tasks: [ 'copy' ],
+        tasks: [ 'copy', 'pack' ],
         options: {
           spawn: false
         }
@@ -32,11 +52,20 @@ module.exports = function(grunt) {
 
   grunt.loadNpmTasks( 'grunt-contrib-watch' );
   grunt.loadNpmTasks( 'grunt-contrib-copy');
+  grunt.loadNpmTasks('grunt-exec');
 
+  grunt.registerTask( 'pack', [ 'exec' ] );
+  grunt.registerTask( 'default', [ 'copy', 'pack' ] );
+
+  // -------------------------------------------------------------------------- copy,pack only those changed
   // adapted from grunt-contrib-watch jslint example
   //TODO: a bit hacky and there's prob. a better way
   //NOTE: copy will fail silently if a file isn't found
+
+  // outer scope variable for the event handler and onChange fn - begin with empty hash
   var changedFiles = Object.create(null);
+
+  // when files are changed, set the copy src and packScripts target to the filenames of the updated files
   var onChange = grunt.util._.debounce(function() {
     grunt.config( 'copy.main.files', [{
       expand: true,
@@ -44,8 +73,10 @@ module.exports = function(grunt) {
       src: Object.keys( changedFiles ),
       dest: '../static/scripts/'
     }]);
+    grunt.config( 'exec.packScripts.target', Object.keys( changedFiles ) );
     changedFiles = Object.create(null);
   }, 200);
+
   grunt.event.on('watch', function(action, filepath) {
     // store each filepath in a Files obj, the debounced fn above will use it as an aggregate list for copying
     // we need to take galaxy/scripts out of the filepath or it will be copied to the wrong loc
@@ -54,5 +85,4 @@ module.exports = function(grunt) {
     onChange();
   });
 
-  grunt.registerTask( 'default', [ 'copy' ] );
 };
diff --git a/client/README.txt b/client/README.txt
new file mode 100644
index 00000000000..e21f8a9417d
--- /dev/null
+++ b/client/README.txt
@@ -0,0 +1,42 @@
+Client Build System
+===================
+
+Builds and moves the client-side scripts necessary for running the Galaxy webapps. There's no need to use this system
+unless you are modifying or developing client-side scripts.
+
+You'll need Node and the Node Package Manager (npm): nodejs.org.
+
+Once npm is installed, install the grunt task manager and it's command line into your global scope:
+
+    npm install -g grunt grunt-cli
+
+Next, from within this directory, install the local build dependencies:
+
+    cd client
+    npm install
+
+You're now ready to re-build the client scripts after modifying them.
+
+
+Rebuilding
+==========
+
+There are two methods for rebuilding: a complete rebuild and automatic, partial rebuilds while you develop.
+
+A complete rebuild can be done with the following (from the `client` directory):
+
+    grunt
+
+This will copy any files in `client/galaxy/scripts` to `static/scripts` and run `static/scripts/pack_scripts.py` on all.
+
+Grunt can also do an automatic, partial rebuild of any files you change *as you develop* by:
+
+    1. opening a new terminal session
+    2. `cd client`
+    3. `grunt watch`
+
+This starts a new grunt watch process that will monitor the files in `client/galaxy/scripts` for changes and copy and
+pack them when they change.
+
+You can stop the `grunt watch` task by pressing `Ctrl+C`. Note: you should also be able to background that task if you
+prefer.
diff --git a/client/package.json b/client/package.json
index 6fb9a1fd513..36cce5fad0d 100644
--- a/client/package.json
+++ b/client/package.json
@@ -8,6 +8,7 @@
   "devDependencies": {
     "grunt": "^0.4.5",
     "grunt-contrib-copy": "^0.5.0",
-    "grunt-contrib-watch": "^0.6.1"
+    "grunt-contrib-watch": "^0.6.1",
+    "grunt-exec": "^0.4.6"
   }
 }