Skip to content
This repository
Newer
Older
100644 112 lines (75 sloc) 5.035 kb
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
1 # Building Aria Templates
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
2
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
3 First of all, make sure you download and install [Node.js](http://nodejs.org/#download).
4 With Node.js comes [npm](http://npmjs.org/) which is AT's build orchestrator.
5
6 Our build solution is powered by [Grunt](http://gruntjs.com/). See `grunt.js` file in the main
7 folder of our repo.
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
8
9 ## Build the standard release
10
cb9d29b0 » jakub-g
2013-01-15 doc Update build info after changing commands in package.json
11 Just `cd` to the root of AT's repository and type `npm run-script grunt`.
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
12
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
13 The releases are then available in subfolders of `build/target`.
14
15 One of the sub-steps of building the release is first to build the bootstrap, which you will find in
16 `build/os-bootstrap`. This is what you may want to use as a starting point to build your own release.
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
17
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
18 The production-ready release is placed in `build/os-production`.
19
20 ## Running unit tests
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
21
cb9d29b0 » jakub-g
2013-01-15 doc Update build info after changing commands in package.json
22 Execute `npm run-script attester`. This launches our test suite using `attester`, which runs PhantomJS (headless
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
23 Webkit) under the hood to perform JavaScript tests.
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
24
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
25 See more: [https://github.com/ariatemplates/attester](attester).
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
26
cb9d29b0 » jakub-g
2013-01-15 doc Update build info after changing commands in package.json
27 ## JSHint
28
29 Execute `npm run-script lint`.
30
31 To have lint, then unit tests, then build executed all-at-once, you can use the shortcut `npm test`
32 (this is due to constraints of [Travis CI](http://about.travis-ci.org/docs/user/languages/javascript-with-nodejs/),
33 which we use for continuous integration builds, which makes only `npm install` and `npm test`
34 commands available for execution, and we didn't want to perform build for people using
35 Aria Templates via `npm install ariatemplates`).
36
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
37 ## Bump AT's version
38
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
39 AT's current version is stored in the npm's configuration file: `package.json`. To update
40 this version and generate the new release, type `npm version 1.2.3` and then `npm install`.
0aab5200 » Patrick Brosset
2012-06-12 updated build documentation
41
42 # Some background information
43
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
44 The build process of AT consists of numerous steps:
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
45
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
46 - verifying file names (to catch uppercased file extensions)
47 - validating the JavaScript syntax (using JSHint)
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
48 - minifying source files
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
49 - merging source files into packages
50 - verifying packages (each source file has to go into some package)
51 - md5-ing packages (appending MD5 hash to file names to make use of browser caching)
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
52 - adding license header comments in every built file
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
53 - normalizing skin file (adding default values etc.)
54 - running unit tests
55 - extracting the API documentation **(TBD)**
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
56
57 ## Packaging files
58
59 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...
60
61 There are 2 natures of packages:
62
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
63 - **boostrap:** the minimal package from which release packages can be created.
64 In AT, we need a certain number of files to be present in the browser, in the right order,
65 so that other files can be loaded and interpreted afterwards.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
66
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
67 - **releases:** depending on her application's need, a developer may want to package AT in a way
68 that it loads only what she needs, in an optimized way. Release builds are based on bootstrap build.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
69
70 ### Boostrap package
71
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
72 - The boostrap release config is `build/build-os-bootstrap.js`
73 - Launching the boostrap build with Grunt goes like `> grunt releaseOsBootstrap`
74 - Running Grunt will produce a `build/target/os-bootstrap` directory
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
75
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
76 The most important thing this build does is to create a bootstrap file named `ariatemplates-x.y.z.js`
77 (x.y.z being the framework version) consisting of the crucial files necessary for proper functioning
78 of the framework. This file can be then loaded on your page and you'll be able to play with the
79 framework. The other files are copied nearly untouched to the target directory, and they'll be
80 lazily loaded in the browser only at the time they're needed.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
81
82 ### Release package
83
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
84 AT build contains one standard release package used to generate the distribution for all users
85 who don't want to create their own release and are fine just using the standard one.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
86
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
87 - The production release config is `build/build-os-prod.js`
88 - Launching the production build with Grunt goes like `> grunt releaseOsProd`
89 - Running Grunt will produce a `build/target/os-production` directory
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
90
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
91 The release build introduces various additional tasks:
92 - `packager` creates logical packages (aka "multipart files") from sets of files commonly used together
93 - the output is minified using UglifyJS
94 - `atmapreader` and `atmapwriter` take care of adding URL map to the bootstrap file.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
95
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
96 **What and what for are the maps?**
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
97
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
98 AT multipart files are downloaded by AT's `DownloadMgr` thanks to a `urlMap`. Without this map,
99 AT wouldn't know in which package a specific class `a.b.C` was located.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
100
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
101 Of course, it would be completely fine for someone to load packaged files in a page using
102 `<script>` tags, as long as dependencies are in the right order. However, it is advised to use
103 the multipart (and therefore map) mechanism because this way, dependencies are resolved
104 automatically on the client side.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
105
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
106 Here, the configuration file is `build/config/urlmap.json`.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
107
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
108 **TODO**: more documentation on packaging, URL map, DownloadMgr.
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
109
640d6188 » jakub-g
2012-11-26 feat #239 build with grunt instead of packman
110 ## Extracting API doc
0801246b » Patrick Brosset
2012-06-11 Few modifications on the packman build + started documentation
111
112 *TBD*
113
Something went wrong with that request. Please try again.