Build Tool Setup

Work in progress

This page is a work in progress and requires review. Please file an issue if information or coding is missing, incorrect or out of sync with the main repository (ramp-pcar/ramp-pcar).

Dependencies

If you haven’t used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

To install Grunt on Windows, you first need to install Node.js and Git binary, and then you can use the command prompt or PowerShell to run Grunt tasks. You also need to have Java installed.

After installing the dependencies, run the following in your command shell as Administrator

$ npm install -g grunt-cli
$ npm install -g bower

This will add the grunt and bower commands to your system path, allowing it to be run from any directory. You might want to restart your machine, just in case.

Getting Started

To run the build tool do the following:

  1. Open Command Prompt or PowerShell
  2. Change to the project’s root directory
  3. Use npm install to install project dependencies (need to run only once or when adding new modules)
  4. Use the following to run the default build task:
$ grunt

if you get an error that something is not found, try running npm install again.

Default Task

Unless you specify a task to run, grunt command creates an unminified development, minified and tarballed distribution packages. They are located in build, dist, and tarball folders respectivelly.

Other Tasks

api

Generate API documentation using YUIDoc and annotated source code documents using Docco and save them in “docs/docco” and “docs/yuidoc” folder. Use the following to run this task:

$ grunt api

build

Creates an unminified development package. Use the following to run this task:

$ grunt build

clean

Removes all temporary and build folders:

  • ./build/
  • ./dist/
  • ./tarball

Use the following to run this task:

$ grunt cleanAll

deploy

Creates a minified distribution package and copies it into to a specified location. This task will fail if there are any JS errors present. Use the following to run this task:

$ grunt deploy

Note: The target folder is cleaned prior to copying files.

dist

Identical to the default task. Use the following to run this task:

$ grunt dist

serve:build

Creates an unminified development package, starts a node server on port 3002, watches for modified JS, CSS and other files, and reloads HTML page on change.

Use the following to run this task:

$ grunt serve:build

Access RAMP pages: http://localhost:3002/ramp-en.html http://localhost:3002/ramp-fr.html

serve:dist

Creates a minified distribution package and starts a node server on port 3002.

Use the following to run this task:

$ grunt serve:dist

Access RAMP pages: http://localhost:3002/ramp-en.html http://localhost:3002/ramp-fr.html

Note: This task does not monitor files and will not rebuild the package or reload the pages.

Config File - package.json

package.json contains the metadata about the build tool project, grunt dependencies to be installed and some of the variables used by the build tool such as various paths, folders, and file names. package.json is a pure JSON file (no comments, no unquoted strings, no multiline values allowed). All the variables related to the build tool stored in ramp object.

ramp.concat.jsLib

A list of JS libraries’ files to be concatenated together for use in RAMP.

ramp.concat.cssLib

A list of CSS libraries’ files to be concatenated together for use in RAMP.

ramp.deployToFolder

A path to the deploy folder.

ramp.docco.path

A path to the JavaScript folder to be parsed.

ramp.docco.outdir

A path where to put generated documents.

yuidocconfig

The Config object for YUIDoc is located in yuidoc.json file. You can read about its structure here: http://yui.github.io/yuidoc/args/index.html

Grunt Modules

The build tool uses a number of Grunt-specific and general NPM modules. They are:

Other

Making your Grunt Snarl

To see sweet notification balloons when your Grunt wants to tell you that your task has failed (or when JS has been JShinted successfully, or when LESS has been converted to proper CSS), install Snarl from here: http://sourceforge.net/projects/snarlwin/files/latest/download?source=files

You don’t need to do anything else.

Adding JavaScript Library

To add a JavaScript library, do the following:

  1. create a folder in RAMP/src/js/lib/{library name}.{ library version}, and copy the library files into this folder;
  2. add the main uglified library file name(s) to the jsLibToConcat property in package.json file making sure the path is relative to the jsFolder property; if the library doesn’t have an uglified version, do step 3 even if you didn’t modify the library’s source;
  3. if you made changes to the library’s source file(s), add their names to the jsLibToUglify property of the package.json file; the build tool will create an uglified version with *.min.js extension;
  4. include the reference to the library’s source file(s) if you modified them and to main uglified file(s) if you didn’t in ramp-src.html between the comment tags:
  5. run the tool;

Adding CSS Library

To add a CSS library, do the following:

  1. create a folder in RAMP/src/css/lib/{library name}.{ library version}, and copy the library files into this folder;
  2. add the main minified library file name(s) to the cssLibToConcat property in package.json file making sure the path is relative to the cssFolder property; if the library doesn’t have an minified version, do step 3 even if you didn’t modify the library’s source;
  3. if you made changes to the library’s source file(s), add their names to the cssLibToMinify property of the package.json file; the build tool will create an minified version with *.min.css extension;
  4. include the reference to the library’s source file(s) if you modified them and to main minified file(s) if you didn’t in ramp-src.html between the comment tags:
  5. run the tool;

Troubleshooting

Task Not Found

If you get a “Task not found” error like this one:

Warning: Task "***" not found.  Use --force to continue.
Aborted due to warnings.

Run the npm install command again (you may want to delete the node_modules folder from the root, if it didn’t work after the first try, just in case):

Date modified: