Refactor the build tasks to be more foolproof, including the parser unless it’s explicitly excluded

Author: GeoffreyBooth

Cakefile

@@ -24,15 +24,34 @@ header = """
    */
 """
 
-# Used in folder names like docs/v1
+# Used in folder names like `docs/v1`.
 majorVersion = parseInt CoffeeScript.VERSION.split('.')[0], 10
 
+
 # Build the CoffeeScript language from source.
-build = (cb) ->
+buildParser = ->
+  helpers.extend global, require 'util'
+  require 'jison'
+  parser = require('./lib/coffee-script/grammar').parser.generate()
+  # Patch Jison’s output, until https://github.com/zaach/jison/pull/339 is accepted,
+  # to ensure that require('fs') is only called where it exists.
+  parser = parser.replace "var source = require('fs')", """
+      var source = '';
+          var fs = require('fs');
+          if (typeof fs !== 'undefined' && fs !== null)
+              source = fs"""
+  fs.writeFileSync 'lib/coffee-script/parser.js', parser
+
+buildExceptParser = (cb) ->
   files = fs.readdirSync 'src'
   files = ('src/' + file for file in files when file.match(/\.(lit)?coffee$/))
   run ['-c', '-o', 'lib/coffee-script'].concat(files), cb
 
+build = (cb) ->
+  buildParser()
+  buildExceptParser cb
+
+
 # Run a CoffeeScript through our node/coffee interpreter.
 run = (args, cb) ->
   proc =         spawn 'node', ['bin/coffee'].concat(args)
@@ -41,14 +60,19 @@ run = (args, cb) ->
     process.exit(1) if status isnt 0
     cb() if typeof cb is 'function'
 
+
 # Log a message with a color.
 log = (message, color, explanation) ->
   console.log color + message + reset + ' ' + (explanation or '')
 
 
-task 'build', 'build the CoffeeScript language from source', build
+task 'build', 'build the CoffeeScript compiler from source', build
+
+task 'build:parser', 'build the Jison parser only', buildParser
+
+task 'build:except-parser', 'build the CoffeeScript compiler, except for the Jison parser', buildExceptParser
 
-task 'build:full', 'rebuild the source twice, and run the tests', ->
+task 'build:full', 'build the CoffeeScript compiler from source twice, and run the tests', ->
   build ->
     build ->
       csPath = './lib/coffee-script'
@@ -60,22 +84,7 @@ task 'build:full', 'rebuild the source twice, and run the tests', ->
       unless runTests require csPath
         process.exit 1
 
-
-task 'build:parser', 'rebuild the Jison parser (run build first)', ->
-  helpers.extend global, require 'util'
-  require 'jison'
-  parser = require('./lib/coffee-script/grammar').parser.generate()
-  # Patch Jison’s output, until https://github.com/zaach/jison/pull/339 is accepted,
-  # to ensure that require('fs') is only called where it exists.
-  parser = parser.replace "var source = require('fs')", """
-      var source = '';
-          var fs = require('fs');
-          if (typeof fs !== 'undefined' && fs !== null)
-              source = fs"""
-  fs.writeFileSync 'lib/coffee-script/parser.js', parser
-
-
-task 'build:browser', 'rebuild the merged script for inclusion in the browser', ->
+task 'build:browser', 'build the merged script for inclusion in the browser', ->
   code = """
   require['../../package.json'] = (function() {
     return #{fs.readFileSync "./package.json"};

docs/v1/index.html

@@ -2584,9 +2584,9 @@ <h2>Resources</h2><ul>
 <li><p><a href="http://github.com/jashkenas/coffeescript/">Source Code</a><br>
 Use <code>bin/coffee</code> to test your changes,<br>
 <code>bin/cake test</code> to run the test suite,<br>
-<code>bin/cake build</code> to rebuild the CoffeeScript compiler, and<br>
-<code>bin/cake build:parser</code> to regenerate the Jison parser if you’re working on the grammar.</p>
-<p><code>git checkout lib &amp;&amp; bin/cake build:full</code> is a good command to run when you’re working on the core language. It’ll refresh the lib directory (in case you broke something), build your altered compiler, use that to rebuild itself (a good sanity test) and then run all of the tests. If they pass, there’s a good chance you’ve made a successful change.</p>
+<code>bin/cake build</code> to rebuild the full CoffeeScript compiler, and<br>
+<code>bin/cake build:except-parser</code> to recompile much faster if you’re not editing <code>grammar.coffee</code>.</p>
+<p><code>git checkout lib &amp;&amp; bin/cake build:full</code> is a good command to run when you’re working on the core language. It’ll refresh the <code>lib</code> folder (in case you broke something), build your altered compiler, use that to rebuild itself (a good sanity test) and then run all of the tests. If they pass, there’s a good chance you’ve made a successful change.</p>
 </li>
 <li><a href="v1/test.html">Browser Tests</a><br>
 Run CoffeeScript’s test suite in your current browser.</li>

documentation/sections/resources.md

@@ -3,10 +3,10 @@
 *   [Source Code](http://github.com/jashkenas/coffeescript/)<br>
     Use `bin/coffee` to test your changes,<br>
     `bin/cake test` to run the test suite,<br>
-    `bin/cake build` to rebuild the CoffeeScript compiler, and<br>
-    `bin/cake build:parser` to regenerate the Jison parser if you’re working on the grammar.
+    `bin/cake build` to rebuild the full CoffeeScript compiler, and<br>
+    `bin/cake build:except-parser` to recompile much faster if you’re not editing `grammar.coffee`.
 
-    `git checkout lib && bin/cake build:full` is a good command to run when you’re working on the core language. It’ll refresh the lib directory (in case you broke something), build your altered compiler, use that to rebuild itself (a good sanity test) and then run all of the tests. If they pass, there’s a good chance you’ve made a successful change.
+    `git checkout lib && bin/cake build:full` is a good command to run when you’re working on the core language. It’ll refresh the `lib` folder (in case you broke something), build your altered compiler, use that to rebuild itself (a good sanity test) and then run all of the tests. If they pass, there’s a good chance you’ve made a successful change.
 *   [Browser Tests](v<%= majorVersion %>/test.html)<br>
     Run CoffeeScript’s test suite in your current browser.
 *   [CoffeeScript Issues](http://github.com/jashkenas/coffeescript/issues)<br>