Updated Moving to NPM and Grunt (markdown)
Paul Spencer
+70
-14
@@ -1,21 +1,43 @@
|
||||
This is a collection of information about, and hopefully decisions for, a move away from pake/build.py to nodejs for the cli development tool chain.
|
||||
|
||||
@tschaub is the primary motivator for this work as stated by Tim near the top of [this thread](https://groups.google.com/forum/#!topic/ol3-dev/FeE5dTFgel8), in summary
|
||||
|
||||
> I'm hoping this doesn't get taken the wrong way, but my motivation for node-ifying ol3 is that I see more promise in .js based tools for managing JavaScript projects. Things like gjslint are hard dependencies now, but I want to be positioned to leverage other tools as the .py ones become outdated.
|
||||
|
||||
The following is based on the assumption that there is general agreement to move the cli development tools to NodeJS, at least where possible, and from the various discussions there hasn't been a lot of push back on moving in this direction.
|
||||
|
||||
## Approach
|
||||
|
||||
The following is based on the assumption that there is general agreement to move the cli development tools to NodeJS, at least where possible.
|
||||
|
||||
The primary tool for managing dependencies and invoking various development tasks will be `npm`, which is included with all recent NodeJS versions.
|
||||
|
||||
The actual development tasks will be run via [Grunt](gruntjs.com). Grunt requires a grunt-cli module to be installed. To avoid another dependency the user has to install, it can be installed as a direct dependency via npm and various grunt tasks can be invoked by npm via scripts. This will keep some consistency in the command line descriptions (npm install, npm test, npm build etc) and keep the prerequisites to a minimum.
|
||||
The actual development tasks will be run via [Grunt](gruntjs.com). Grunt requires a grunt-cli module to be installed. To avoid another dependency the user has to install, it can be installed as a direct dependency via npm and various grunt tasks can be invoked by npm via run-scripts. This will keep some consistency in the command line descriptions (npm install, npm test, npm build etc) and keep the prerequisites to a minimum.
|
||||
|
||||
## Installation
|
||||
### npm run-scripts
|
||||
|
||||
npm run-scripts are scripts that are listed in the `scripts` section of the `package.json` file and are invoked on the cli via `npm <script-name>`.
|
||||
|
||||
npm currently has a limitation with run-scripts discussed in npm issues [3494](https://github.com/isaacs/npm/issues/3494) and [3313](https://github.com/isaacs/npm/issues/3313) in that you cannot pass arbitrary arguments to a run-script. This is a minor inconvenience at this point and they are actively working on changes that would allow this. What this means is we cannot have a single run-script target handle multiple things so it increases documentation tasks somewhat and perhaps has a less nice feel to using it on the command line, i.e.
|
||||
|
||||
npm test
|
||||
npm integration-test
|
||||
npm watch
|
||||
|
||||
versus
|
||||
|
||||
npm test
|
||||
npm test --integration
|
||||
npm test --watch
|
||||
|
||||
Initially, then, only the most obviously useful targets will be defined for things like `build`, which will build all the permutations, to simplify the target list. These would eventually evolve to include finer grained control once npm supports flags.
|
||||
|
||||
## Using npm for installation
|
||||
|
||||
### From Source
|
||||
`git clone https://github.com/openlayers/ol3.git`
|
||||
|
||||
`cd ol3`
|
||||
|
||||
`npm install`
|
||||
`npm install` (depending on how install/check are used by other targets this may not be strictly necessary)
|
||||
|
||||
### From NPM
|
||||
|
||||
@@ -25,7 +47,7 @@ _assuming we publish an ol3 package with npm_
|
||||
|
||||
### Steps
|
||||
|
||||
Both `npm install` and `npm install ol3` will process the `package.json` dependencies (and devDependencies if the environment variable `NODE_ENV` is **not** set to `production`). The `postinstall` script can be used to run an initial build if desired, this is what Tim has currently set up in his [use-node PR](https://github.com/openlayers/ol3/pull/804).
|
||||
Both `npm install` and `npm install ol3` will process the `package.json` dependencies (and devDependencies if the environment variable `NODE_ENV` is **not** set to `production`). The `postinstall` script can be used to run an initial build if desired, this is what Tim has currently set up in his [use-node PR](https://github.com/openlayers/ol3/pull/804) - it runs `build.py build test-deps`
|
||||
|
||||
## Build Targets
|
||||
|
||||
@@ -73,9 +95,17 @@ Both `npm install` and `npm install ol3` will process the `package.json` depende
|
||||
|
||||
* postinstall - grunt install
|
||||
|
||||
* test - what Tim did!
|
||||
* test
|
||||
* what Tim did!
|
||||
* check [https://github.com/karma-runner/karma-closure/](https://github.com/karma-runner/karma-closure/)
|
||||
|
||||
* integration-test - does this make sense if the examples are no longer _built_?
|
||||
* watch
|
||||
* run tests in watch mode, automatically re-running tests on file changes
|
||||
* not sure if this detects changes in source or just the tests
|
||||
* probably should consider other uses of this, like running lint in watch mode to report errors as files are saved
|
||||
|
||||
* integration-test
|
||||
* run an integration test against the examples to ensure that exports and requires are working
|
||||
|
||||
* build - grunt build
|
||||
|
||||
@@ -85,15 +115,18 @@ Both `npm install` and `npm install ol3` will process the `package.json` depende
|
||||
|
||||
* clean - grunt clean
|
||||
|
||||
* reallyclean
|
||||
* reallyclean - grunt reallyclean
|
||||
|
||||
* todo/fixme - grunt todo
|
||||
|
||||
* serve - grunt serve
|
||||
|
||||
### Grunt Tasks
|
||||
|
||||
what grunt tasks are required (based on npm script targets) and how we can potentially satisfy them
|
||||
|
||||
* install - (custom code here) install / update dependencies
|
||||
* install - probably custom code here
|
||||
* install / update dependencies
|
||||
|
||||
* [http://dl.google.com/closure-compiler/compiler-latest.zip](http://dl.google.com/closure-compiler/compiler-latest.zip)
|
||||
|
||||
@@ -101,9 +134,14 @@ what grunt tasks are required (based on npm script targets) and how we can poten
|
||||
|
||||
* it would be nice to pick up environment variables that would use existing versions that a developer might install elsewhere and avoid downloading/installing dependencies
|
||||
* how do we make sure the dependencies are updated? Is there an automatic way to do this or is it the responsibility of the developer to periodically do something (clean perhaps?) to trigger an update
|
||||
* perhaps install always updates the dependencies to the current version (if not overridden by env variables) and the check task only installs if missing?
|
||||
|
||||
* check
|
||||
* check dependencies, not sure if this needs to be a task or not …
|
||||
* check - custom code
|
||||
* check for the existence of a dependency
|
||||
* other tasks use this to ensure dependencies are available
|
||||
* should differentiate between dependencies we can install and ones we can't
|
||||
* may possibly install missing dependencies
|
||||
* might collapse with install task
|
||||
|
||||
* todo - [https://npmjs.org/package/grunt-todos](https://npmjs.org/package/grunt-todos)
|
||||
|
||||
@@ -111,11 +149,24 @@ what grunt tasks are required (based on npm script targets) and how we can poten
|
||||
* may want to investigate how this works, the wrapper claims to embed a specific version with local modifications. In my mind, we should avoid embedded versions if possible.
|
||||
|
||||
* build - [https://npmjs.org/package/grunt-closure-compiler](https://npmjs.org/package/grunt-closure-compiler)
|
||||
|
||||
* build ol.js, ol-simple.js, ol-whitespace.js (touch ol.css)
|
||||
|
||||
* doc - [https://npmjs.org/package/grunt-jsdoc](https://npmjs.org/package/grunt-jsdoc)
|
||||
## Notes and Information
|
||||
* build documentation
|
||||
|
||||
* reallyclean - [https://npmjs.org/package/grunt-exec](https://npmjs.org/package/grunt-exec)
|
||||
* this runs a git command to remove all untracked items from the working folder
|
||||
|
||||
* serve - custom code
|
||||
* starts a local web server that serves the examples, related static files and the js files in various modes to support debugging the examples
|
||||
|
||||
## Notes and Related Information
|
||||
|
||||
### Email threads
|
||||
|
||||
[https://groups.google.com/forum/#!topic/ol3-dev/B2GUz9xvtUE](https://groups.google.com/forum/#!topic/ol3-dev/B2GUz9xvtUE) - Tim's initial Node and ol3 thread
|
||||
|
||||
[http://groups.google.com/forum/#!topic/ol3-dev/FeE5dTFgel8](http://groups.google.com/forum/#!topic/ol3-dev/FeE5dTFgel8) - Node and ol3 thread that got separated from the initial thread
|
||||
|
||||
### Related issues and PRs
|
||||
|
||||
@@ -141,4 +192,9 @@ These things will need to be downloaded:
|
||||
* [http://dl.google.com/closure-compiler/compiler-latest.zip](http://dl.google.com/closure-compiler/compiler-latest.zip)
|
||||
* [http://closure-library.googlecode.com/files/closure-library-20130212-95c19e7f0f5f.zip](http://closure-library.googlecode.com/files/closure-library-20130212-95c19e7f0f5f.zip) - **or** `git clone https://code.google.com/p/closure-library/ build/closure-library`
|
||||
|
||||
## Wiki Pages
|
||||
|
||||
[https://github.com/openlayers/ol3/wiki/Build-Tools-Specs](https://github.com/openlayers/ol3/wiki/Build-Tools-Specs)
|
||||
[https://github.com/cedricmoullet/ol3/wiki/My-HOWTO](https://github.com/cedricmoullet/ol3/wiki/My-HOWTO)
|
||||
[https://github.com/openlayers/ol3/wiki/Developer-Guide](https://github.com/openlayers/ol3/wiki/Developer-Guide)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user