Anvil

I wanted a way to build a single javascript module from several source files. Jake/Rake/Make aren't really doing enough for me. Everything else I found that came close was also trying to enforce how that output got used (Ender, Require, etc.).

I built anvil for myself, but I hope others find it useful.

What Does It Do?

Here's the current feature list:

• Create simple directory structure for new projects
• Create build.json files
• Combine multiple js or coffee files
• Compile coffee files into js (can be turned off to maintain coffee output)
• Lint resulting file(s)
• Uglify resulting file(s)
• Gzip resulting file(s)
• Run in a CI mode where anvil will re-compile the project on source file changes
• Dynamically generate a pavlov test page
  • Hosted on localhost:1580
  • Auto-refresh of the test page on code changes (thanks to @ifandelse
• Host integration pages at 3080
• Create integration page stubs including all external dependencies and build output

Installation

npm install anvil.js -g

By Convention

Without a build file, Anvil will make assumptions. Here's the list:

• All your source will be in ./src
• Your output will go to ./lib
• You want .coffee files compiled to .js
• Your final files will get run through lint
• Your final files will then be uglified as *.min.js
• Your final files will then be gzipped as *.min.gz.js

There isn't a wrapper by convention.

The Build File

{
    "source": "src",
    "output": "build",
    "lint": {},
    "uglify": {},
    "gzip": {},
    "extensions": { "uglify": "min", "gzip": "gz" },
    "wrap": {
        "prefix": "(function(context) {",
        "suffix": "})(this);"
    }
}

• source is where Anvil expects all your code. Don't get fancy or Anvil can't help you :(

• output is where Anvil will write all the build output and temp files. This should NOT be the same as source.

• lint specifies that you want your output files run through JSLint before Uglify and Gzip occur.

• uglify specifies that you want your output uglified. (happens before gzip)

• gzip specifies that you want your output gzipped.

• wrap

  • prefix prepends the following string to your output files.
  • suffix appends the following string to your output files.

There's also another option called justCoffee that will cause anvil to maintain all output in coffeescript instead of compiling it to js.

Jumpstart New Projects

Anvil will build a set of standard project directories for you and even spit out a build.json file based on the conventional use.

anvil -n <projectName>

Will produce a directory structure that looks like this:

-projectName
    |-ext
    |-src
    |-lib
    |-spec
    build.json

Building By Convention

If you don't specify your own build file, anvil assumes you intend to use a build.json file. If one isn't present, it will use its own conventions to build your project. If that's all you need, great! Chances are you'll want a build.json that's configured for your specific project.

Combining source files

Anvil allows you to combine source files by using a commented command

Javascript

//import("dependency.js");

Coffeescript

###import "dependency.js" ###

When you use Anvil to compile your project, it will traverse all the files in your source directory and combine them so that your top level files are what get output. Warning Currently, Anvil is not clever enough to detect circular import statements and it will break the world if you do this.

Building With Specific Build Files

To build with a specific build file type

anvil -b <buildfile>

Creating New / Additional Build Files

To create a build file, you can just type the following:

anvil -t <buildfile>

and it will create the build file for you. If you don't include the file name, anvil will create a build.json (possibly overwriting your existing one, be careful!)

Continuous Integration

Anvil will watch your source directory for changes and rebuild the project in the event any changes are saved to the files in the directory.

anvil --ci

Hosting

Anvil provides local hosting for pavlov test specification and integration tests via express.

External Dependencies

External dependencies get included in pavlov host pages and integration pages. The default directory these are stored in is "ext"

Fun With Coffee

External dependencies, lib files and specs can all be written in coffee script provided the files have a .coffee file extension. Anvil will translate these on-the-fly and serve the js to the browser.

Pavlov Hosting

Anvil will generate a pavlov test page for your output and host it in express at port 1580. All scripts in the lib, ext and spec folders will be included in this test page. The pavlov, qunit and jquery resources are symlinked into your root directory so that express will load these files correctly.

Thanks to a contribution from @ifandelse, if you're using the CI feature, the test page will automatically refresh itself after each successful build.

anvil -p

Integration Hosting

Anvil can also host files from the lib, ext, and html folders at port 3080. Unlike the pavlov host, there is no default page so the URL has to be page specific.

anvil -h

Generating Stub Integration Files

I am incredibly lazy. The thought of typing a bunch of script tags makes me tired. Therefore, anvil will do this for you.

anvil --html integration

Would create an integration.html file with script tags for all files found in lib and ext named integration.html

Too chatty?

You can tell anvil to run in quiet mode (it will still print errors (red) and step completions (green) )

anvil -q

Demo

If you have the source, check out the demo directory. It's intended to play around and test different features out. If you've installed anvil from npm, all you have to do is type:

cd demo
anvil

and watch how anvil builds the demo project.

If you've pulled the repository down, then try this: cd demo ../bin/anvil

If all's well, you should get some console output and the build directory should have three output files.

I suggest testing the --ci and -p arguments here. There's a silly test included in the spec folder to demonstrate the pavlov host.

To Do

• Provide advanced uglify configuration options
• Provide advanced JSLint configuration options
• Support pavlov tests for node projects