Hate UML?

Draw sequence diagrams in seconds.

JZBUILD - An Easy Javascript Build System
Posted on: 2010-08-03 08:30:00

I love languages where you need years of experience to write code that works, and languages where if you don't do everything exactly right, you will shoot yourself in the foot. (See my article "C++: A language for next generation web apps"). Naturally, I love javascript.

Fortunately, Javascript has tools that will help catch bugs before you run it. One is JsLint. Following Douglas Crockford's crazy rules eliminates many cross-browser compatablility problems, and it syntax-checks the code too. The Google Closure compiler performs static analysis of the code to catch a few more problems, and as a bonus it will compress and obfuscate your code for you.

JZBUILD is a build system to simplify the process.

Download jzbuild.py

git clone http://github.com/smhanov/jzbuild.git

Like any of the other dozen javascript build systems, JZBUILD will:

  • Run all of your javascript through a built-in copy of jslint for error checking.
  • Concatenate files together and feed them into the Closure compiler or YUI compressor, without sending your code over the web.
  • Process include directives. JZBUILD resolves dependencies so your files will be included in the proper order.
  • Include files from other folders. For example, you might have a folder full of re-usable javascript components that are used in several projects. JZBUILD will let you pull these files into your current project.

JZBUILD is designed to be easy to use.

  • JZBUILD only requires python and Java to run. If you don't have another tool that it needs, it will download it automatically.
  • You don't need any configuration file. By default, JZBUILD will process all files in the current folder.
  • JZBUILD includes built-in "externs" for the closure compiler, so it will work with projects that use the jquery javascript library. It includes other tricks to make the compiler work on your code.
  • It works on Linux and Windows


Although this example is in Windows, JZBUILD works equally well on Linux.

Suppose you have a folder full of javascript files -- eg, foo.js, and bar.js.

 Directory of H:\demo

07/29/2010  09:25    <DIR>          .
07/29/2010  09:25    <DIR>          ..
07/29/2010  09:26              8392 foo.js
07/29/2010  09:26              2303 bar.js
               2 File(s)           10293 bytes
               2 Dir(s)     377,483,264 bytes free

Run JsLint on them:


Run JsLint and concatenate them together into MyWebApplication.js:

jzbuild.py --out MyWebApplication.js

Run JsLint and compress them using the YUI compressor into MyWebApplication.js. The YUI compressor will be downloaded for you.

jzbuild.py --out MyWebApplication.js --compiler yui

Run JsLint and compress them using the Google closure compiler into MyWebApplication.js. The compiler will be downloaded for you.

jzbuild.py --out MyWebApplication.js --compiler closure

Included files

JZBUILD processes include directives by searching the current folder and any included files. Suppose foo.bar contained a line like this:

//#include <bar.js>

And bar.js contained a line like this:

//#include <MyUsefulFunctions.js>

Where MyUsefulFunctions.js is in the folder ../shared. Then you can compile your whole web application by specifying only "foo.js" on the command line:

jzbuild.py --out MyWebApplication.js --compiler closure -I../shared foo.js

The -I option says to search the given path for input or included files. JZBUILD takes a list of input files on the command line. It reads each of them and processes included files as well, and sticks all of them together before sending them to the output file.

Note: It is incorrect to say JZBUILD "includes" files. The files are only included once, no matter how many times you specify "#include". This directive will be renamed "@require" in a future version.

Advanced Usage

When it starts, and you didn't specify "--out" on the command line, JZBUILD will look for a file named "makefile.jz" in the current folder.

Example makefile.jz

Here's an example makefile.jz. In it, we specify two projects to build. The "release" project will use the closure compiler to create MyWebApplication.js from "foo.js" and all files that it includes, searching in the folder "../shared" for any included files. It will also prepend "license.js" to the output.

It also specifies a second project, called "debug". The "debug" project contains the option "base: release", which means to inherit all the settings from the "release" project.

When this makefile is in the current folder, you can build a specific project by specifying its name on the command line. For example, to build the release project, use:

