From a28db38eef8c08c6b1816e157d32edf084052460 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Fri, 11 Apr 2014 13:33:46 -0600 Subject: [PATCH] Parse options and add docs --- package.json | 3 ++- tasks/build.js | 38 +++++++++++++++++++++++----- tasks/readme.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++ tasks/serve.js | 27 ++++++++++++++++++-- 4 files changed, 126 insertions(+), 9 deletions(-) create mode 100644 tasks/readme.md diff --git a/package.json b/package.json index 72da183f6c..73e1b6a59b 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,7 @@ "jshint": "~2.4.4", "jsdoc": "~3.3.0-alpha5", "walk": "~2.3.1", - "fs-extra": "~0.8.1" + "fs-extra": "~0.8.1", + "nomnom": "~1.6.2" } } diff --git a/tasks/build.js b/tasks/build.js index 241904a207..0c615f3f61 100644 --- a/tasks/build.js +++ b/tasks/build.js @@ -7,6 +7,7 @@ var path = require('path'); var async = require('async'); var closure = require('closure-util'); var fse = require('fs-extra'); +var nomnom = require('nomnom'); var generateExports = require('./generate-exports'); @@ -66,7 +67,7 @@ function readConfig(configPath, callback) { * or any error. */ function getDependencies(callback) { - log.info('ol', 'Parsing dependencies ...'); + log.info('ol', 'Parsing dependencies'); closure.getDependencies({lib: ['src/**/*.js']}, function(err, paths) { if (err) { callback(err); @@ -86,7 +87,7 @@ function getDependencies(callback) { * any error. */ function build(options, paths, callback) { - log.info('ol', 'Compiling ...'); + log.info('ol', 'Compiling ' + paths.length + ' sources'); options.js = paths; closure.compile(options, callback); } @@ -114,12 +115,37 @@ function main(config, callback) { * function. */ if (require.main === module) { - var configPath = process.argv[2]; - var outputPath = process.argv[3]; + var options = nomnom.options({ + config: { + position: 0, + required: true, + help: 'Path to JSON config file' + }, + output: { + position: 1, + required: true, + help: 'Output file path' + }, + loglevel: { + abbr: 'l', + choices: ['silly', 'verbose', 'info', 'warn', 'error'], + default: 'info', + help: 'Log level', + metavar: 'LEVEL' + } + }).parse(); + + /** + * Set the log level. + * @type {string} + */ + log.level = options.loglevel; + + // read the config, run the main function, and write the output file async.waterfall([ - readConfig.bind(null, configPath), + readConfig.bind(null, options.config), main, - fse.outputFile.bind(fse, outputPath) + fse.outputFile.bind(fse, options.output) ], function(err) { if (err) { log.error(err.message); diff --git a/tasks/readme.md b/tasks/readme.md new file mode 100644 index 0000000000..8417800308 --- /dev/null +++ b/tasks/readme.md @@ -0,0 +1,67 @@ +# Tasks + +This directory contains utility scripts for working with the library. + + +## `build.js` + +Builds the library based on a configuration file. See the `--help` option for more detail. + + node tasks/build.js --help + +### Build configuration files + +Build configuration files are JSON files that are used to determine what should be exported from the library and what options should be passed to the compiler. + + * **exports** - `Array.` An array of symbol names or patterns to be exported (names that are used in your application). For example, including `"ol.Map"` will export the map constructor. Method names are prefixed with `#`. So `"ol.Map#getView"` will export the map's `getView` method. You can use a `*` at the end to match multiple names. The pattern `"ol.Map#*"` will export all map methods. + + * **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`). + +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/oli.js", + "externs/geojson.js" + ], + "define": [ + "ol.ENABLE_PROJ4JS=false", + "goog.dom.ASSUME_STANDARDS_MODE=true", + "goog.DEBUG=false" + ], + "output_wrapper": "(function(){%output%})();" + } +} +``` + +To generate a build named `ol.min.js` with the `build.json`, you would run this: + + node tasks/build.js build.json ol.min.js + + +## `generate-exports.js` + +Called internally to generate a `build/exports.js` file optionally with a limited set of exports. + + +## `generate-symbols.js` + +Called internally to parse the library for API annotations and write out a `build/symbols.json` file. + + +## `parse-examples.js` + +Called after install to generate an example index. After new examples are added, run `node tasks/parse-examples.js` to regenerate the example index. + + +## `serve.js` + +Run a debug server that provides all library sources unminified. Provides a static server for examples and tests. See the `--help` option for more detail. + + node tasks/serve.js --help diff --git a/tasks/serve.js b/tasks/serve.js index 61ed865dbf..23118a5959 100644 --- a/tasks/serve.js +++ b/tasks/serve.js @@ -8,8 +8,30 @@ var path = require('path'); var url = require('url'); var closure = require('closure-util'); +var nomnom = require('nomnom'); + var log = closure.log; +var options = nomnom.options({ + port: { + abbr: 'p', + default: 3000, + help: 'Port for incoming connections', + metavar: 'PORT' + }, + loglevel: { + abbr: 'l', + choices: ['silly', 'verbose', 'info', 'warn', 'error'], + default: 'info', + help: 'Log level', + metavar: 'LEVEL' + } +}).parse(); + + +/** @type {string} */ +log.level = options.loglevel; + log.info('ol', 'Parsing dependencies ...'); var manager = new closure.Manager({ closure: true, // use the bundled Closure Library @@ -40,8 +62,9 @@ manager.on('ready', function() { return main; } }); - server.listen(3000, function() { - log.info('ol', 'Listening on http://localhost:3000/ (Ctrl+C to stop)'); + server.listen(options.port, function() { + log.info('ol', 'Listening on http://localhost:' + + options.port + '/ (Ctrl+C to stop)'); }); server.on('error', function(err) { log.error('ol', 'Server failed to start: ' + err.message);