Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 670 lines (492 sloc) 19.994 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
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
11 Prerequisites: Jake requires Node.js. (<http://nodejs.org/>)
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
12
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
13 Get Jake:
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
14
e3b394b Jake is just jake.
mde authored
15 git clone git://github.com/mde/jake.git
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
16
8b8b3f2 @mde Simplify project name to just Jake.
mde authored
17 Build Jake:
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
18
e3b394b Jake is just jake.
mde authored
19 cd jake && make && sudo make install
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
20
fc6cefd @mde Wrap text.
mde authored
21 By default Jake is installed in "/usr/local." To install it into a different
22 directory (e.g., one that doesn't require super-user privilege), pass the PREFIX
23 variable to the `make install` command. For example, to install it into a
24 "jake" directory in your home directory, you could use this:
418b95f @mde Updated README with custom-install-location info.
mde authored
25
26 make && make install PREFIX=~/jake
27
fc6cefd @mde Wrap text.
mde authored
28 If do you install Jake somewhere special, you'll need to add the "bin" directory
29 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
30
8ea6916 Call out Windows steps.
mde authored
31 ### Windows, installing from source
32
37a5c79 Updated README with better installation instructions.
mde authored
33 For Windows users installing from source, there are some additional steps.
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
34
35 *Assumed: current directory is the same directory where node.exe is present.*
36
37 Get Jake:
38
39 git clone git://github.com/mde/jake.git node_modules/jake
40
2ab2d93 @mpareja Add bash script to repository for Windows users that run bash.
mpareja authored
41 Copy jake.bat and jake to the same directory as node.exe
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
42
43 copy node_modules/jake/jake.bat jake.bat
2ab2d93 @mpareja Add bash script to repository for Windows users that run bash.
mpareja authored
44 copy node_modules/jake/jake jake
e41dff7 @prabirshrestha Instructions for installing in windows in README.md
prabirshrestha authored
45
46 Add the directory of node.exe to the environment PATH variable.
47
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
48 ### Basic usage
49
79b2ef2 Fixing args-parsing.
mde authored
50 jake [options ...] [env variables ...] target
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
51
52 ### Description
53
fc6cefd @mde Wrap text.
mde authored
54 Jake is a simple JavaScript build program with capabilities similar to the
55 regular make or rake command.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
56
57 Jake has the following features:
58 * Jakefiles are in standard JavaScript syntax
59 * Tasks with prerequisites
60 * Namespaces for tasks
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
61 * Async task execution
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
62
63 ### Options
64
53a6307 Lowercase v works for version.
mde authored
65 -V/v
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
66 --version Display the program version.
67
b1a7ff9 @mde Added better error-handling, usage instructions.
mde authored
68 -h
69 --help Display help information.
70
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
71 -f *FILE*
72 --jakefile *FILE* Use FILE as the Jakefile.
73
74 -C *DIRECTORY*
75 --directory *DIRECTORY* Change to DIRECTORY before running tasks.
76
0d25a6d Docs for jakelibdir.
mde authored
77 -J *JAKELIBDIR*
78 --jakelibdir *JAKELIBDIR* Auto-import any .jake files in JAKELIBDIR.
79 (default is 'jakelib')
80
81 -B
82 --always-make Unconditionally make all targets.
83
84 -t
85 --trace Enable full backtracke.
86
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
87 -T
88 --tasks Display the tasks, with descriptions, then exit.
89
90 ### Jakefile syntax
91
fc6cefd @mde Wrap text.
mde authored
92 A Jakefile is just executable JavaScript. You can include whatever JavaScript
93 you want in it.
932b7f0 Issue #29 Added example of file task to README.
mde authored
94
729397a Moved API docs section in README.
mde authored
95 ## API Docs
96
97 API docs [can be found here](http://mde.github.com/jake/doc/).
98
9bfe167 Derp.
mde authored
99 ## Tasks
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
100
fc6cefd @mde Wrap text.
mde authored
101 Use `task` to define tasks. Call it with two arguments (and one optional
102 argument):
cc60a89 @mde Fixing README, bumping version one more time.
mde authored
103
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
104 ```javascript
105 task(name, [prerequisites], action, [opts]);
106 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
107
fc6cefd @mde Wrap text.
mde authored
108 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
109 is an optional Array arg of the list of prerequisite tasks to perform first.
110
111 The `action` is a Function defininng the action to take for the task. (Note that
fc6cefd @mde Wrap text.
mde authored
112 Object-literal syntax for name/prerequisites in a single argument a la Rake is
113 also supported, but JavaScript's lack of support for dynamic keys in Object
0f3ac52 Document use of "this" inside of Task actions.
mde authored
114 literals makes it not very useful.) The action is invoked with the Task object
115 itself as the execution context (i.e, "this" inside the action references the
116 Task object).
cc60a89 @mde Fixing README, bumping version one more time.
mde authored
117
fc6cefd @mde Wrap text.
mde authored
118 The `opts` argument is optional, and when it includes an `async` property set to
119 `true`, indicates the task executes asynchronously. Asynchronous tasks need to
120 call `complete()` to signal they have completed. (Passing a final `async`
121 Boolean flag is deprecated, but still supported.)
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
122
fc6cefd @mde Wrap text.
mde authored
123 Tasks created with `task` are always executed when asked for (or are a
124 prerequisite). Tasks created with `file` are only executed if no file with the
125 given name exists or if any of its file-prerequisites are more recent than the
126 file named by the task. Also, if any prerequisite is a regular task, the file
127 task will always be executed.
0c8ca80 Added support for file-tasks, just like in make, rake and all of their c...
Jakob Mattsson authored
128
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
129 Use `desc` to add a string description of the task.
130
131 Here's an example:
132
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
133 ```javascript
134 desc('This is the default task.');
135 task('default', function (params) {
136 console.log('This is the default task.');
137 });
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
138
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
139 desc('This task has prerequisites.');
140 task('hasPrereqs', ['foo', 'bar', 'baz'], function (params) {
141 console.log('Ran some prereqs first.');
142 });
143 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
144
b50167d @novemberborn Updated README with information about the fork, async support.
novemberborn authored
145 And here's an example of an asynchronous task:
146
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
147 ```javascript
148 desc('This is an asynchronous task.');
149 task('asyncTask', function () {
150 setTimeout(complete, 1000);
151 }, {async: true});
152 ```
b50167d @novemberborn Updated README with information about the fork, async support.
novemberborn authored
153
39a858f @mde Document Tasks as EventEmitters.
mde authored
154 A Task is also an EventEmitter which emits the 'complete' event when it is
155 finished. This allows asynchronous tasks to be run from within other asked via
156 either `invoke` or `execute`, and ensure they will complete before the rest of
157 the containing task executes. See the section "Running tasks from within other
158 tasks," below.
159
932b7f0 Issue #29 Added example of file task to README.
mde authored
160 ### File-tasks
161
4336691 Stupid C/P error.
mde authored
162 Create a file-task by calling `file`.
932b7f0 Issue #29 Added example of file task to README.
mde authored
163
fc6cefd @mde Wrap text.
mde authored
164 File-tasks create a file from one or more other files. With a file-task, Jake
165 checks both that the file exists, and also that it is not older than the files
166 specified by any prerequisite tasks. File-tasks are particularly useful for
167 compiling something from a tree of source files.
e993d74 Added doc for directory-tasks.
mde authored
168
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
169 ```javascript
170 desc('This builds a minified JS file for production.');
171 file('foo-minified.js', ['bar', 'foo-bar.js', 'foo-baz.js'], function () {
172 // Code to concat and minify goes here
173 });
174 ```
932b7f0 Issue #29 Added example of file task to README.
mde authored
175
e993d74 Added doc for directory-tasks.
mde authored
176 ### Directory-tasks
177
4336691 Stupid C/P error.
mde authored
178 Create a directory-task by calling `directory`.
e993d74 Added doc for directory-tasks.
mde authored
179
fc6cefd @mde Wrap text.
mde authored
180 Directory-tasks create a directory for use with for file-tasks. Jake checks for
181 the existence of the directory, and only creates it if needed.
e993d74 Added doc for directory-tasks.
mde authored
182
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
183 ```javascript
184 desc('This creates the bar directory for use with the foo-minified.js file-task.');
185 directory('bar');
186 ```
e993d74 Added doc for directory-tasks.
mde authored
187
fc6cefd @mde Wrap text.
mde authored
188 This task will create the directory when used as a prerequisite for a file-task,
189 or when run from the command-line.
430937e @mde Clarify usage of DirectoryTasks.
mde authored
190
932b7f0 Issue #29 Added example of file task to README.
mde authored
191 ### Namespaces
192
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
193 Use `namespace` to create a namespace of tasks to perform. Call it with two arguments:
194
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
195 ```javascript
196 namespace(name, namespaceTasks);
197 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
198
fc6cefd @mde Wrap text.
mde authored
199 Where is `name` is the name of the namespace, and `namespaceTasks` is a function
200 with calls inside it to `task` or `desc` definining all the tasks for that
201 namespace.
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
202
203 Here's an example:
204
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
205 ```javascript
206 desc('This is the default task.');
207 task('default', function () {
208 console.log('This is the default task.');
209 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
210
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
211 namespace('foo', function () {
212 desc('This the foo:bar task');
213 task('bar', function () {
214 console.log('doing foo:bar task');
215 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
216
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
217 desc('This the foo:baz task');
218 task('baz', ['default', 'foo:bar'], function () {
219 console.log('doing foo:baz task');
220 });
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
221
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
222 });
223 ```
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
224
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
225 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
226
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
227 ### Passing parameters to jake
228
fc6cefd @mde Wrap text.
mde authored
229 Parameters can be passed to Jake two ways: plain arguments, and environment
230 variables.
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
231
fc6cefd @mde Wrap text.
mde authored
232 To pass positional arguments to the Jake tasks, enclose them in square braces,
233 separated by commas, after the name of the task on the command-line. For
234 example, with the following Jakefile:
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
235
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
236 ```javascript
237 desc('This is an awesome task.');
238 task('awesome', function (a, b, c) {
239 console.log(a, b, c);
240 });
241 ```
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
242
243 You could run `jake` like this:
244
671925f @mde Updated README to explain params-passing and env vars.
mde authored
245 jake awesome[foo,bar,baz]
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
246
247 And you'd get the following output:
248
f1ddbe3 @mde Better example of passing params using named args to the action-function...
mde authored
249 foo bar baz
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
250
671925f @mde Updated README to explain params-passing and env vars.
mde authored
251 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
252
fc6cefd @mde Wrap text.
mde authored
253 Any parameters passed after the Jake task that contain an equals sign (=) will
254 be added to process.env.
9d5301f @mde Updated README with info on passing params, fixed bug with nonexistent o...
mde authored
255
671925f @mde Updated README to explain params-passing and env vars.
mde authored
256 With the following Jakefile:
257
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
258 ```javascript
259 desc('This is an awesome task.');
260 task('awesome', function (a, b, c) {
261 console.log(a, b, c);
262 console.log(process.env.qux, process.env.frang);
263 });
264 ```
671925f @mde Updated README to explain params-passing and env vars.
mde authored
265
266 You could run `jake` like this:
267
f6a07ee @mde No longer support colon delimiter for env vars.var
mde authored
268 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
269
270 And you'd get the following output:
271
f1ddbe3 @mde Better example of passing params using named args to the action-function...
mde authored
272 foo bar baz
273 zoobie asdf
13b9829 @mde Added better options parsing and usage instructions in README.
mde authored
274 Running `jake` with no arguments runs the default task.
275
fc6cefd @mde Wrap text.
mde authored
276 __Note for zsh users__ : you will need to escape the brackets or wrap in single
277 quotes like this to pass parameters :
8d936fe @alexstrat Add few lines about passing arguments for zsh users (issue #44)
alexstrat authored
278
279 jake 'awesome[foo,bar,baz]'
fc6cefd @mde Wrap text.
mde authored
280
281 An other solution is to desactivate permannently file-globbing for the `jake`
282 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
283
284 alias jake="noglob jake"
285
38c8f44 Added docs for invoke/execute to README.
mde authored
286 ### Running tasks from within other tasks
287
fc6cefd @mde Wrap text.
mde authored
288 Jake supports the ability to run a task from within another task via the
289 `invoke` and `execute` methods.
38c8f44 Added docs for invoke/execute to README.
mde authored
290
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
291 The `invoke` method will run the desired task, along with its prerequisites:
38c8f44 Added docs for invoke/execute to README.
mde authored
292
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
293 ```javascript
294 desc('Calls the foo:bar task and its prerequisites.');
295 task('invokeFooBar', function () {
296 // Calls foo:bar and its prereqs
297 jake.Task['foo:bar'].invoke();
298 });
299 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
300
39a858f @mde Document Tasks as EventEmitters.
mde authored
301 Tasks are EventEmitters. If the inner-task invoked is asynchronous, you can set
302 a listener on the 'complete' event to run any code that depends on it.
303
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
304 ```javascript
305 desc('Calls the async foo:baz task and its prerequisites.');
306 task('invokeFooBaz', function () {
307 var t = jake.Task['foo:baz'];
308 t.addListener('complete', function () {
309 console.log('Finished executing foo:baz');
310 // Maybe run some other code
311 // ...
312 // Complete the containing task
313 complete();
314 });
315 // Kick off foo:baz
316 t.invoke();
317 }, {async: true});
318 ```
39a858f @mde Document Tasks as EventEmitters.
mde authored
319
320 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
321
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
322 ```javascript
323 desc('Calls the foo:bar task and its prerequisites.');
324 task('invokeFooBar', function () {
325 // Calls foo:bar and its prereqs
326 jake.Task['foo:bar'].invoke();
327 // Does nothing
328 jake.Task['foo:bar'].invoke();
329 });
330 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
331
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
332 The `execute` method will run the desired task without its prerequisites:
38c8f44 Added docs for invoke/execute to README.
mde authored
333
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
334 ```javascript
335 desc('Calls the foo:bar task without its prerequisites.');
336 task('executeFooBar', function () {
337 // Calls foo:bar without its prereqs
338 jake.Task['foo:baz'].execute();
339 });
340 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
341
342 Calling `execute` repeatedly will run the desired task repeatedly.
343
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
344 ```javascript
345 desc('Calls the foo:bar task without its prerequisites.');
346 task('executeFooBar', function () {
347 // Calls foo:bar without its prereqs
348 jake.Task['foo:baz'].execute();
349 // Can keep running this over and over
350 jake.Task['foo:baz'].execute();
351 jake.Task['foo:baz'].execute();
352 });
353 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
354
fc6cefd @mde Wrap text.
mde authored
355 If you want to run the task and its prerequisites more than once, you can use
356 `invoke` with the `reenable` method.
38c8f44 Added docs for invoke/execute to README.
mde authored
357
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
358 ```javascript
359 desc('Calls the foo:bar task and its prerequisites.');
360 task('invokeFooBar', function () {
361 // Calls foo:bar and its prereqs
362 jake.Task['foo:bar'].invoke();
363 // Does nothing
364 jake.Task['foo:bar'].invoke();
365 // Only re-runs foo:bar, but not its prerequisites
366 jake.Task['foo:bar'].reenable();
367 jake.Task['foo:bar'].invoke();
368 });
369 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
370
fc6cefd @mde Wrap text.
mde authored
371 The `reenable` method takes a single Boolean arg, a 'deep' flag, which reenables
372 the task's prerequisites if set to true.
38c8f44 Added docs for invoke/execute to README.
mde authored
373
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
374 ```javascript
375 desc('Calls the foo:bar task and its prerequisites.');
376 task('invokeFooBar', function () {
377 // Calls foo:bar and its prereqs
378 jake.Task['foo:bar'].invoke();
379 // Does nothing
380 jake.Task['foo:bar'].invoke();
381 // Only re-runs foo:bar, but not its prerequisites
382 jake.Task['foo:bar'].reenable(true);
383 jake.Task['foo:bar'].invoke();
384 });
385 ```
38c8f44 Added docs for invoke/execute to README.
mde authored
386
e3b65da @mde Added example of passing params via execute or invoke.
mde authored
387 It's easy to pass params on to a sub-task run via `invoke` or `execute`:
388
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
389 ```javascript
390 desc('Passes params on to other tasks.');
391 task('passParams', function () {
392 var t = jake.Task['foo:bar'];
393 // Calls foo:bar, passing along current args
394 t.invoke.apply(t, arguments);
395 });
396 ```
e3b65da @mde Added example of passing params via execute or invoke.
mde authored
397
f8c08a0 @mde Better fail.
mde authored
398 ### Aborting a task
399
fc6cefd @mde Wrap text.
mde authored
400 You can abort a task by calling the `fail` function, and Jake will abort the
401 currently running task. You can pass a customized error message to `fail`:
f8c08a0 @mde Better fail.
mde authored
402
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
403 ```javascript
404 desc('This task fails.');
405 task('failTask', function () {
406 fail('Yikes. Something back happened.');
407 });
408 ```
f8c08a0 @mde Better fail.
mde authored
409
991d461 Added docs for custom status-codes for fail.
mde authored
410 You can also pass an optional exit status-code to the fail command, like so:
411
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
412 ```javascript
413 desc('This task fails with an exit-status of 42.');
414 task('failTaskQuestionCustomStatus', function () {
415 fail('What is the answer?', 42);
416 });
417 ```
991d461 Added docs for custom status-codes for fail.
mde authored
418
419 The process will exit with a status of 42.
420
f8c08a0 @mde Better fail.
mde authored
421 Uncaught errors will also abort the currently running task.
422
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
423 ### Showing the list of tasks
424
fc6cefd @mde Wrap text.
mde authored
425 Passing `jake` the -T or --tasks flag will display the full list of tasks
426 available in a Jakefile, along with their descriptions:
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
427
428 $ jake -T
429 jake default # This is the default task.
d6d61c9 Fixes to docs, added test for older string+array syntax.
mde authored
430 jake asdf # This is the asdf task.
ae52453 @mde Updated README with example usage of -T/--tasks
mde authored
431 jake concat.txt # File task, concating two files together
432 jake failure # Failing task.
433 jake lookup # Jake task lookup by name.
434 jake foo:bar # This the foo:bar task
435 jake foo:fonebone # This the foo:fonebone task
436
437 Setting a value for -T/--tasks will filter the list by that value:
438
439 $ jake -T foo
440 jake foo:bar # This the foo:bar task
441 jake foo:fonebone # This the foo:fonebone task
442
443 The list displayed will be all tasks whose namespace/name contain the filter-string.
444
47a0edd Better docs for libjakedir.
mde authored
445 ### Breaking things up into multiple files
0d25a6d Docs for jakelibdir.
mde authored
446
47a0edd Better docs for libjakedir.
mde authored
447 Jake will automatically look for files with a .jake extension in a 'jakelib'
448 directory in your project, and load them (via `require`) after loading your
449 Jakefile. (The directory name can be overridden using the -J/--jakelibdir
450 command-line option.)
0d25a6d Docs for jakelibdir.
mde authored
451
452 This allows you to break your tasks up over multiple files -- a good way to do
47a0edd Better docs for libjakedir.
mde authored
453 it is one namespace per file: e.g., a `zardoz` namespace full of tasks in
454 'jakelib/zardox.jake'.
0d25a6d Docs for jakelibdir.
mde authored
455
456 Note that these .jake files each run in their own module-context, so they don't
457 have access to each others' data. However, the Jake API methods, and the
458 task-hierarchy are globally available, so you can use tasks in any file as
47a0edd Better docs for libjakedir.
mde authored
459 prerequisites for tasks in any other, just as if everything were in a single
460 file.
0d25a6d Docs for jakelibdir.
mde authored
461
462 Environment-variables set on the command-line are likewise also naturally
463 available to code in all files via process.env.
464
65ddbec Documenting file-utils.
mde authored
465 ### File-utils
466
467 Since shelling out in Node is an asynchronous operation, Jake comes with a few
f662726 Tweaks to file-utils doc.
mde authored
468 useful file-utilities with a synchronous API, that make scripting easier.
65ddbec Documenting file-utils.
mde authored
469
470 The `jake.mkdirP` utility recursively creates a set of nested directories. It
471 will not throw an error if any of the directories already exists. Here's an example:
472
473 ```javascript
474 jake.mkdirP('app/views/layouts');
475 ```
476
f662726 Tweaks to file-utils doc.
mde authored
477 The `jake.cpR` utility does a recursive copy of a file or directory. It takes
478 two arguments, the file/directory to copy, and the destination. Note that this
479 command can only copy files and directories; it does not perform globbing (so
480 arguments like '*.txt' are not possible).
65ddbec Documenting file-utils.
mde authored
481
482 ```javascript
483 jake.cpR(path.join(sourceDir, '/templates'), currentDir);
484 ```
485
486 This would copy 'templates' (and all its contents) into `currentDir`.
487
f662726 Tweaks to file-utils doc.
mde authored
488 The `jake.rmRf` utility recursively removes a directory and all its contents.
24eba51 Doc the jake.rmRf command.
mde authored
489
490 ```javascript
491 jake.rmRf('pkg');
492 ```
493
f662726 Tweaks to file-utils doc.
mde authored
494 This would remove the 'pkg' directory, and all its contents.
495
8ddbdaa @mde Documented jake.exec.
mde authored
496 ### Running shell-commands with `jake.exec`
497
65ddbec Documenting file-utils.
mde authored
498 Jake also provides a more general utility function for running a sequence of
499 shell-commands. The `jake.exec` command takes an array of shell-command strings,
500 and a final callback to run after completing them. Here's an example from Jake's
501 Jakefile, that runs the tests:
8ddbdaa @mde Documented jake.exec.
mde authored
502
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
503 ```javascript
504 desc('Runs the Jake tests.');
505 task('test', function () {
506 var cmds = [
507 'node ./tests/parseargs.js'
508 , 'node ./tests/task_base.js'
509 , 'node ./tests/file_task.js'
510 ];
511 jake.exec(cmds, function () {
512 console.log('All tests passed.');
513 complete();
514 }, {stdout: true});
515 }, {async: true});
516 ```
8ddbdaa @mde Documented jake.exec.
mde authored
517
518 It also takes an optional options-object, where you can set `stdout` (print to
519 stdout, default false), `stderr` (print to stderr, default false), and
520 `breakOnError` (stop execution on error, default true).
521
522 This command doesn't pipe input between commands -- it's for simple execution.
523 If you need something more sophisticated, Procstreams
524 (<https://github.com/polotek/procstreams>) might be a good option.
525
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
526 ### PackageTask
527
96250c3 Link to PackageTask docs.
mde authored
528 Instantiating a PackageTask programmically creates a set of tasks for packaging
529 up your project for distribution. Here's an example:
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
530
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
531 ```javascript
532 var t = new jake.PackageTask('fonebone', 'v0.1.2112', function () {
533 var fileList = [
534 'Jakefile'
535 , 'README.md'
536 , 'package.json'
537 , 'lib/*'
538 , 'bin/*'
539 , 'tests/*'
540 ];
541 this.packageFiles.include(fileList);
542 this.needTarGz = true;
543 this.needTarBz2 = true;
544 });
545 ```
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
546
fc6cefd @mde Wrap text.
mde authored
547 This will automatically create a 'package' task that will assemble the specified
548 files in 'pkg/fonebone-v0.1.2112,' and compress them according to the specified
549 options. After running `jake package`, you'll have the following in pkg/:
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
550
551 fonebone-v0.1.2112
552 fonebone-v0.1.2112.tar.bz2
553 fonebone-v0.1.2112.tar.gz
554
96250c3 Link to PackageTask docs.
mde authored
555 PackageTask also creates a 'clobber' task that removes the pkg/
556 directory.
557
48fb56d Changed link to PackagTask docs.
mde authored
558 The [PackageTask API
559 docs](http://mde.github.com/jake/doc/symbols/jake.PackageTask.html) include a
560 lot more information, including different archiving options.
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
561
48fb56d Changed link to PackagTask docs.
mde authored
562 PackageTask requires NodeJS's minimatch module
fc6cefd @mde Wrap text.
mde authored
563 (https://github.com/isaacs/minimatch). It is used in FileList, which is used to
564 specify the list of files to include in your PackageTask (the packageFiles
565 property). (See FileList, below.)
a6a79e2 Docs, bugfixes for PackageTask.
mde authored
566
0b35466 Bugfix and docs for FileList.
mde authored
567 ### FileList
568
fc6cefd @mde Wrap text.
mde authored
569 Jake's FileList takes a list of glob-patterns and file-names, and lazy-creates a
570 list of files to include. Instead of immediately searching the filesystem to
571 find the files, a FileList holds the pattern until it is actually used.
0b35466 Bugfix and docs for FileList.
mde authored
572
fc6cefd @mde Wrap text.
mde authored
573 When any of the normal JavaScript Array methods (or the `toArray` method) are
574 called on the FileList, the pending patterns are resolved into an actual list of
575 file-names. FileList uses NodeJS's minimatchmodule
576 (https://github.com/isaacs/minimatch).
0b35466 Bugfix and docs for FileList.
mde authored
577
578 To build the list of files, use FileList's `include` and `exclude` methods:
579
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
580 ```javascript
581 var list = new jake.FileList();
582 list.include('foo/*.txt');
583 list.include(['bar/*.txt', 'README.md']);
584 list.include('Makefile', 'package.json');
585 list.exclude('foo/zoobie.txt');
586 list.exclude(/foo\/src.*.txt/);
587 console.log(list.toArray());
588 ```
0b35466 Bugfix and docs for FileList.
mde authored
589
fc6cefd @mde Wrap text.
mde authored
590 The `include` method can be called either with an array of items, or multiple
591 single parameters. Items can be either glob-patterns, or individual file-names.
0b35466 Bugfix and docs for FileList.
mde authored
592
fc6cefd @mde Wrap text.
mde authored
593 The `exclude` method will prevent files from being included in the list. These
594 files must resolve to actual files on the filesystem. It can be called either
595 with an array of items, or mutliple single parameters. Items can be
596 glob-patterns, individual file-names, string-representations of
597 regular-expressions, or regular-expression literals.
0b35466 Bugfix and docs for FileList.
mde authored
598
cc2d44d @mde Documented NpmPublishTask
mde authored
599 ### NpmPublishTask
600
601 The NpmPublishTask builds on top of PackageTask to allow you to do a version
602 bump of your project, package it, and publish it to NPM. Define the task with
603 your project's name, and the list of files you want packaged and published to
604 NPM.
605
606 Here's an example from Jake's Jakefile:
607
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
608 ```javascript
609 var p = new jake.NpmPublishTask('jake', [
610 'Makefile'
611 , 'Jakefile'
612 , 'README.md'
613 , 'package.json'
614 , 'lib/*'
615 , 'bin/*'
616 , 'tests/*'
617 ]);
618 ```
cc2d44d @mde Documented NpmPublishTask
mde authored
619
f50a99b @mde getPackageVersionNumber doesn't need to be publicly available.
mde authored
620 The NpmPublishTask will automatically create a `publish` task which performs the
cc2d44d @mde Documented NpmPublishTask
mde authored
621 following steps:
622
623 1. Bump the version number in your package.json
624 2. Commit change in git, push it to GitHub
625 3. Create a git tag for the version
626 4. Push the tag to GitHub
627 5. Package the new version of your project
628 6. Publish it to NPM
39a858f @mde Document Tasks as EventEmitters.
mde authored
629 7. Clean up the package
cc2d44d @mde Documented NpmPublishTask
mde authored
630
3ab7761 @mde Edited wording of CoffeeScript example.
mde authored
631 ### CoffeeScript Jakefiles
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
632
fc6cefd @mde Wrap text.
mde authored
633 Jake can also handle Jakefiles in CoffeeScript. Be sure to make it
634 Jakefile.coffee so Jake knows it's in CoffeeScript.
3ab7761 @mde Edited wording of CoffeeScript example.
mde authored
635
636 Here's an example:
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
637
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
638 ```coffeescript
639 sys = require('sys')
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
640
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
641 desc 'This is the default task.'
642 task 'default', (params) ->
643 console.log 'Ths is the default task.'
644 console.log(sys.inspect(arguments))
15e780c Merge remote-tracking branch 'benatkin/fence-code-blocks'
mde authored
645 jake.Task['new'].invoke []
ffd420e @andrzejsliwa added function for calling task from body of another task.
andrzejsliwa authored
646
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
647 task 'new', ->
648 console.log 'ello from new'
15e780c Merge remote-tracking branch 'benatkin/fence-code-blocks'
mde authored
649 jake.Task['foo:next'].invoke ['param']
d0f3ee2 @andrzejsliwa added Jakefile.coffee example
andrzejsliwa authored
650
55b0f4f @benatkin fence code blocks to enable syntax highlighting
benatkin authored
651 namespace 'foo', ->
652 task 'next', (param) ->
653 console.log 'ello from next with param: ' + param
654 ```
e3407bf Removed Contributors section from README (can find it on GitHub), and ad...
mde authored
655
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
656 ### Related projects
657
b9e614a @mde Added hotlinks for URLs in README.
mde authored
658 James Coglan's "Jake": <http://github.com/jcoglan/jake>
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
659
660 Confusingly, this is a Ruby tool for building JavaScript packages from source code.
661
b9e614a @mde Added hotlinks for URLs in README.
mde authored
662 280 North's Jake: <http://github.com/280north/jake>
394bb0c @mde Added binary and Makefile, updated README with build instructions and re...
mde authored
663
664 This is also a JavaScript port of Rake, which runs on the Narwhal platform.
665
7038fac @prabirshrestha added Apache License, Version 2.0 in README.md
prabirshrestha authored
666 ### License
667
fc6cefd @mde Wrap text.
mde authored
668 Licensed under the Apache License, Version 2.0
669 (<http://www.apache.org/licenses/LICENSE-2.0>)
Something went wrong with that request. Please try again.