Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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