This readme file describes the Breakout build process. If you are changing any
of the Breakout source code (in
Breakout/src/) and/or making a contribution to
Breakout you will need to follow this process.
Installing the build tools (dev)
Breakout uses grunt to run the build tasks. The following instructions will get you set up with Node.js (which is a requrement to run grunt) and grunt so you can build Breakout.
Install grunt-cli globally (may require
$ npm install -g grunt-cli
Navigate to the
Breakoutdirectory execute the following command to install the required Node modules. This will install everything you need to build Breakout.
$ npm install
Windows users, see the 'Does Grunt work on Windows?' FAQ here to get setup.
Building a new release
If you are contributing to Breakout and have changed any of the source files (excluding example files) you must run the full build process before submitting a pull request. Executing the following command will run the full build.
This process executes the following steps in order:
- Check each file for lint
- Concatenate files
- Minify (uglify) files
- Run unit tests
- Generate docs
If any step fails, the build process will exit. Correct any errors in the source
code and run
It can take a while to build a full release so if you just want to run one or
two of the build steps refer to the grunt commands in the following sections for
each of the build steps. For example, while you are working on a new feature it
may be convenient to just run
grunt compile (which only takes a few seconds)
after making changes to the code rather than running the full build.
$ grunt jshint $ grunt jscs
Concatenate and minify
If you make changes to any files in the Breakout src directory, you will need
to concatenate and minify (uglify) the src files. Run the
compile command to
concatenate and minify the files.
$ grunt compile
If you would only like to concatenate (and not minify) or vice versa, use one of the following two commands:
$ grunt concat
$ grunt uglify
Unit tests are written with mocha, chai for expect and sinon for spies and stubs. phantomJS is used to run the tests headlessly. phantomJS is installed when you run
npm install so there is no need to install it separately. If you already have phantomJS
installed, there will not be a conflict.
The following command will run jshint and jscs and then the unit tests via phantomjs:
$ grunt test
Use the following command to run the unit tests without first running jshint:
$ grunt mocha_phantomjs
See the README file in
Breakout/test/ for more info on running the tests. If
files are excluded) be sure to add unit tests for any new functionality. Refer to
the existing tests and fixtures in
Breakout/test/core/as a guilde.
Updating the documentation
The documentation uses yuidoc. Be sure to use the yui doc syntax when documenting any added code. If you need to generate the docs outside of the full build process, run the following command:
$ grunt docs
Breakout is distributed under the terms of the MIT License.