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('foo.js')
 .log('read foo.js')
 .inspect()
 .write('foobarbaz.js')
 .run();

Execute Tasks Using Array Style

gear.queue()
 .load(['foo.js', {file: 'bar.js'}, 'baz.js'])
 .log('read foo.js')
 .inspect()
 .write(['newfoo.js', 'newbar.js']) // Not writing 'baz.js'
 .run();

Complex Task Execution

gear.queue()
 .load('foo.js')
 .log('Complex Task')
 .tasks({
    read: {task: 'load', options: ['foo.js', 'bar.js', 'baz.js'], callback: function(err, results) {}}
    combine: {task: 'concat', requires: ['read']}
    minify: {task: 'jsminify', requires: ['combine']}
    print: {task: 'inspect', requires: ['read', 'combine', 'minify']} // Runs when read, combine, and minify complete
    parallel: {task: 'log', options: "Hello gear world!"} // Run parallel to read
 }).run();

Documentation

Core

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

Core Tasks

• load
• write
• concat
• inspect
• log
• tasks

Library Tasks

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 - Filename or object to load.
// source.file - Filename of resource.
.load(['foo', 'baz'])
.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')

---

### tasks(workflow)

Arguments

• workflow - Task workflow.

Execute tasks in parallel with optional dependencies. Data is joined on 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.
.tasks({
    label_1: {task: 'log', options: 'Hello, world!'}
    label_2: {task: 'log', options: 'Hello, world 2!', requires: ['label_1']}
})

## Library Tasks

Install gear-lib which contains tasks such as:

• jslint
• jsminify
• csslint
• cssminify
• s3

npm install gear-lib

## 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.