development.md

layout	title	previous	next
article	Developing new libraries	libraries	testing

Our toolchain

Much of our JavaScript development toolchain consists of utilities written in Ruby. To get them up and running on your system you'll need Ruby 1.8.6 or higher and Rubygems, the Ruby package manager. Once those are installed, you just need to run the following command to install the relevant dependencies:

sudo gem install jake helium

All of our internal libraries, including JS.Class and Ojay, are kept under version control with Git. You will need a recent version of Git installed on your computer in order to develop new libraries and modify existing ones. It's very likely available through your operating system's package manager (e.g. aptitude on Ubuntu), but installing it from source is a relatively painless procedure.

There are many introductory Git tutorials available on the web. The Git repository hosting site, GitHub, list several on their help site. If you need commit access to any of our GitHub repositories, just ask. Please note, however, that Git is a distributed version control system: you can get a full copy of the entire repository and commit changes locally, without needing to have commit rights to the version on GitHub.

Build tools

Jake is a command line tool for building JavaScript packages from source code. Using YAML config files, you can specify any number of build files to be generated by concatenating and minifying groups of source files. All of our JavaScript libraries, if they exist outside a particular client project, have a Jake config file, jake.yml.

These config files also specify the JavaScript objects that the library provides, and which other objects they rely on. For example, the Panel library provides three objects--panel, Panel and PanelOverlay--and depends on four: JS.Class, Ojay, Ojay.HTML and Ojay.ContentOverlay.

The YAML code is very simple, and as we shall see, a skeleton jake.yml file can be generated when starting work on a new library.

{% highlight yaml %} provides:

• panel
• Panel
• PanelOverlay requires:
• JS.Class
• Ojay
• Ojay.HTML
• Ojay.ContentOverlay {% endhighlight %}

This dependency data is used by our other JavaScript deployment tool, Helium.

Extractions

JavaScript libraries tend to begin their lives in client projects. After all, we don't write these things for no reason: they're created to address specific needs. However, as soon as something begins to be used for more than one project, it needs to be extracted into a separate library. YouTube Player and Panel both started out within particular projects, but proved sufficiently useful and widely applicable that they were extracted into generic libraries.

There are several advantages to this way of doing things. Firstly, no code is ever written just because it might turn out to be useful: it is created to solve a specific problem at a specific point in time, and even if it turns out not to be generally useful, it will still have served its purpose.

Secondly, extractions are proven: they have been shown to work in real-world situations. There are two aspects to this. Firstly, they solve the problem they were intended to; secondly, their correctness and reliability are known quantities.

Lastly, and perhaps most importantly, extractions offer one the possibility of improving on one's initial efforts. Application code is often written in too much of a hurry; "After all," thinks the programmer, "it will never appear outside this site, so all it needs to do is work---I don't need to spend days ensuring it's interoperable and has a good API."

When extracting a library, one shouldn't be afraid of changing the API. After all, the intention is that the extracted code will be used in many places, not just one, so care must be taken to ensure that it will be easy to use and provide the features required. Fred Brooks suggested "write one to throw away", and the extraction process provides this: there are often important lessons to be learned from the mistakes and limitations of the first version. Discovering and solving these problems is a proven route to good library design.

Writing the library

The first step in writing a new library is to generate a stub project with the Helium command line tool. Just run the he create command:

he create my-library

Obviously my-library should be the name of the library you're writing. This will produce a summary like this:

Generating JavaScript project in /Users/beastaugh/projects/my-library...
create my-library/test/index.html
create my-library/source/my-library.js
create my-library/Jakefile
create my-library/jake.yml
create my-library/.gitignore

Building project using Jake...
create my-library/build/my-library.js
created: /Users/beastaugh/projects/my-library/build/my-library.js
create my-library/build/my-library-min.js
created: /Users/beastaugh/projects/my-library/build/my-library-min.js
Copying ./build/my-library-min.js --> ./test/lib/my-library-min.js
Writing package listing to ./test/packages.js

... done, now your new JavaScript project is ready.

  * Build your project by running `jake` in the root directory
  * We've added generated files to your .gitignore
  * Keep your dependencies up-to-date in jake.yml
  * Point test/index.html at your Helium server and write some tests!

If you're extracting existing code into the library, the first thing to do is copy it into the source directory in the new library directory. Next, you should amend the jake.yml file to reflect the source files your library contains. Then list its dependencies, and the objects it provides. In general, you shouldn't have to stray from the defaults too much, but most settings in the config file can be adjusted to suit the project at hand.