Building Aria Templates
Our build solution is powered by Grunt. See
grunt.js file in the main
folder of our repo.
Build the standard release
cd to the root of AT's repository and type
npm run-script grunt.
The releases are then available in subfolders of
One of the sub-steps of building the release is first to build the bootstrap, which you will find in
build/os-bootstrap. This is what you may want to use as a starting point to build your own release.
The production-ready release is placed in
Running unit tests
npm run-script attester. This launches our test suite using
attester, which runs PhantomJS (headless
See more: https://github.com/ariatemplates/attester.
npm run-script lint.
To have lint, then unit tests, then build executed all-at-once, you can use the shortcut
(this is due to constraints of Travis CI,
which we use for continuous integration builds, which makes only
npm install and
commands available for execution, and we didn't want to perform build for people using
Aria Templates via
npm install ariatemplates).
Bump AT's version
AT's current version is stored in the npm's configuration file:
package.json. To update
this version and generate the new release, type
npm version 1.2.3 and then
Some background information
The build process of AT consists of numerous steps:
- verifying file names (to catch uppercased file extensions)
- minifying source files
- merging source files into packages
- verifying packages (each source file has to go into some package)
- md5-ing packages (appending MD5 hash to file names to make use of browser caching)
- adding license header comments in every built file
- normalizing skin file (adding default values etc.)
- running unit tests
- extracting the API documentation (TBD)
Packaging files mainly means merging them together according to some configuration, but also processing them in any required way, including: minifying them, "compiling" them, adding license headers...
There are 2 natures of packages:
boostrap: the minimal package from which release packages can be created. In AT, we need a certain number of files to be present in the browser, in the right order, so that other files can be loaded and interpreted afterwards.
releases: depending on her application's need, a developer may want to package AT in a way that it loads only what she needs, in an optimized way. Release builds are based on bootstrap build.
- The boostrap release config is
- Launching the boostrap build with Grunt goes like
> grunt releaseOsBootstrap
- Running Grunt will produce a
The most important thing this build does is to create a bootstrap file named
(x.y.z being the framework version) consisting of the crucial files necessary for proper functioning
of the framework. This file can be then loaded on your page and you'll be able to play with the
framework. The other files are copied nearly untouched to the target directory, and they'll be
lazily loaded in the browser only at the time they're needed.
AT build contains one standard release package used to generate the distribution for all users who don't want to create their own release and are fine just using the standard one.
- The production release config is
- Launching the production build with Grunt goes like
> grunt releaseOsProd
- Running Grunt will produce a
The release build introduces various additional tasks:
packagercreates logical packages (aka "multipart files") from sets of files commonly used together
- the output is minified using UglifyJS
atmapwritertake care of adding URL map to the bootstrap file.
What and what for are the maps?
AT multipart files are downloaded by AT's
DownloadMgr thanks to a
urlMap. Without this map,
AT wouldn't know in which package a specific class
a.b.C was located.
Of course, it would be completely fine for someone to load packaged files in a page using
<script> tags, as long as dependencies are in the right order. However, it is advised to use
the multipart (and therefore map) mechanism because this way, dependencies are resolved
automatically on the client side.
Here, the configuration file is
TODO: more documentation on packaging, URL map, DownloadMgr.
Extracting API doc