Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 863 lines (639 sloc) 25.998 kb
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
1 ### Jake -- JavaScript build tool for Node.js
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
2
37a5c79 Updated README with better installation instructions.
mde authored
3 ### Installing with [NPM](http://npmjs.org/)
4
5 npm install -g jake
6
7 Note that Jake is a system-level tool, and wants to be installed globally.
8
9 ### Installing from source
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
10
70629a9 Update info about dependencies and installation.
mde authored
11 Prerequisites: Jake requires [Node.js](<http://nodejs.org/>), and the
12 [utilities](https://npmjs.org/package/utilities) and
13 [minimatch](https://npmjs.org/package/minimatch) modules.
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
14
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
15 Get Jake:
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
16
e3b394b Jake is just jake.
mde authored
17 git clone git://github.com/mde/jake.git
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
18
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
19 Build Jake:
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
20
e3b394b Jake is just jake.
mde authored
21 cd jake && make && sudo make install
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
22
70629a9 Update info about dependencies and installation.
mde authored
23 Even if you're installing Jake from source, you'll still need NPM for installing
24 the few modules Jake depends on. `make install` will do this automatically for
25 you.
26
fc6cefd @mde Wrap text.
mde authored
27 By default Jake is installed in "/usr/local." To install it into a different
28 directory (e.g., one that doesn't require super-user privilege), pass the PREFIX
29 variable to the `make install` command. For example, to install it into a
30 "jake" directory in your home directory, you could use this:
418b95f @mde Updated README with custom-install-location info.
mde authored
31
32 make && make install PREFIX=~/jake
33
fc6cefd @mde Wrap text.
mde authored
34 If do you install Jake somewhere special, you'll need to add the "bin" directory
35 in the install target to your PATH to get access to the `jake` executable.
418b95f @mde Updated README with custom-install-location info.
mde authored
36
8ea6916 Call out Windows steps.
mde authored
37 ### Windows, installing from source
38
37a5c79 Updated README with better installation instructions.
mde authored
39 For Windows users installing from source, there are some additional steps.
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
40
41 *Assumed: current directory is the same directory where node.exe is present.*
42
43 Get Jake:
44
45 git clone git://github.com/mde/jake.git node_modules/jake
46
2ab2d93 @mpareja Add bash script to repository for Windows users that run bash.
mpareja authored
47 Copy jake.bat and jake to the same directory as node.exe
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
48
49 copy node_modules/jake/jake.bat jake.bat
2ab2d93 @mpareja Add bash script to repository for Windows users that run bash.
mpareja authored
50 copy node_modules/jake/jake jake
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
51
52 Add the directory of node.exe to the environment PATH variable.
53
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
54 ### Basic usage
55
79b2ef2 Fixing args-parsing.
mde authored
56 jake [options ...] [env variables ...] target
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
57
58 ### Description
59
fc6cefd @mde Wrap text.
mde authored
60 Jake is a simple JavaScript build program with capabilities similar to the
61 regular make or rake command.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
62
63 Jake has the following features:
64 * Jakefiles are in standard JavaScript syntax
65 * Tasks with prerequisites
66 * Namespaces for tasks
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
67 * Async task execution
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
68
69 ### Options
70
53a6307 Lowercase v works for version.
mde authored
71 -V/v
7f93f2f Docs for quiet-flag
mde authored
72 --version Display the Jake version.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
73
b1a7ff9 @mde Added better error-handling, usage instructions.
mde authored
74 -h
7f93f2f Docs for quiet-flag
mde authored
75 --help Display help message.
b1a7ff9 @mde Added better error-handling, usage instructions.
mde authored
76
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
77 -f *FILE*
78 --jakefile *FILE* Use FILE as the Jakefile.
79
80 -C *DIRECTORY*
81 --directory *DIRECTORY* Change to DIRECTORY before running tasks.
82
7f93f2f Docs for quiet-flag
mde authored
83 -q
84 --quiet Do not log messages to standard output.
85
0d25a6d Docs for jakelibdir.
mde authored
86 -J *JAKELIBDIR*
87 --jakelibdir *JAKELIBDIR* Auto-import any .jake files in JAKELIBDIR.
88 (default is 'jakelib')
89
90 -B
91 --always-make Unconditionally make all targets.
92
93 -t
7f93f2f Docs for quiet-flag
mde authored
94 --trace Enable full backtrace.
0d25a6d Docs for jakelibdir.
mde authored
95
e2098b6 Added info about jake 'complete' event
mde authored
96 -T/ls
7f93f2f Docs for quiet-flag
mde authored
97 --tasks Display the tasks (matching optional PATTERN)
98 with descriptions, then exit.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
99
100 ### Jakefile syntax
101
fc6cefd @mde Wrap text.
mde authored
102 A Jakefile is just executable JavaScript. You can include whatever JavaScript
103 you want in it.
932b7f0 Issue #29 Added example of file task to README.
mde authored
104
729397a Moved API docs section in README.
mde authored
105 ## API Docs
106
107 API docs [can be found here](http://mde.github.com/jake/doc/).
108
9bfe167 Derp.
mde authored
109 ## Tasks
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
110
ad26ccf Actually only task-name is required.
mde authored
111 Use `task` to define tasks. It has one required argument, the task-name, and
112 three optional arguments:
cc60a89 @mde Fixing README, bumping version one more time.
mde authored
113
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
114 ```javascript
ad26ccf Actually only task-name is required.
mde authored
115 task(name, [prerequisites], [action], [opts]);
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
116 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
117
fc6cefd @mde Wrap text.
mde authored
118 The `name` argument is a String with the name of the task, and `prerequisites`
0f3ac52 Document use of "this" inside of Task actions.
mde authored
119 is an optional Array arg of the list of prerequisite tasks to perform first.
120
121 The `action` is a Function defininng the action to take for the task. (Note that
fc6cefd @mde Wrap text.
mde authored
122 Object-literal syntax for name/prerequisites in a single argument a la Rake is
123 also supported, but JavaScript's lack of support for dynamic keys in Object
0f3ac52 Document use of "this" inside of Task actions.
mde authored
124 literals makes it not very useful.) The action is invoked with the Task object
125 itself as the execution context (i.e, "this" inside the action references the
126 Task object).
cc60a89 @mde Fixing README, bumping version one more time.
mde authored
127
ad26ccf Actually only task-name is required.
mde authored
128 The `opts` argument is the normal JavaScript-style 'options' object. When a
129 task's operations are asynchronous, the `async` property should be set to
130 `true`, and the task must call `complete()` to signal to Jake that the task is
131 done, and execution can proceed. By default the `async` property is `false`.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
132
fc6cefd @mde Wrap text.
mde authored
133 Tasks created with `task` are always executed when asked for (or are a
134 prerequisite). Tasks created with `file` are only executed if no file with the
135 given name exists or if any of its file-prerequisites are more recent than the
136 file named by the task. Also, if any prerequisite is a regular task, the file
137 task will always be executed.
0c8ca80 Added support for file-tasks, just like in make, rake and all of their c...
Jakob Mattsson authored
138
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
139 Use `desc` to add a string description of the task.
140
141 Here's an example:
142
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
143 ```javascript
144 desc('This is the default task.');
145 task('default', function (params) {
146 console.log('This is the default task.');
147 });
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
148
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
149 desc('This task has prerequisites.');
150 task('hasPrereqs', ['foo', 'bar', 'baz'], function (params) {
151 console.log('Ran some prereqs first.');
152 });
153 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
154
b50167d @novemberborn Updated README with information about the fork, async support.
novemberborn authored
155 And here's an example of an asynchronous task:
156
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
157 ```javascript
158 desc('This is an asynchronous task.');
ad9a158 Allow opts passed before action
mde authored
159 task('asyncTask', {async: true}, function () {
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
160 setTimeout(complete, 1000);
ad9a158 Allow opts passed before action
mde authored
161 });
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
162 ```
b50167d @novemberborn Updated README with information about the fork, async support.
novemberborn authored
163
39a858f @mde Document Tasks as EventEmitters.
mde authored
164 A Task is also an EventEmitter which emits the 'complete' event when it is
165 finished. This allows asynchronous tasks to be run from within other asked via
166 either `invoke` or `execute`, and ensure they will complete before the rest of
167 the containing task executes. See the section "Running tasks from within other
168 tasks," below.
169
932b7f0 Issue #29 Added example of file task to README.
mde authored
170 ### File-tasks
171
4336691 Stupid C/P error.
mde authored
172 Create a file-task by calling `file`.
932b7f0 Issue #29 Added example of file task to README.
mde authored
173
fc6cefd @mde Wrap text.
mde authored
174 File-tasks create a file from one or more other files. With a file-task, Jake
175 checks both that the file exists, and also that it is not older than the files
176 specified by any prerequisite tasks. File-tasks are particularly useful for
177 compiling something from a tree of source files.
e993d74 Added doc for directory-tasks.
mde authored
178
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
179 ```javascript
180 desc('This builds a minified JS file for production.');
181 file('foo-minified.js', ['bar', 'foo-bar.js', 'foo-baz.js'], function () {
182 // Code to concat and minify goes here
183 });
184 ```
932b7f0 Issue #29 Added example of file task to README.
mde authored
185
e993d74 Added doc for directory-tasks.
mde authored
186 ### Directory-tasks
187
4336691 Stupid C/P error.
mde authored
188 Create a directory-task by calling `directory`.
e993d74 Added doc for directory-tasks.
mde authored
189
fc6cefd @mde Wrap text.
mde authored
190 Directory-tasks create a directory for use with for file-tasks. Jake checks for
191 the existence of the directory, and only creates it if needed.
e993d74 Added doc for directory-tasks.
mde authored
192
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
193 ```javascript
194 desc('This creates the bar directory for use with the foo-minified.js file-task.');
195 directory('bar');
196 ```
e993d74 Added doc for directory-tasks.
mde authored
197
fc6cefd @mde Wrap text.
mde authored
198 This task will create the directory when used as a prerequisite for a file-task,
199 or when run from the command-line.
430937e @mde Clarify usage of DirectoryTasks.
mde authored
200
932b7f0 Issue #29 Added example of file task to README.
mde authored
201 ### Namespaces
202
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
203 Use `namespace` to create a namespace of tasks to perform. Call it with two arguments:
204
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
205 ```javascript
206 namespace(name, namespaceTasks);
207 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
208
fc6cefd @mde Wrap text.
mde authored
209 Where is `name` is the name of the namespace, and `namespaceTasks` is a function
210 with calls inside it to `task` or `desc` definining all the tasks for that
211 namespace.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
212
213 Here's an example:
214
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
215 ```javascript
216 desc('This is the default task.');
217 task('default', function () {
218 console.log('This is the default task.');
219 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
220
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
221 namespace('foo', function () {
222 desc('This the foo:bar task');
223 task('bar', function () {
224 console.log('doing foo:bar task');
225 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
226
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
227 desc('This the foo:baz task');
228 task('baz', ['default', 'foo:bar'], function () {
229 console.log('doing foo:baz task');
230 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
231
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
232 });
233 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
234
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
235 In this example, the foo:baz task depends on the the default and foo:bar tasks.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
236
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
237 ### Passing parameters to jake
238
fc6cefd @mde Wrap text.
mde authored
239 Parameters can be passed to Jake two ways: plain arguments, and environment
240 variables.
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
241
fc6cefd @mde Wrap text.
mde authored
242 To pass positional arguments to the Jake tasks, enclose them in square braces,
243 separated by commas, after the name of the task on the command-line. For
244 example, with the following Jakefile:
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
245
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
246 ```javascript
247 desc('This is an awesome task.');
248 task('awesome', function (a, b, c) {
249 console.log(a, b, c);
250 });
251 ```
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
252
253 You could run `jake` like this:
254
671925f @mde Updated README to explain params-passing and env vars.
mde authored
255 jake awesome[foo,bar,baz]
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
256
257 And you'd get the following output:
258
f1ddbe3 @mde Better example of passing params using named args to the action-function...
mde authored
259 foo bar baz
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
260
671925f @mde Updated README to explain params-passing and env vars.
mde authored
261 Note that you *cannot* uses spaces between the commas separating the parameters.
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
262
fc6cefd @mde Wrap text.
mde authored
263 Any parameters passed after the Jake task that contain an equals sign (=) will
264 be added to process.env.
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
265
671925f @mde Updated README to explain params-passing and env vars.
mde authored
266 With the following Jakefile:
267
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
268 ```javascript
269 desc('This is an awesome task.');
270 task('awesome', function (a, b, c) {
271 console.log(a, b, c);
272 console.log(process.env.qux, process.env.frang);
273 });
274 ```
671925f @mde Updated README to explain params-passing and env vars.
mde authored
275
276 You could run `jake` like this:
277
f6a07ee @mde No longer support colon delimiter for env vars.var
mde authored
278 jake awesome[foo,bar,baz] qux=zoobie frang=asdf
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
279
280 And you'd get the following output:
281
f1ddbe3 @mde Better example of passing params using named args to the action-function...
mde authored
282 foo bar baz
283 zoobie asdf
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
284 Running `jake` with no arguments runs the default task.
285
fc6cefd @mde Wrap text.
mde authored
286 __Note for zsh users__ : you will need to escape the brackets or wrap in single
287 quotes like this to pass parameters :
8d936fe @alexstrat Add few lines about passing arguments for zsh users (issue #44)
alexstrat authored
288
289 jake 'awesome[foo,bar,baz]'
fc6cefd @mde Wrap text.
mde authored
290
291 An other solution is to desactivate permannently file-globbing for the `jake`
292 command. You can do this by adding this line to your `.zshrc` file :
8d936fe @alexstrat Add few lines about passing arguments for zsh users (issue #44)
alexstrat authored
293
294 alias jake="noglob jake"
295
e2098b6 Added info about jake 'complete' event
mde authored
296 ### Cleanup after all tasks run, jake 'complete' event
297
298 The base 'jake' object is an EventEmitter, and fires a 'complete' event after
299 running all tasks.
300
301 This is sometimes useful when a task starts a process which keeps the Node
302 event-loop running (e.g., a database connection). If you know you want to stop
303 the running Node process after all tasks have finished, you can set a listener
304 for the 'complete' event, like so:
305
306 ```javascript
307 jake.addListener('complete', function () {
308 process.exit();
309 });
310 ```
311
38c8f44 Added docs for invoke/execute to README.
mde authored
312 ### Running tasks from within other tasks
313
fc6cefd @mde Wrap text.
mde authored
314 Jake supports the ability to run a task from within another task via the
315 `invoke` and `execute` methods.
38c8f44 Added docs for invoke/execute to README.
mde authored
316
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
317 The `invoke` method will run the desired task, along with its prerequisites:
38c8f44 Added docs for invoke/execute to README.
mde authored
318
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
319 ```javascript
320 desc('Calls the foo:bar task and its prerequisites.');
321 task('invokeFooBar', function () {
322 // Calls foo:bar and its prereqs
323 jake.Task['foo:bar'].invoke();
324 });
325 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
326
39a858f @mde Document Tasks as EventEmitters.
mde authored
327 The `invoke` method will only run the task once, even if you call it repeatedly.
38c8f44 Added docs for invoke/execute to README.
mde authored
328
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
329 ```javascript
330 desc('Calls the foo:bar task and its prerequisites.');
331 task('invokeFooBar', function () {
332 // Calls foo:bar and its prereqs
333 jake.Task['foo:bar'].invoke();
334 // Does nothing
335 jake.Task['foo:bar'].invoke();
336 });
337 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
338
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
339 The `execute` method will run the desired task without its prerequisites:
38c8f44 Added docs for invoke/execute to README.
mde authored
340
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
341 ```javascript
342 desc('Calls the foo:bar task without its prerequisites.');
343 task('executeFooBar', function () {
344 // Calls foo:bar without its prereqs
345 jake.Task['foo:baz'].execute();
346 });
347 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
348
349 Calling `execute` repeatedly will run the desired task repeatedly.
350
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
351 ```javascript
352 desc('Calls the foo:bar task without its prerequisites.');
353 task('executeFooBar', function () {
354 // Calls foo:bar without its prereqs
355 jake.Task['foo:baz'].execute();
356 // Can keep running this over and over
357 jake.Task['foo:baz'].execute();
358 jake.Task['foo:baz'].execute();
359 });
360 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
361
fc6cefd @mde Wrap text.
mde authored
362 If you want to run the task and its prerequisites more than once, you can use
363 `invoke` with the `reenable` method.
38c8f44 Added docs for invoke/execute to README.
mde authored
364
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
365 ```javascript
366 desc('Calls the foo:bar task and its prerequisites.');
367 task('invokeFooBar', function () {
368 // Calls foo:bar and its prereqs
369 jake.Task['foo:bar'].invoke();
370 // Does nothing
371 jake.Task['foo:bar'].invoke();
372 // Only re-runs foo:bar, but not its prerequisites
373 jake.Task['foo:bar'].reenable();
374 jake.Task['foo:bar'].invoke();
375 });
376 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
377
fc6cefd @mde Wrap text.
mde authored
378 The `reenable` method takes a single Boolean arg, a 'deep' flag, which reenables
379 the task's prerequisites if set to true.
38c8f44 Added docs for invoke/execute to README.
mde authored
380
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
381 ```javascript
382 desc('Calls the foo:bar task and its prerequisites.');
383 task('invokeFooBar', function () {
384 // Calls foo:bar and its prereqs
385 jake.Task['foo:bar'].invoke();
386 // Does nothing
387 jake.Task['foo:bar'].invoke();
388 // Only re-runs foo:bar, but not its prerequisites
389 jake.Task['foo:bar'].reenable(true);
390 jake.Task['foo:bar'].invoke();
391 });
392 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
393
e3b65da @mde Added example of passing params via execute or invoke.
mde authored
394 It's easy to pass params on to a sub-task run via `invoke` or `execute`:
395
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
396 ```javascript
397 desc('Passes params on to other tasks.');
398 task('passParams', function () {
399 var t = jake.Task['foo:bar'];
400 // Calls foo:bar, passing along current args
401 t.invoke.apply(t, arguments);
402 });
403 ```
e3b65da @mde Added example of passing params via execute or invoke.
mde authored
404
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
405 ### Evented tasks
406
407 Tasks are EventEmitters. They can fire 'complete' and 'error' events.
408
2932a4d Fixed README wording
mde authored
409 If a task called via `invoke` is asynchronous, you can set a listener on the
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
410 'complete' event to run any code that depends on it.
411
412 ```javascript
413 desc('Calls the async foo:baz task and its prerequisites.');
ad9a158 Allow opts passed before action
mde authored
414 task('invokeFooBaz', {async: true}, function () {
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
415 var t = jake.Task['foo:baz'];
416 t.addListener('complete', function () {
417 console.log('Finished executing foo:baz');
418 // Maybe run some other code
419 // ...
420 // Complete the containing task
421 complete();
422 });
423 // Kick off foo:baz
424 t.invoke();
ad9a158 Allow opts passed before action
mde authored
425 });
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
426 ```
427
428 If you want to handle the errors in a task in some specific way, you can set a
429 listener for the 'error' event, like so:
430
431 ```javascript
432 namespace('vronk', function () {
433 task('groo', function () {
434 var t = jake.Task['vronk:zong'];
435 t.addListener('error', function (e) {
436 console.log(e.message);
437 });
438 t.invoke();
439 });
440
441 task('zong', function () {
442 throw new Error('OMFGZONG');
443 });
444 });
445 ```
446
447 If no specific listener is set for the "error" event, errors are handled by
448 Jake's generic error-handling.
449
f8c08a0 @mde Better fail.
mde authored
450 ### Aborting a task
451
fc6cefd @mde Wrap text.
mde authored
452 You can abort a task by calling the `fail` function, and Jake will abort the
453 currently running task. You can pass a customized error message to `fail`:
f8c08a0 @mde Better fail.
mde authored
454
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
455 ```javascript
456 desc('This task fails.');
457 task('failTask', function () {
458 fail('Yikes. Something back happened.');
459 });
460 ```
f8c08a0 @mde Better fail.
mde authored
461
991d461 Added docs for custom status-codes for fail.
mde authored
462 You can also pass an optional exit status-code to the fail command, like so:
463
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
464 ```javascript
465 desc('This task fails with an exit-status of 42.');
466 task('failTaskQuestionCustomStatus', function () {
467 fail('What is the answer?', 42);
468 });
469 ```
991d461 Added docs for custom status-codes for fail.
mde authored
470
471 The process will exit with a status of 42.
472
f8c08a0 @mde Better fail.
mde authored
473 Uncaught errors will also abort the currently running task.
474
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
475 ### Showing the list of tasks
476
fc6cefd @mde Wrap text.
mde authored
477 Passing `jake` the -T or --tasks flag will display the full list of tasks
478 available in a Jakefile, along with their descriptions:
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
479
480 $ jake -T
481 jake default # This is the default task.
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
482 jake asdf # This is the asdf task.
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
483 jake concat.txt # File task, concating two files together
484 jake failure # Failing task.
485 jake lookup # Jake task lookup by name.
486 jake foo:bar # This the foo:bar task
487 jake foo:fonebone # This the foo:fonebone task
488
489 Setting a value for -T/--tasks will filter the list by that value:
490
491 $ jake -T foo
492 jake foo:bar # This the foo:bar task
493 jake foo:fonebone # This the foo:fonebone task
494
495 The list displayed will be all tasks whose namespace/name contain the filter-string.
496
de4a73c Fixed heading levels in docs.
mde authored
497 ## Breaking things up into multiple files
0d25a6d Docs for jakelibdir.
mde authored
498
47a0edd Better docs for libjakedir.
mde authored
499 Jake will automatically look for files with a .jake extension in a 'jakelib'
500 directory in your project, and load them (via `require`) after loading your
501 Jakefile. (The directory name can be overridden using the -J/--jakelibdir
502 command-line option.)
0d25a6d Docs for jakelibdir.
mde authored
503
504 This allows you to break your tasks up over multiple files -- a good way to do
47a0edd Better docs for libjakedir.
mde authored
505 it is one namespace per file: e.g., a `zardoz` namespace full of tasks in
506 'jakelib/zardox.jake'.
0d25a6d Docs for jakelibdir.
mde authored
507
508 Note that these .jake files each run in their own module-context, so they don't
509 have access to each others' data. However, the Jake API methods, and the
510 task-hierarchy are globally available, so you can use tasks in any file as
47a0edd Better docs for libjakedir.
mde authored
511 prerequisites for tasks in any other, just as if everything were in a single
512 file.
0d25a6d Docs for jakelibdir.
mde authored
513
514 Environment-variables set on the command-line are likewise also naturally
515 available to code in all files via process.env.
516
de4a73c Fixed heading levels in docs.
mde authored
517 ## File-utils
65ddbec Documenting file-utils.
mde authored
518
519 Since shelling out in Node is an asynchronous operation, Jake comes with a few
f662726 Tweaks to file-utils doc.
mde authored
520 useful file-utilities with a synchronous API, that make scripting easier.
65ddbec Documenting file-utils.
mde authored
521
522 The `jake.mkdirP` utility recursively creates a set of nested directories. It
523 will not throw an error if any of the directories already exists. Here's an example:
524
525 ```javascript
526 jake.mkdirP('app/views/layouts');
527 ```
528
f662726 Tweaks to file-utils doc.
mde authored
529 The `jake.cpR` utility does a recursive copy of a file or directory. It takes
530 two arguments, the file/directory to copy, and the destination. Note that this
531 command can only copy files and directories; it does not perform globbing (so
532 arguments like '*.txt' are not possible).
65ddbec Documenting file-utils.
mde authored
533
534 ```javascript
535 jake.cpR(path.join(sourceDir, '/templates'), currentDir);
536 ```
537
538 This would copy 'templates' (and all its contents) into `currentDir`.
539
a6e1ba9 Documenting evented command-line Exec.
mde authored
540 The `jake.readdirR` utility gives you a recursive directory listing, giving you
541 output somewhat similar to the Unix `find` command. It only works with a
542 directory name, and does not perform filtering or globbing.
543
544 ```javascript
545 jake.readdirR('pkg');
546 ```
547
548 This would return an array of filepaths for all files in the 'pkg' directory,
549 and all its subdirectories.
550
f662726 Tweaks to file-utils doc.
mde authored
551 The `jake.rmRf` utility recursively removes a directory and all its contents.
24eba51 Doc the jake.rmRf command.
mde authored
552
553 ```javascript
554 jake.rmRf('pkg');
555 ```
556
f662726 Tweaks to file-utils doc.
mde authored
557 This would remove the 'pkg' directory, and all its contents.
558
de4a73c Fixed heading levels in docs.
mde authored
559 ## Running shell-commands: `jake.exec` and `jake.createExec`
8ddbdaa @mde Documented jake.exec.
mde authored
560
65ddbec Documenting file-utils.
mde authored
561 Jake also provides a more general utility function for running a sequence of
3975532 Added sub-heads
mde authored
562 shell-commands.
563
de4a73c Fixed heading levels in docs.
mde authored
564 ### `jake.exec`
3975532 Added sub-heads
mde authored
565
00f1144 A few more doc fixes
mde authored
566 The `jake.exec` command takes an array of shell-command strings, and an optional
3975532 Added sub-heads
mde authored
567 callback to run after completing them. Here's an example from Jake's Jakefile,
568 that runs the tests:
8ddbdaa @mde Documented jake.exec.
mde authored
569
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
570 ```javascript
571 desc('Runs the Jake tests.');
ad9a158 Allow opts passed before action
mde authored
572 task('test', {async: true}, function () {
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
573 var cmds = [
574 'node ./tests/parseargs.js'
575 , 'node ./tests/task_base.js'
576 , 'node ./tests/file_task.js'
577 ];
578 jake.exec(cmds, function () {
579 console.log('All tests passed.');
580 complete();
00f1144 A few more doc fixes
mde authored
581 }, {printStdout: true});
ad9a158 Allow opts passed before action
mde authored
582 });
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
583 ```
8ddbdaa @mde Documented jake.exec.
mde authored
584
a6e1ba9 Documenting evented command-line Exec.
mde authored
585 It also takes an optional options-object, with the following options:
586
587 * `printStdout` (print to stdout, default false)
588
589 * `printStderr` (print to stderr, default false)
590
591 * `breakOnError` (stop execution on error, default true)
8ddbdaa @mde Documented jake.exec.
mde authored
592
593 This command doesn't pipe input between commands -- it's for simple execution.
a6e1ba9 Documenting evented command-line Exec.
mde authored
594
de4a73c Fixed heading levels in docs.
mde authored
595 ### `jake.createExec` and the evented Exec object
3975532 Added sub-heads
mde authored
596
4786b9e A few doc tweaks.
mde authored
597 Jake also provides an evented interface for running shell commands. Calling
a6e1ba9 Documenting evented command-line Exec.
mde authored
598 `jake.createExec` returns an instance of `jake.Exec`, which is an `EventEmitter`
599 that fires events as it executes commands.
600
601 It emits the following events:
602
603 * 'cmdStart': When a new command begins to run. Passes one arg, the command
604 being run.
605
606 * 'cmdEnd': When a command finishes. Passes one arg, the command
607 being run.
608
609 * 'stdout': When the stdout for the child-process recieves data. This streams
610 the stdout data. Passes one arg, the chunk of data.
611
9b39254 Fixed typo in README.md
John Setzer authored
612 * 'stderr': When the stderr for the child-process recieves data. This streams
613 the stderr data. Passes one arg, the chunk of data.
a6e1ba9 Documenting evented command-line Exec.
mde authored
614
615 * 'error': When a shell-command exits with a non-zero status-code. Passes two
616 args -- the error message, and the status code. If you do not set an error
617 handler, and a command exits with an error-code, Jake will throw the unhandled
618 error. If `breakOnError` is set to true, the Exec object will emit and 'error'
619 event after the first error, and stop any further execution.
620
621 To begin running the commands, you have to call the `run` method on it. It also
622 has an `append` method for adding new commands to the list of commands to run.
623
624 Here's an example:
625
626 ```javascript
00f1144 A few more doc fixes
mde authored
627 var ex = jake.createExec(['do_thing.sh'], {printStdout: true});
a6e1ba9 Documenting evented command-line Exec.
mde authored
628 ex.addListener('error', function (msg, code) {
629 if (code == 127) {
630 console.log("Couldn't find do_thing script, trying do_other_thing");
631 ex.append('do_other_thing.sh');
632 }
633 else {
4786b9e A few doc tweaks.
mde authored
634 fail('Fatal error: ' + msg, code);
a6e1ba9 Documenting evented command-line Exec.
mde authored
635 }
636 });
637 ex.run();
638 ```
639
640 Using the evented Exec object gives you a lot more flexibility in running shell
641 commmands. But if you need something more sophisticated, Procstreams
8ddbdaa @mde Documented jake.exec.
mde authored
642 (<https://github.com/polotek/procstreams>) might be a good option.
643
7f93f2f Docs for quiet-flag
mde authored
644 ## Logging and output
645
646 Using the -q/--quiet flag at the command-line will stop Jake from sending its
647 normal output to standard output. Note that this only applies to built-in output
648 from Jake; anything you output normally from your tasks will still be displayed.
649
650 If you want to take advantage of the -q/--quiet flag in your own programs, you
651 can use `jake.logger.log` and `jake.logger.error` for displaying output. These
652 two commands will respect the flag, and suppress output correctly when the
653 quiet-flag is on.
654
655 You can check the current value of this flag in your own tasks by using
656 `jake.program.opts.quiet`. If you want the output of a `jake.exec` shell-command
657 to respect the quiet-flag, set your `printStdout` and `printStderr` options to
658 false if the quiet-option is on:
659
660 ```javascript
ad9a158 Allow opts passed before action
mde authored
661 task('echo', {async: true}, function () {
7f93f2f Docs for quiet-flag
mde authored
662 jake.exec(['echo "hello"'], function () {
663 jake.logger.log('Done.');
664 complete();
665 }, {printStdout: !jake.program.opts.quiet});
ad9a158 Allow opts passed before action
mde authored
666 });
7f93f2f Docs for quiet-flag
mde authored
667 ```
668
de4a73c Fixed heading levels in docs.
mde authored
669 ## PackageTask
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
670
96250c3 Link to PackageTask docs.
mde authored
671 Instantiating a PackageTask programmically creates a set of tasks for packaging
672 up your project for distribution. Here's an example:
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
673
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
674 ```javascript
675 var t = new jake.PackageTask('fonebone', 'v0.1.2112', function () {
676 var fileList = [
677 'Jakefile'
678 , 'README.md'
679 , 'package.json'
680 , 'lib/*'
681 , 'bin/*'
682 , 'tests/*'
683 ];
684 this.packageFiles.include(fileList);
685 this.needTarGz = true;
686 this.needTarBz2 = true;
687 });
688 ```
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
689
fc6cefd @mde Wrap text.
mde authored
690 This will automatically create a 'package' task that will assemble the specified
691 files in 'pkg/fonebone-v0.1.2112,' and compress them according to the specified
692 options. After running `jake package`, you'll have the following in pkg/:
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
693
694 fonebone-v0.1.2112
695 fonebone-v0.1.2112.tar.bz2
696 fonebone-v0.1.2112.tar.gz
697
96250c3 Link to PackageTask docs.
mde authored
698 PackageTask also creates a 'clobber' task that removes the pkg/
699 directory.
700
48fb56d Changed link to PackagTask docs.
mde authored
701 The [PackageTask API
702 docs](http://mde.github.com/jake/doc/symbols/jake.PackageTask.html) include a
703 lot more information, including different archiving options.
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
704
01f6234 update readme
mde authored
705 ### FileList
0b35466 Bugfix and docs for FileList.
mde authored
706
fc6cefd @mde Wrap text.
mde authored
707 Jake's FileList takes a list of glob-patterns and file-names, and lazy-creates a
708 list of files to include. Instead of immediately searching the filesystem to
709 find the files, a FileList holds the pattern until it is actually used.
0b35466 Bugfix and docs for FileList.
mde authored
710
fc6cefd @mde Wrap text.
mde authored
711 When any of the normal JavaScript Array methods (or the `toArray` method) are
712 called on the FileList, the pending patterns are resolved into an actual list of
01f6234 update readme
mde authored
713 file-names. FileList uses the [minimatch](https://github.com/isaacs/minimatch) module.
0b35466 Bugfix and docs for FileList.
mde authored
714
715 To build the list of files, use FileList's `include` and `exclude` methods:
716
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
717 ```javascript
718 var list = new jake.FileList();
719 list.include('foo/*.txt');
720 list.include(['bar/*.txt', 'README.md']);
721 list.include('Makefile', 'package.json');
722 list.exclude('foo/zoobie.txt');
723 list.exclude(/foo\/src.*.txt/);
724 console.log(list.toArray());
725 ```
0b35466 Bugfix and docs for FileList.
mde authored
726
fc6cefd @mde Wrap text.
mde authored
727 The `include` method can be called either with an array of items, or multiple
728 single parameters. Items can be either glob-patterns, or individual file-names.
0b35466 Bugfix and docs for FileList.
mde authored
729
fc6cefd @mde Wrap text.
mde authored
730 The `exclude` method will prevent files from being included in the list. These
731 files must resolve to actual files on the filesystem. It can be called either
732 with an array of items, or mutliple single parameters. Items can be
733 glob-patterns, individual file-names, string-representations of
734 regular-expressions, or regular-expression literals.
0b35466 Bugfix and docs for FileList.
mde authored
735
822dd29 Documented TestTask.
mde authored
736 ## TestTask
737
738 Instantiating a TestTask programmically creates a simple task for running tests
739 for your project. The first argument of the constructor is the project-name
740 (used in the description of the task), and the second argument is a function
741 that defines the task. It allows you to specifify what files to run as tests,
742 and what to name the task that gets created (defaults to "test" if unset).
743
744 ```javascript
745 var t = new jake.TestTask('fonebone', function () {
746 var fileList = [
747 'tests/*'
748 , 'lib/adapters/**/test.js'
749 ];
750 this.testFiles.include(fileList);
cbbaf59 Converted tests to TestTask.
mde authored
751 this.testFiles.exclude('tests/helper.js');
822dd29 Documented TestTask.
mde authored
752 this.testName = 'testMainAndAdapters';
753 });
754 ```
755
756 Tests in the specified file should be in the very simple format of
757 test-functions hung off the export. These tests are converted into Jake tasks
758 which Jake then runs normally.
759
760 If a test needs to run asynchronously, simply define the test-function with a
761 single argument, a callback. Jake will define this as an asynchronous task, and
762 will wait until the callback is called in the test function to run the next test.
763
764 Here's an example test-file:
765
766 ```javascript
767 var assert = require('assert')
768 , tests;
769
770 tests = {
771 'sync test': function () {
772 // Assert something
773 assert.ok(true);
774 }
775 , 'async test': function (next) {
776 // Assert something else
777 assert.ok(true);
778 // Won't go next until this is called
779 next();
780 }
781 , 'another sync test': function () {
782 // Assert something else
783 assert.ok(true);
784 }
785 };
786
787 module.exports = tests;
788 ```
789
cbbaf59 Converted tests to TestTask.
mde authored
790 Jake's tests are also a good example of use of a TestTask.
791
de4a73c Fixed heading levels in docs.
mde authored
792 ## NpmPublishTask
cc2d44d @mde Documented NpmPublishTask
mde authored
793
794 The NpmPublishTask builds on top of PackageTask to allow you to do a version
795 bump of your project, package it, and publish it to NPM. Define the task with
796 your project's name, and the list of files you want packaged and published to
797 NPM.
798
799 Here's an example from Jake's Jakefile:
800
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
801 ```javascript
802 var p = new jake.NpmPublishTask('jake', [
803 'Makefile'
804 , 'Jakefile'
805 , 'README.md'
806 , 'package.json'
807 , 'lib/*'
808 , 'bin/*'
809 , 'tests/*'
810 ]);
811 ```
cc2d44d @mde Documented NpmPublishTask
mde authored
812
f50a99b @mde getPackageVersionNumber doesn't need to be publicly available.
mde authored
813 The NpmPublishTask will automatically create a `publish` task which performs the
cc2d44d @mde Documented NpmPublishTask
mde authored
814 following steps:
815
816 1. Bump the version number in your package.json
817 2. Commit change in git, push it to GitHub
818 3. Create a git tag for the version
819 4. Push the tag to GitHub
820 5. Package the new version of your project
821 6. Publish it to NPM
39a858f @mde Document Tasks as EventEmitters.
mde authored
822 7. Clean up the package
cc2d44d @mde Documented NpmPublishTask
mde authored
823
de4a73c Fixed heading levels in docs.
mde authored
824 ## CoffeeScript Jakefiles
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
825
fc6cefd @mde Wrap text.
mde authored
826 Jake can also handle Jakefiles in CoffeeScript. Be sure to make it
827 Jakefile.coffee so Jake knows it's in CoffeeScript.
3ab7761 @mde Edited wording of CoffeeScript example.
mde authored
828
829 Here's an example:
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
830
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
831 ```coffeescript
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
832 util = require('util')
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
833
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
834 desc 'This is the default task.'
835 task 'default', (params) ->
836 console.log 'Ths is the default task.'
ffa4698 Updated README with task "error" event, a few other small tweaks
mde authored
837 console.log(util.inspect(arguments))
15e780c Merge remote-tracking branch 'benatkin/fence-code-blocks'
mde authored
838 jake.Task['new'].invoke []
ffd420e @andrzejsliwa added function for calling task from body of another task.
andrzejsliwa authored
839
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
840 task 'new', ->
841 console.log 'ello from new'
15e780c Merge remote-tracking branch 'benatkin/fence-code-blocks'
mde authored
842 jake.Task['foo:next'].invoke ['param']
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
843
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
844 namespace 'foo', ->
845 task 'next', (param) ->
846 console.log 'ello from next with param: ' + param
847 ```
e3407bf Removed Contributors section from README (can find it on GitHub), and ad...
mde authored
848
de4a73c Fixed heading levels in docs.
mde authored
849 ## Related projects
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
850
b9e614a @mde Added hotlinks for URLs in README.
mde authored
851 James Coglan's "Jake": <http://github.com/jcoglan/jake>
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
852
853 Confusingly, this is a Ruby tool for building JavaScript packages from source code.
854
b9e614a @mde Added hotlinks for URLs in README.
mde authored
855 280 North's Jake: <http://github.com/280north/jake>
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
856
857 This is also a JavaScript port of Rake, which runs on the Narwhal platform.
858
7038fac @prabirshrestha added Apache License, Version 2.0 in README.md
prabirshrestha authored
859 ### License
860
fc6cefd @mde Wrap text.
mde authored
861 Licensed under the Apache License, Version 2.0
862 (<http://www.apache.org/licenses/LICENSE-2.0>)
Something went wrong with that request. Please try again.