The Karma Project: Code Less, Teach More

January 15, 2010

Get Started with Jake, a Rake clone in JavaScript

Filed under: News — Tags: , , , , — bryanwb @ 8:33 am

In my last post, I gave an introduction to narwhal, a standard library for JavaScript. This time I will explore Jake, a Rake clone in JavaScript. I have been using it for the repetitive tasks in the Karma project like generating documentation, cleaning up temporary files, and checking out the latest version and packaging it for deployment. You may want to take a look at my Jakefile before you work through this tutorial.

What Jake doesn’t have

  • XML files
  • Special syntax

Jake only has pure JavaScript. This is a good thing. (mental) Context switching is expensive, particularly for utility scripts you might only look at once every few months.

Why use *-ake?

Managing a software project, especially web development projects, I find myself needing to do a number of repetitive and mind-numbing tasks that often, but not always, need to be done in a certain order. When packaging a new release of Karma, I usually want to check out the latest code from several repositories, put all the files in a temporary directory, remove unnecessary files, minify the source, and copy common JavaScript and CSS files to a common directory. Sometimes, I just want to check out the latest code. Sometimes I just want to minify the source and not move around the JavaScript and CSS files.

Here are the Tasks

  1. Check out files from version control
  2. Copy files to a temporary build/ directory
  3. Copy Common JS and CSS to a common directory, change references to new paths
  4. Remove files not needed for deployment to the server like docs, tests, utilities
  5. Minify JS and CSS files
  6. Optionally, compress project files into a tarball or zip file

Here is how those same tasks map to Jake tasks

  1. Check out files from version control ==> jake checkout
  2. Copy files to a temporary build/ directory  ==> jake build-dir
  3. Copy Common JS and CSS to a common directory, change references to new paths  ==>jake move-common-files
  4. Remove files not needed for deployment to the server like docs, tests, utilities ==> jake repack
  5. Minify JS and CSS files ==> jake minify
  6. Optionally, compress project files into a tarball or zip file  ==> jake package

Now some of these tasks depend on previous tasks so I shouldn’t be able to run them unless the previous tasks have been completed. But if they have been completed, I don’t want to rerun them. This is what buildmasters call <em>build dependencies</em>.

There is a task I haven’t yet specified, <code> jake build </code> which depends on tasks 1-6. I will show you an example build task later in the tutorial. Now let’s go back to creating basic tasks.

First Steps with Jake

Next, let’s set up jake. Narwhal has a package manager called tusk, which is comparable to ruby’s gem and Python’s easy_install.

$ tusk install jake
you@computer$ jake
No Jakefile found (looking for: jakefile, Jakefile, jakefile.js, Jakefile.js, jakefile.j, Jakefile.j)

Jake, like its siblings Rake and Make, requires a Jakefile that contains jake tasks.

Here is a very simple Jakefile

//import the jake module
//This is equivalent to python's "import" statement
var  JAKE = require("jake");
// JAKE.task('taskname', [ dependencies ], function(){});
JAKE.task('hello', function(){
      print('hello world');
});

Like Rakefiles, Jakefiles contain pure JavaScript. You should see a number of commands that are specific to narwhal. It is beyond the scope of this tutorial to cover those. I recommend you take a look at the narwhal documentation here.

To execute this simple hello task, run the following in the same directory as the Jakefile

$ jake hello
hello

Now let’s do something more interesting. I frequently need to regenerate the documentation for karma.js using a long shell command that I can never remember all the switches for. I use the excellent jsdoc-toolkit.

JAKE.task('docs', function(){
        var path = './tools/jsdoc-toolkit';
         if(FILE.exists(path)){
             var cmd = 'java -jar ' + path + '/jsrun.jar ' +
                 path + '/app/run.js ' + './js/karma.js -d=docs/ ' +
                 '-t=tools/jsdoc-toolkit/templates/jsdoc/';
             OS.system(cmd);
         } else {
             print("The folder ./tools/jsdoc-toolkit isn't present " +
                   "you need it to generate documentation");
         }

});

May prefer passing an array to OS.system rather than a string.

var cmd = [
   'java', '-jar', path + '/jsrun.jar',
   path + '/app/run.js', './js/karma.js',
   '-d=docs/', '-t=tools/jsdoc-toolkit/templates/jsdoc/'
];
OS.system(cmd);

One task that I run quite quickly is “jake clean” which I use to get rid all the temporary files created by text editors. Importing the submodule jake/clean automatically adds the “clean” task to your Jakefile. The next step is to add regular expressions that I want cleaned. The syntax for regular expressions here is not what I am used to. If may look odd to you too.

var CLEAN_LIB = require('jake/clean');  //adds the tasks clean and clobber
var CLEAN = CLEAN_LIB.CLEAN;
//include the temporary files created by text editors
CLEAN.include('**/#*#', '\.#*' , '**/\.tmp*',"**/\.*\.*\.swp");
CLEAN.exclude('\.git');    //don't touch my .git directory!

The regular expressions in the CLEAN.include() statement may look odd and that is because they are not regular expressions at all. Rather they are glob expressions.

Now, let’s run the clean task

$ jake clean

Here I tell the clobber task to delete my entire build-dir/ directory

var CLOBBER = CLEAN_LIB.CLOBBER;
CLOBBER.include('**/build-dir');
CLOBBER.exclude('\.git');

Often during a build process you find yourself checking if a particular file or directory exists and creating it if it doesn’t. Jake’s filedir() method is great shorthand for this. JAKE.filedir() which runs the task’s action if a) the target file (passed as the task name) doesn’t exist, or b) any of the dependencies’ timestamps are newer than the target’s timestamp.

filedir ("build-dir", ["debug", "release"], function()
{
    FILE.mkdirs("build-dir");
});

Now let’s go back to the 6 build tasks I outlined earlier in this article. Let’s create the build meta-task. We can specify dependencies for the build task as an array for the second argument to Jake.task. The dependencies will be run before the the build task if they are not up-to-date.

JAKE.task('build',['checkout', 'build-dir', 'move-common-files', 'repack', 'minify', 'package'],  function()
{
    /* do any finishing touches */
});

I have just scratched the surface of what Jake can do. You may want to look through my Jakefile for ideas. Cappuccino’s Jakefile is also a great example of what can be done with Jake.

Jake is a great tool and narwhal is a very useful platform. While quite young, narwhal is quite a stable and feature-rich platform. The biggest drawback that I have found working with narwhal is that documentation is quite lacking. Hopefully this will be resolved shortly.

About these ads

1 Comment »

  1. thanks for admin wonderfull information…

    Comment by aşk büyüsü — October 6, 2010 @ 1:46 pm


RSS feed for comments on this post.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

The Shocking Blue Green Theme. Create a free website or blog at WordPress.com.

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: