Accept a src config, add docs

tasks/build.js

@@ -30,6 +30,10 @@ function assertValidConfig(config, callback) {
       callback(new Error('Config missing "compile" object'));
       return;
     }
+    if (config.src && !Array.isArray(config.src)) {
+      callback(new Error('Config "src" must be an array'));
+      return;
+    }
     callback(null);
   });
 }
@@ -63,12 +67,15 @@ function readConfig(configPath, callback) {
 
 /**
  * Get the list of sources sorted in dependency order.
+ * @param {Array.<string>} src List of paths or patterns to source files.  By
+ *     default, all .js files in the src directory are included.
  * @param {function(Error, Array.<string>)} callback Called with a list of paths
  *     or any error.
  */
-function getDependencies(callback) {
+function getDependencies(src, callback) {
   log.info('ol', 'Parsing dependencies');
-  closure.getDependencies({lib: ['src/**/*.js']}, function(err, paths) {
+  src = src || ['src/**/*.js'];
+  closure.getDependencies({lib: src}, function(err, paths) {
     if (err) {
       callback(err);
       return;
@@ -88,7 +95,7 @@ function getDependencies(callback) {
  */
 function build(options, paths, callback) {
   log.info('ol', 'Compiling ' + paths.length + ' sources');
-  options.js = paths;
+  options.js = paths.concat(options.js || []);
   closure.compile(options, callback);
 }
 
@@ -104,7 +111,7 @@ function main(config, callback) {
   async.waterfall([
     assertValidConfig.bind(null, config),
     generateExports.bind(null, config.exports),
-    getDependencies,
+    getDependencies.bind(null, config.src),
     build.bind(null, config.compile)
   ], callback);
 }

tasks/readme.md

@@ -17,25 +17,35 @@ Build configuration files are JSON files that are used to determine what should
 
  * **compile** - `Object` An object whose properties are [Closure Compiler options](https://github.com/openlayers/closure-util/blob/master/compiler-options.txt).  Property names match the option names without the `--` prefix (e.g. `"compilation_level": "ADVANCED_OPTIMIZATIONS"` would set the `--compilation_level` option).  Where an option can be specified multiple times, use an array for the value (e.g. `"externs": ["one.js", "two.js"]`).  Where an option is used as a flag, use a boolean value (e.g. `"use_types_for_optimization": true`).
 
+ * **src** - `Array.<string>` Optional array of [path patterns](https://github.com/isaacs/minimatch/blob/master/README.md) for source files.  This defaults to `["src/**/*.js"]` which will match all `.js` files in the `src` directory.  To include a different set of source files, provide an array of path patterns.  Note that these patterns are `/` delimited even on Windows.
+
+The build task generates a list of source files sorted in dependency order and passes these to the compiler.  This takes the place of the `--js` options that you would use when calling the compiler directly.  If you want to add additional source files, typically you would use the `src` array described above.  This works with sources that have `goog.require` and/or `goog.provide` calls (which are used to sort dependencies).  If you want to force the inclusion of files that don't use `goog.require` or `goog.provide`, you can use the `js` property of the `compile` object.  Paths in the `js` array will be passed to the compiler **after** all other source files.
+
+Paths in your config file should be relative to the current working directory (when you call `node tasks/build.js`).  Note that this means paths are not necessarily relative to the config file itself.
+
 Below is a complete `build.json` configuration file that would generate a build including every symbol in the library (much more than you'd ever need).
 
 ```json
 {
   "exports": ["*"],
   "compile": {
-    "compilation_level": "ADVANCED_OPTIMIZATIONS",
-    "use_types_for_optimization": true,
     "externs": [
-      "externs/olx.js",
+      "externs/bingmaps.js",
+      "externs/geojson.js",
       "externs/oli.js",
-      "externs/geojson.js"
+      "externs/olx.js",
+      "externs/proj4js.js",
+      "externs/tilejson.js",
+      "externs/topojson.js",
+      "externs/vbarray.js"
     ],
     "define": [
-      "ol.ENABLE_PROJ4JS=false",
       "goog.dom.ASSUME_STANDARDS_MODE=true",
       "goog.DEBUG=false"
     ],
-    "output_wrapper": "(function(){%output%})();"
+    "compilation_level": "ADVANCED_OPTIMIZATIONS",
+    "output_wrapper": "(function(){%output%})();",
+    "use_types_for_optimization": true
   }
 }
 ```