jzbuild.py release
// You can use comments in a JZBUILD makefile.jz. The file format is exactly like
// JSON, except that quotes and commas are optional.
// A file is an object of projects. Each project produces one output file.
// When you invoke JZBUILD you must specify a project to build unless there
// is only one in the file.
    // Here is a project description. You only need one project but we will
    // define several for completeness.

    // You can give a project a name. You can use it to refer to the project
    // from other projects.
    release: {
        // The output file will be created from the input files. It is a
        // string with the path to the output file.
        output: MyWebApplication.js

        // 'input' is an array of input files. You should use only the filename
        // and not the path. When jsbuild starts it will automatically find
        // the files it needs from the include path. It will also expand this
        // list based on any //#include  directives.
        input: [foo.js]

        prepend: [license.js]

        // The include path specifies an array of paths to search for files.
        // It always includes the current folder.
        include: [../shared]

        // The compiler specifies the compiler to use. The default compiler is
        // 'cat' which simply appends files together. The other
        // option is 'closure' which refers to Google's closure compiler. If
        // you do not have the closure compiler JZBUILD will download it for
        // you. However you will need to have Java installed to use it.
        compiler: closure

        // Here are the options to the closure compiler.
        compilerOptions: [
            --compilation_level ADVANCED_OPTIMIZATIONS
            --warning_level VERBOSE

    // Here is a second project.
    debug: {

        // This project is special because it inherits all the properties from
        // its parent project. It specifies the parent by name.
        base: release

        // Here we override the options to the closure compiler to include
        // pretty-printing so we can easily see what it is doing.
        compilerOptions: [
            --compilation_level ADVANCED_OPTIMIZATIONS
            --warning_level VERBOSE
            --formatting PRETTY_PRINT

Goodies to make the Closure compiler work properly

Built in externs

An externs file is built in to JZBUILD, so you can use the jquery library with the closure compiler, and it will give you useful warnings when you call the functions with the wrong parameter types.

@export annotation

A painful reality (and the whole point) of using the advanced compilation mode of the closure compiler is that it renames everything, so if you need to refer to a property of an object from HTML then it won't work unless you "export" it as described here.

JZBUILD makes this easy using the @export annotation. For example:

//@export MyGreatObject
/** @constructor */
function MyGreatObject()


//@export MyGreatObject.prototype.dostuff
MyGreatObject.prototype.dostuff = function()


When the compiler is set to "closure", the above will cause JZBUILD to add the required exports to the code. Specifically:

window["MyGreatObject"] = MyGreatObject;
MyGreatObject.prototype["dostuff"] = MyGreatObject.prototype.dostuff;


The JZBUILD system is open source. It is released to the public domain. However, it contains portions of code that fall under other licenses. The full license information is found in the source code.

Want more programming tech talk?
Add to Circles on Google Plus
Subscribe to posts

Post comment

Real Name:
Your Email (Not displayed):

Text only. No HTML. If you write "http:" your message will be ignored.
Choose an edit password if you want to be able to edit or delete your comment later.
Editing Password (Optional):

Roland Bouman

2010-08-10 21:45:50

hey, this looks like a pretty interesting build utility for javascript. Thanks, I'll check it out!


Other posts by Steve

Yes, You Absolutely Might Possibly Need an EIN to Sell Software to the US How Asana Breaks the Rules About Per-Seat Pricing 5 Ways PowToon Made Me Want to Buy Their Software How I run my business selling software to Americans 0, 1, Many, a Zillion Give your Commodore 64 new life with an SD card reader 20 lines of code that will beat A/B testing every time [comic] Appreciation of xkcd comics vs. technical ability VP trees: A data structure for finding stuff fast Why you should go to the Business of Software Conference Next Year Four ways of handling asynchronous operations in node.js Type-checked CoffeeScript with jzbuild Zero load time file formats Finding the top K items in a list efficiently An instant rhyming dictionary for any web site Succinct Data Structures: Cramming 80,000 words into a Javascript file. Throw away the keys: Easy, Minimal Perfect Hashing Why don't web browsers do this? Fun with Colour Difference Compressing dictionaries with a DAWG Fast and Easy Levenshtein distance using a Trie The Curious Complexity of Being Turned On Cross-domain communication the HTML5 way Five essential steps to prepare for your next programming interview Minimal usable Ubuntu with one command Finding awesome developers in programming interviews Compress your JSON with automatic type extraction JZBUILD - An Easy Javascript Build System Pssst! Want to stream your videos to your iPod? "This is stupid. Your program doesn't work," my wife told me The simple and obvious way to walk through a graph Asking users for steps to reproduce bugs, and other dumb ideas Creating portable binaries on Linux Bending over: How to sell your software to large companies Regular Expression Matching can be Ugly and Slow C++: A language for next generation web apps qb.js: An implementation of QBASIC in Javascript Zwibbler: A simple drawing program using Javascript and Canvas You don't need a project/solution to use the VC++ debugger Boring Date (comic) barcamp (comic) How IE <canvas> tag emulation works I didn't know you could mix and match (comic) Sign here (comic) It's a dirty job... (comic) The PenIsland Problem: Text-to-speech for domain names Pitching to VCs #2 (comic) Building a better rhyming dictionary Does Android team with eccentric geeks? (comic) Comment spam defeated at last Pitching to VCs (comic) How QBASIC almost got me killed Blame the extensions (comic) How to run a linux based home web server Microsoft's generosity knows no end for a year (comic) Using the Acer Aspire One as a web server When programmers design web sites (comic) Finding great ideas for your startup Game Theory, Salary Negotiation, and Programmers Coding tips they don't teach you in school When a reporter mangles your elevator pitch Test Driven Development without Tears Drawing Graphs with Physics Free up disk space in Ubuntu Keeping Abreast of Pornographic Research in Computer Science Exploiting perceptual colour difference for edge detection Experiment: Deleting a post from the Internet Is 2009 the year of Linux malware? Email Etiquette How a programmer reads your resume (comic) How wide should you make your web page? Usability Nightmare: Xfce Settings Manager cairo blur image surface Automatically remove wordiness from your writing Why Perforce is more scalable than Git Optimizing Ubuntu to run from a USB key or SD card UMA Questions Answered Make Windows XP look like Ubuntu, with Spinning Cube Effect See sound without drugs Standby Preventer Stock Picking using Python Spoke.com scam Stackoverflow.com Copy a cairo surface to the windows clipboard Simulating freehand drawing with Cairo Free, Raw Stock Data Installing Ubuntu on the Via Artigo Why are all my lines fuzzy in cairo? A simple command line calculator Tool for Creating UML Sequence Diagrams Exploring sound with Wavelets UMA and free long distance UMA's dirty secrets Installing the Latest Debian on an Ancient Laptop Dissecting Adsense HTML/ Javascript/ CSS Pretty Printer Web Comic Aggregator Experiments in making money online How much cash do celebrities make? Draw waveforms and hear them Cell Phones on Airplanes Detecting C++ memory leaks What does your phone number spell? A Rhyming Engine Rules for Effective C++ Cell Phone Secrets