gear

gear

Task-Based Build System

gear is a scriptable build system using simple tasks that act like a sequence of piped commands.

Features include:

• Basic building blocks that can be combined to perform complex builds.
• Tasks simply transform input to output without relying on system internals.
• Asynchronous execution.
• Extensible task loading via NPM, file, or directory.
• Advanced flow control for complex task execution.

Installation

To get the most out of gear, you will want to install gear-lib which contains tasks for linting, minifying, and deploying JS/CSS assets.

npm install gear
npm install gear-lib

Quick Examples

Chaining Tasks

gear.queue()
 .load([{file: 'foo.js'}, {file: 'bar.js'}, {file: 'baz.js'}]
 .concat()
 .write({file: 'foobarbaz.js'})
 .run();

Complex Task Execution

gear.queue()
 .load([{file: 'foo.js'}])
 .log('Complex Task')
 .fork({
    read: {task: 'load', options: [{file: 'foo.js'}, {file: 'bar.js'}, {file: 'baz.js'}]}
    combine: {task: 'concat', requires: ['read']}
    output: {task: 'jsminify', requires: ['combine']}
    print: {task: 'inspect', requires: ['read', 'combine', 'output']}
 }).run();

Documentation

Core

• queue
• Queue.task
• Queue.run
• registry
• Registry.load

Tasks

• load
• write
• concat
• inspect
• log
• fork

Custom Tasks

## Core ### queue(options)

Creates a new Queue instance.

Arguments

• options.registry - Registry with available tasks.

Example

gear.queue()
 .log('test')
 .run();

---

### Queue.task(name, options)

Runs the specified task.

Arguments

• name - Name of task in registry.

Example

gear.queue()
 .task('log', 'Hello, world!')
 .run();

---

### Queue.run()

Runs the queue.

Example

gear.queue()
 .log('test')
 .run();

---

### registry()

Creates a new Registry instance.

Example

gear.registry();

---

### Registry.load(options)

Load from NPM, directory, or file.

Arguments

• options.module - Module to load tasks from.
• options.dirname - Directory to load tasks from.
• options.filename - File to load tasks from.

Example

gear.registry().load({dirname: 'foo'});

---

## Tasks ### load(sources)

Loads messages from different sources.

Arguments

• sources - List of sources.

Example

// source - What resource to load.
// source.file - Filename of resource.
.load([{file: 'foo'}, {file: 'bar'}, {file: 'baz'}])

---

### write(options)

Arguments

• options.file - File to write, will replace {checksum} with hash of message body.

Write the message to disk.

Example

.write({file: 'foo'})

---

### concat()

Concatenates messages.

Example

.concat()

---

### inspect()

Inspects a message.

Example

.inspect()

---

### log(message)

Arguments

• message - Message to log.

Log a message.

Example

.log('Finished')

---

### fork(tasks)

Arguments

• tasks - Task workflow.

Fork execution into parallel tasks with optional dependencies. Data is joined on fork completion.

Example

// label - Task instance name.
// label.task - Task name.
// label.options - Task options.
// label.requires - List of labels that must be executed before this task runs.
.fork({
    label_1: {task: 'log', options: 'Hello, world!'}
    label_2: {task: 'log', options: 'Hello, world 2!', requires: ['label_1']}
})

## Custom Tasks

Writing a task is especially easy compared to other Node build systems. There is no need to use gear internals within a task. Tasks operate on immutable messages. Messages have a body property. The task returns transformed data via its callback.

Arguments

• options - Options for the task.
• messages - Immutable list of messages created by other tasks. Messages must each have a body property.
• done(err, results) - Callback executed when task is complete.

Example

// example.js
// Example task replaces each message body with a string.
exports.example = function(string, message, done) {
    done(null, {body: string});
};

Running Example Task

gear.queue({registry: gear.registry({filename: 'example.js'})})
 .example('EXAMPLE')
 .run();

Special Thanks

gear takes inspiration from a few sources:

• Thread Building Blocks by Intel.
• buildy created by mosen.
• grunt created by cowboy.