Installing from source

By default Jake is installed in "/usr/local." To install it into a different
directory (e.g., one that doesn't require super-user privilege), pass the PREFIX
variable to the make install command. For example, to install it into a
"jake" directory in your home directory, you could use this:

make && make install PREFIX=~/jake

If do you install Jake somewhere special, you'll need to add the "bin" directory
in the install target to your PATH to get access to the jake executable.

Windows, installing from source

For Windows users installing from source, there are some additional steps.

Assumed: current directory is the same directory where node.exe is present.

Basic usage

jake [options ...] [env variables ...] target

Description

Jake is a simple JavaScript build program with capabilities similar to the
regular make or rake command.
Jake has the following features:
* Jakefiles are in standard JavaScript syntax
* Tasks with prerequisites
* Namespaces for tasks
* Async task execution

Jakefile syntax

API Docs

Tasks

Use task to define tasks. Call it with two arguments (and one optional
argument):

task(name, [prerequisites], action, [opts]);

The name argument is a String with the name of the task, and prerequisites
is an optional Array arg of the list of prerequisite tasks to perform first.

The action is a Function defininng the action to take for the task. (Note that
Object-literal syntax for name/prerequisites in a single argument a la Rake is
also supported, but JavaScript's lack of support for dynamic keys in Object
literals makes it not very useful.) The action is invoked with the Task object
itself as the execution context (i.e, "this" inside the action references the
Task object).

The opts argument is optional. When a task's operations are asynchronous, the
async property should be set to true, and the task must call complete() to
signal to Jake that the task is done, and execution can proceed. By default the
async property is false.

Tasks created with task are always executed when asked for (or are a
prerequisite). Tasks created with file are only executed if no file with the
given name exists or if any of its file-prerequisites are more recent than the
file named by the task. Also, if any prerequisite is a regular task, the file
task will always be executed.

A Task is also an EventEmitter which emits the 'complete' event when it is
finished. This allows asynchronous tasks to be run from within other asked via
either invoke or execute, and ensure they will complete before the rest of
the containing task executes. See the section "Running tasks from within other
tasks," below.

File-tasks

Create a file-task by calling file.

File-tasks create a file from one or more other files. With a file-task, Jake
checks both that the file exists, and also that it is not older than the files
specified by any prerequisite tasks. File-tasks are particularly useful for
compiling something from a tree of source files.

desc('Calls the foo:bar task without its prerequisites.');
task('executeFooBar', function () {
// Calls foo:bar without its prereqs
jake.Task['foo:baz'].execute();
// Can keep running this over and over
jake.Task['foo:baz'].execute();
jake.Task['foo:baz'].execute();
});

If you want to run the task and its prerequisites more than once, you can use
invoke with the reenable method.

desc('Calls the foo:bar task and its prerequisites.');
task('invokeFooBar', function () {
// Calls foo:bar and its prereqs
jake.Task['foo:bar'].invoke();
// Does nothing
jake.Task['foo:bar'].invoke();
// Only re-runs foo:bar, but not its prerequisites
jake.Task['foo:bar'].reenable();
jake.Task['foo:bar'].invoke();
});

The reenable method takes a single Boolean arg, a 'deep' flag, which reenables
the task's prerequisites if set to true.

desc('Calls the foo:bar task and its prerequisites.');
task('invokeFooBar', function () {
// Calls foo:bar and its prereqs
jake.Task['foo:bar'].invoke();
// Does nothing
jake.Task['foo:bar'].invoke();
// Only re-runs foo:bar, but not its prerequisites
jake.Task['foo:bar'].reenable(true);
jake.Task['foo:bar'].invoke();
});

The list displayed will be all tasks whose namespace/name contain the filter-string.

Breaking things up into multiple files

Jake will automatically look for files with a .jake extension in a 'jakelib'
directory in your project, and load them (via require) after loading your
Jakefile. (The directory name can be overridden using the -J/--jakelibdir
command-line option.)

This allows you to break your tasks up over multiple files -- a good way to do
it is one namespace per file: e.g., a zardoz namespace full of tasks in
'jakelib/zardox.jake'.

Note that these .jake files each run in their own module-context, so they don't
have access to each others' data. However, the Jake API methods, and the
task-hierarchy are globally available, so you can use tasks in any file as
prerequisites for tasks in any other, just as if everything were in a single
file.

Environment-variables set on the command-line are likewise also naturally
available to code in all files via process.env.

File-utils

Since shelling out in Node is an asynchronous operation, Jake comes with a few
useful file-utilities with a synchronous API, that make scripting easier.

The jake.mkdirP utility recursively creates a set of nested directories. It
will not throw an error if any of the directories already exists. Here's an example:

jake.mkdirP('app/views/layouts');

The jake.cpR utility does a recursive copy of a file or directory. It takes
two arguments, the file/directory to copy, and the destination. Note that this
command can only copy files and directories; it does not perform globbing (so
arguments like '*.txt' are not possible).

jake.cpR(path.join(sourceDir, '/templates'), currentDir);

This would copy 'templates' (and all its contents) into currentDir.

The jake.readdirR utility gives you a recursive directory listing, giving you
output somewhat similar to the Unix find command. It only works with a
directory name, and does not perform filtering or globbing.

jake.readdirR('pkg');

This would return an array of filepaths for all files in the 'pkg' directory,
and all its subdirectories.

The jake.rmRf utility recursively removes a directory and all its contents.

jake.rmRf('pkg');

This would remove the 'pkg' directory, and all its contents.

Running shell-commands: jake.exec and jake.createExec

Jake also provides a more general utility function for running a sequence of
shell-commands.

jake.exec

The jake.exec command takes an array of shell-command strings, and an optional
callback to run after completing them. Here's an example from Jake's Jakefile,
that runs the tests:

jake.createExec and the evented Exec object

Jake also provides an evented interface for running shell commands. Calling
jake.createExec returns an instance of jake.Exec, which is an EventEmitter
that fires events as it executes commands.

It emits the following events:

'cmdStart': When a new command begins to run. Passes one arg, the command
being run.

'cmdEnd': When a command finishes. Passes one arg, the command
being run.

'stdout': When the stdout for the child-process recieves data. This streams
the stdout data. Passes one arg, the chunk of data.

'stdout': When the stderr for the child-process recieves data. This streams
the sterr data. Passes one arg, the chunk of data.

'error': When a shell-command exits with a non-zero status-code. Passes two
args -- the error message, and the status code. If you do not set an error
handler, and a command exits with an error-code, Jake will throw the unhandled
error. If breakOnError is set to true, the Exec object will emit and 'error'
event after the first error, and stop any further execution.

To begin running the commands, you have to call the run method on it. It also
has an append method for adding new commands to the list of commands to run.

Using the evented Exec object gives you a lot more flexibility in running shell
commmands. But if you need something more sophisticated, Procstreams
(https://github.com/polotek/procstreams) might be a good option.

Logging and output

Using the -q/--quiet flag at the command-line will stop Jake from sending its
normal output to standard output. Note that this only applies to built-in output
from Jake; anything you output normally from your tasks will still be displayed.

If you want to take advantage of the -q/--quiet flag in your own programs, you
can use jake.logger.log and jake.logger.error for displaying output. These
two commands will respect the flag, and suppress output correctly when the
quiet-flag is on.

You can check the current value of this flag in your own tasks by using
jake.program.opts.quiet. If you want the output of a jake.exec shell-command
to respect the quiet-flag, set your printStdout and printStderr options to
false if the quiet-option is on:

This will automatically create a 'package' task that will assemble the specified
files in 'pkg/fonebone-v0.1.2112,' and compress them according to the specified
options. After running jake package, you'll have the following in pkg/:

FileList

Jake's FileList takes a list of glob-patterns and file-names, and lazy-creates a
list of files to include. Instead of immediately searching the filesystem to
find the files, a FileList holds the pattern until it is actually used.

When any of the normal JavaScript Array methods (or the toArray method) are
called on the FileList, the pending patterns are resolved into an actual list of
file-names. FileList uses the minimatch module.

To build the list of files, use FileList's include and exclude methods:

The include method can be called either with an array of items, or multiple
single parameters. Items can be either glob-patterns, or individual file-names.

The exclude method will prevent files from being included in the list. These
files must resolve to actual files on the filesystem. It can be called either
with an array of items, or mutliple single parameters. Items can be
glob-patterns, individual file-names, string-representations of
regular-expressions, or regular-expression literals.

TestTask

Instantiating a TestTask programmically creates a simple task for running tests
for your project. The first argument of the constructor is the project-name
(used in the description of the task), and the second argument is a function
that defines the task. It allows you to specifify what files to run as tests,
and what to name the task that gets created (defaults to "test" if unset).

Tests in the specified file should be in the very simple format of
test-functions hung off the export. These tests are converted into Jake tasks
which Jake then runs normally.

If a test needs to run asynchronously, simply define the test-function with a
single argument, a callback. Jake will define this as an asynchronous task, and
will wait until the callback is called in the test function to run the next test.

NpmPublishTask

The NpmPublishTask builds on top of PackageTask to allow you to do a version
bump of your project, package it, and publish it to NPM. Define the task with
your project's name, and the list of files you want packaged and published to
NPM.