Ninja based build tool

This is a tool for building projects using Ninja. It assumes your project follows a certain layout.

Quick start

npm install --save-dev benbria-build
npm install --save-dev ninja-build
npm install --save-dev coffee-script
npm install --save-dev [other optional dependencies - see below]
mkdir src
echo "console.log 'hello world'" > src/index.coffee
./node_modules/.bin/benbria-configure-ninja
./node_modules/.bin/ninja

This benbria-configure-ninja configures the Ninja build process, generating build.ninja. See the Ninja manual for more information.

Project Layout

This assumes you have a project with the following file structure:

/
|-- src
+-- assets
    |-- js
    +-- css

• /src - Server side source code goes here. Every file here will be compiled into a .js and .map file in /lib. This can include .js, .coffee, ._js, ._coffee.
• /assets - Client side assets. There are two different client side build types - debug and release. Build artifacts will end up in /build/assets/debug or /build/assets/release, accordingly.
• /assets/js - Client side source code. This can include .js, .coffee. coffee files can include snockets directives. Any file that starts with an "_" will not be compiled - handy for files that are included via snockets and not used independently.
• /assets/css - Client side CSS, right now being .styl. (TODO: Would be nice if we copied .css files.)

By convention we put browserify bundles in assets/browserify. (We don't put them in assets/js, since we don't want the files to by compiled into the build directory.)

Dependencies

Your project should have any the following optional dependencies specified as dependencies or devDependencies in it's project.json, and installed in the node_modules folder. All of these are optional; so long as you don't need the specified feature, you don't need them installed:

• coffee-script - Required for building .coffee files in /src.
• snockets-cli - Required for building coffee files in /assets.
• streamline - Required for building ._js and ._coffee files in /src. If you are using < 0.10.x, then make sure you pass --streamline8 to build-configure-ninja. Otherwise, streamline 0.10.9 or newer is required. You can also use --streamline-opts '--cb _cb' to set whatever extra streamline options you want. Streamline is not currently supported for files in /assets/js.
• stylus - required for building .styl files. You can use --stylus-opts '--import node_modules/nib/index.styl' to set arbitrary extra stylus options.
• browserify - Required for building browserify bundles. Note that in debug builds, benbria-build will automatically compute all dependencies for your bundle, so your bundle only be recompiled if it needs to be. For release builds, dependencies are not detected, so the bundle will only be recompiled if the main file for the bundle is modified.

Ninja Edges

benbria-configure-ninja will generate a ninja file with the following edges:

• lint - Lint all source files.

• lib - Compile all source files in /src to /lib. This will automatically include:

  • *.js - Copied directly over.
  • *.coffee, *.litcoffee, *.coffee.md - Compiled to .coffee file. Sourcemap will be generated.
  • *._js, *._coffee - Compiled with streamline compiler. Souremaps will be generated if your streamline compiler is v0.10.x or better. Note you need to specify --streamline8 for v0.8.x. Lower than v0.8.x is not supported.

• debug-assets - Build files in the assets folders. Compiled files go into build/assets/debug. Any files which start with an "_" will be excluded from the build:

  • assets/js/*.coffee, assets/js/*.js - Javascript: These will be compiled with snockets support.
  • assets/*.styl - CSS.

• release-assets - Same as debug-assets except compiled files go into build/assets/release. Also this will run all files through the "fingerprint" process, producing a build/release/fingerprints.json.

Customizing the build

Build edges are generated by factory objects defined in src/ninjaFactories.coffee. You can define your own factories to customize your build process. For example, to build a browserify bundle as part of the build, create a file called ninjaConfig.coffee:

{defineFactory} = require 'benbria-build'

# Browserify bundle
defineFactory "foo-bundle", {
    makeRules: (ninja, config) ->
        ['debug', 'release'].forEach (releaseType) ->
            cli = "$buildCoffee ./assets/foo/doBuild.coffee -o $out"
            cli += if (releaseType is 'release') then '' else ' --debug'

            ninja.rule("foo-#{releaseType}")
                .run(cli)
                .description "(#{releaseType}) BROWSERIFY $in"

    assetFiles: 'foo/src/foo.coffee'

    makeAssetEdge:  (ninja, source, target, releaseType) ->
        ninja.edge(target)
            .from(source)
            .using("foo-#{releaseType}")
        return [target]
}

Then when you run benbria-configure-ninja:

benbria-configure-ninja --require './ninjaConfig.coffee'

Browserify bundles

You can register a factory to create a browserify bundle:

# Browserify bundle for reporting
defineBrowserifyFactory "inbox",
    "browserify/inbox/inbox.coffee",
    "inbox/inbox.js", {
        extensions: ['.coffee', '.jade']
        transform: [
            'coffeeify'
            'browserify-jade'
            'aliasify'
            'includify'
            'rfolderify'
            'debowerify'
        ]
    }

This will read assets/browserify/inbox/inbox.coffee, and compile it to build/assets/[buildtype]/js/inbox/inbox.js. i18n-extractor is automatically run on the output, and in debug mode a dependencies file is built, so ninja will know whether or not your js file needs rebuilding. For release mode, the bundle is automatically minified using uglify-js.

Configure Coffeelint

benbria-build has a default set of paths it lints. Those paths being the assumed directory structure (see above). If you have some extra paths you would like to lint, or perhaps omit, you can override the defaults like so:

{configureCoffeelint} = require 'benbria-build'
configureCoffeelint {
    extensions: [
        'coffee'
        '_coffee'
    ]
    paths: [
        'src/**/*.$ext'
        'assets/js/**/*.$ext'
        'assets/browserify/**/*.$ext'
        'bin/**/*.$ext'
        'Gruntfile.$ext'
    ]
}

Where $ext will be replaced by each item in the extensions array of the options hash. This example adds the new path 'assets/browserify/**/*.$ext' to be linted.

Handy Tips

Run:

scripts/browserify-bundle.coffee \
  --transforms 'coffeeify,browserify-jade' \
  --show myFile.coffee

to see what a set of transforms is going to do to a source file.

Future improvements:

• Should support streamline in /assets.
• Could offer more control over browserify builds.