Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 269 lines (205 sloc) 9.531 kb
fca9e45 James Coglan Improved documentation. Should probably add inline documentation to Buil...
authored
1 = Jake
2
3 * http://github.com/jcoglan/jake
4
5 Jake is a command line tool for building JavaScript packages from source
6 code. Using simple YAML config files, you can specify any number of build
7 files to be generated by concatenating and minifying groups of source files.
8 It allows ERB to be used inside source files to generate code, and provides
9 event hooks into the build process so you can extend it for your own needs.
10
11
12 == Installation
13
14 sudo gem install jake
15
16
17 == Usage
18
19 To begin with, create a file called <tt>jake.yml</tt> in the root directory
20 of your project; you will run the +jake+ command from here. A basic config
21 looks like this:
22
23 ---
24 source_directory: source
25 build_directory: build
26
27 layout: together
28
29 header: COPYRIGHT
30
31 builds:
32 src:
33 packer: false
34 min:
35 shrink_vars: true
36 private: true
37
38 packages:
39 [ DESCRIBED BELOW ]
40
41 * +source_directory+ is the directory relative to <tt>jake.yml</tt> where
42 your source files are, and +build_directory+ is where all the generated
43 build files will be placed.
44 * +layout+ describes whether files from separate builds should go in
45 separate directories. For example if you have a package called +foo+,
46 with the above config the +together+ layout will generate
47 <tt>build/foo-src.js</tt> and <tt>build/foo-min.js</tt>, whereas a
48 +layout+ value of +apart+ will generate <tt>build/src/foo.js</tt> and
49 <tt>build/min/foo.js</tt>.
50 * +header+ specifies a file whose content should appear at the top of
51 all generated build files. The content of this file will typically be
52 JavaScript comments containing copyright and license information. This
53 content is never minified. The +header+ option may be omitted.
54
55
56 === Build listing
57
58 The build listing, given by the +builds+ option in the config file, lists
59 all the builds you want to produce for distribution, and what minification
60 settings that build should use. JavaScript projects typically distribute
61 both compressed and uncompressed copies of their code to suit both production
62 and development environments.
63
64 You can have as many builds as you like and the names are up to you. I'm
65 using +src+ and +min+ as readily understood examples. Each build may specify
66 some combination of the following options:
67
68 * <tt>packer: false</tt> - disables minification for this build. This
69 precludes use of further minification options.
70 * <tt>shrink_vars: true</tt> - tells the minifier to compress local
71 variable names inside functions.
72 * <tt>private: true</tt> - tells the minifier to obfuscate 'private'
73 variables with numeric replacements. JavaScript convention is that any
74 name beginning with an underscore, e.g. <tt>_foo</tt> or <tt>obj._bar</tt>
75 should be considered private. They are replaced with <tt>_0</tt>,
76 <tt>_1</tt>, etc.
77 * <tt>base62: true</tt> - produces base-62 encoded minification.
78 * <tt>suffix: false</tt> - files from this build should not have a
79 suffix if using the +together+ layout, so you get <tt>build/foo.js</tt>
80 rather than <tt>build/foo-src.js</tt>, for example. Only one build
81 may use this option, otherwise file name clashes will occur.
82
83
84 === Package listing
85
86 The package listing, given under the +packages+ config option, describes
87 the packages you want to produce and which source files are used to generate
88 them. A package is named using the path under +build_directory+ where it
89 should be generated, e.g. <tt>foo</tt> or <tt>ext/awesome</tt> (you may
90 omit the <tt>.js</tt> extension). Each package lists one or more source
91 files used to build it, and may optionally list some extra options as described
92 below.
93
94 For the examples, assume the source directory is +src+ and the build
95 directory is +dist+. This package uses a single source file <tt>src/foo.js</tt>
96 and generates <tt>dist/foo_dist.js</tt>:
97
98 foo_dist: foo
99
100 This package generates <tt>dist/bar.js</tt> from <tt>src/bar1.js</tt> and
101 <tt>src/bar2.js</tt>
102
103 bar:
104 - bar1
105 - bar2
106
107 This generates a package at <tt>dist/sub/dir.js</tt> from <tt>src/path/file.js</tt>
108 and <tt>src/path/baz.js</tt>:
109
110 sub/dir:
111 - path/file
112 - path/baz
113
114 If all the source files for a package live in the same subdirectory, you
115 can tidy things up using the +directory+ option. If you use any package-level
116 options, you must list the files under the +files+ option (the above examples
117 are just syntactic shorthands for this):
118
119 sub/dir:
120 directory: path
121 files:
122 - file
123 - baz
124
125 The full list of package options is as follows:
126
127 * +files+ - lists the source files used to build the package. Shorthand may
128 be used as above if no further options are used.
129 * +extends+ - name of another package from which to inherit configuration.
130 Useful for making a package that includes all the files from another,]
131 plus a few extras.
132 * +directory+ - the directory under +source_directory+ in which to find
133 source files. May be omitted.
134 * +header+ - a custom header file to use on this package. Overrides the
135 root +header+ option. May be omitted.
136 * +packer+ - lists minification settings that override settings being used
137 for the current build. If a build listed above uses <tt>packer: false</tt>,
138 this takes precedence over package-specific instructions. Typically used
139 to override options for the minified build.
06b1430 James Coglan Adding documentation for event hooks, inline method docs, and making a f...
authored
140 * +meta+ - should be a YAML dictionary containing arbitrary data useful to
141 user-defined build events. May be omitted. See 'Event hooks' below.
fca9e45 James Coglan Improved documentation. Should probably add inline documentation to Buil...
authored
142
143 For example, here's a package listing that uses all the options:
144
145 packages:
146 foo_dist: foo
147
148 bar:
149 - bar1
150 - bar2
151
152 sub/whizz:
153 extends: foo_dist
154 directory: path
155 header: CUSTOM_HEADER
156 files:
157 - file1
158 - file2
159
160 last:
161 packer:
162 private: false
163 files:
164 - one_file
165 - another_file
166
167 In conjunction with the build options listed above, this matches the
168 following project layout (omitting build name suffixes for brevity):
169
170 - build/
171 - sub/
172 - whizz.js
173 - bar.js
174 - foo_dist.js
175 - last.js
176 - source/
177 - path/
178 - CUSTOM_HEADER
179 - file1.js
180 - file2.js
181 - another_file.js
182 - bar1.js
183 - bar2.js
184 - foo.js
185 - one_file.js
186 - COPYRIGHT
187 - jake.yml
188
189
190 === Using ERB in source files
191
192 Jake lets you use Ruby's ERB templating system within your source code so
193 you can insert values generated from Ruby functions. To use this feature,
194 you need to create a file called <tt>Jakefile</tt> in the root of your project.
195 This contains helper functions that are called in your source code to inject data.
196
197 For example, say you want to extract a version number from your version control
198 system and inject it into your code along with the build name. Your source code
199 should contain something like this:
200
201 MyJavaScriptLib.VERSION = "<%= version %>-<%= build %>";
202
203 And your <tt>Jakefile</tt> should contain a helper called +version+:
204
205 jake_helper :version do
206 # extract version number from svn, git, whatever
207 # e.g. return '1.0'
208 end
209
210 Jake has a built-in helper called +build+ that returns the current build
211 name. When built, the output would contain the following:
212
213 MyJavaScriptLib.VERSION = "1.0-src"; // or "1.0-min" for the 'min' build
214
215
06b1430 James Coglan Adding documentation for event hooks, inline method docs, and making a f...
authored
216 === Event hooks
217
218 The +Jakefile+ may also define event hooks that are fired during a build when
219 interesting things happen. This allows you to extend your build process using
220 configuration data from Jake. We currently have two events:
221
222 +file_created+ is fired whenever a new build file is created. The callback is
223 passed the +Buildable+ package object, the current build name (+src+ or +min+
224 using the above examples), and the full path to the newly created file.
225 The package object may contain metadata (set using the +meta+ option, see
226 above) which you can use for further code generation.
227
228 +build_complete+ is fired after a build has finished running, that is after
229 all sets of minification options have been run. At this point you can use any
230 metadata you've gathered to generate more code, copy files to your distribution
231 directory, etc.
232
233 $register = {}
234
235 jake_hook :file_created do |pkg, build_name, path|
236 $register[path] = pkg.meta
237 end
238
239 jake_hook :build_complete do |build|
240 FileUtils.cp 'README', build.build_directory + '/README'
241 # generate code from $register
242 end
243
244
fca9e45 James Coglan Improved documentation. Should probably add inline documentation to Buil...
authored
245 == License
246
247 (The MIT License)
248
249 Copyright (c) 2008-2009 James Coglan
250
251 Permission is hereby granted, free of charge, to any person obtaining
252 a copy of this software and associated documentation files (the
253 'Software'), to deal in the Software without restriction, including
254 without limitation the rights to use, copy, modify, merge, publish,
255 distribute, sublicense, and/or sell copies of the Software, and to
256 permit persons to whom the Software is furnished to do so, subject to
257 the following conditions:
258
259 The above copyright notice and this permission notice shall be
260 included in all copies or substantial portions of the Software.
261
262 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
263 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
264 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
265 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
266 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
267 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
268 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.