Labs/Ubiquity/Ubiquity 0.1 Development Tutorial

If you just want to write new commands for Ubiquity, you should read the Command Author Tutorial instead. This page is about how to do development on the Ubiquity core.

Getting Set Up

Getting the Source

It is pretty easy to get involved with the development of Ubiquity. Start off by introducing yourself on the irc channel #ubiquity on irc.mozilla.org.

You will need to have Python installed, preferably Python 2.5. (If you are on Mac OS X, you have Python already.) We use Python instead of Make for our build script.

We use Mercurial, called "Hg" for short, for version control. It is very easy to install if you've got Python 2.5 with setuptools. Just type:

 easy_install Mercurial

If you don't have setuptools, you can also install Hg the old-fashioned way, by downloading it from www.selenic.com.

Once installed, you will be able to checkout the current source using the command:

 hg clone http://hg.toolness.com/ubiquity-firefox

Installing the Source Version of the Extension

Uninstall your current version of Ubiquity from your Firefox Addons and then run:

 python manage.py install

This will generate a new build of the Ubiquity extension from the source checkout and install it with your local Firefox instance.

If you have a separate profile that you'd prefer to install the extension under, such as 'testing', you can add that as an optional parameter:

 python manage.py install testing

Now you are all set to become a pro Ubiquity hacker!

Uninstalling Ubiquity

Just run

python manage.py uninstall

optionally specifying a profile name/directory if necessary. Alternatively, you can also uninstall the extension through the normal Firefox addon management UI.

Building an XPI

To build an XPI for Ubiquity, just run:

 python manage.py build-xpi

This will create an XPI with the name "ubiquity-<version>.xpi", where "<version>" is taken from the contents of the "em:version" element in the "ubiquity/install.rdf" file.

You generally won't need to build an XPI when doing development, unless you're working on a final version intended for release to end-users.

Development

If you want to start writing code for Ubiquity, you need to follow the Mozilla's Javascript style guide (especially with respect to indentation and variable naming). This helps to maintain consistency in Ubiquity's code.

(TODO: find a style guide for HTML + CSS)

The heart of the code can be found in the subdirectory:

  ubiquity/chrome/content/

To get started, you may want to first take a look at the built-in commands and built-in noun types, which are in the files:

  ubiquity/chrome/content/builtincmds.js (TODO: no longer here. update this section)
  ubiquity/chrome/content/nlparser/en/nountypes.js

These files are dynamically loaded, so if you make any changes to them, all you have to do is save the file, then go back to Firefox and hit alt-space to bring up Ubiquity again. Your changes will be reflected immediately. There's no need to rebuild your extension or restart Firefox.

If you make changes to other files -- parts of the core, such as the parser, that are not dynamically loaded -- you will have to restart Firefox. Even in this case, there is no need for you to keep on rebuilding your extension. Once you've run python manage.py for the first time to install the extension, as described above, you shouldn't need to run it again. Just save the source file and restart Firefox and whatever changes you've made will be reflected in Ubiquity.

Don't Forget to Test

Make sure you run the test suite before committing your changes. From the root directory of your checkout, run:

   python manage.py test

That will only work if you have xpcshell installed. If you have built Mozilla from source, you should have xpcshell on your system. If you don't have it, another way to run the same test suite is by visiting this page:

 chrome://ubiquity/content/test.html

Due to slight differences between running javascript code in xpcshell on the command line, and running it in an html page, a test occasionally will fail on the html page even though it succeeds on the command line. In that case, you can ignore the failure on the html page. To be specific, you can ignore the following error message:

Error in test testSandboxSupportsJs17: missing ; before statement (in chrome://ubiquity/content/sandboxfactory.js, line 23)

Keeping Up to Date

I recommend that you frequently update your repository to get the latest changes from the central repository. In case you're not familiar with using Mercurial, pulling the code is a two-step process:

hg pull
hg update

You can also view the latest changes to the central repository on the web at hg.toolness.com.

Finding Something to Work On

We use this Wiki and GetSatisfaction as places to get feature requests and bug reports. These feed into an internal Trac-based ticketing system.

Login to the Trac using an OpenID account. Look for unassigned tickets (these are the ones that say "New" in the status column as opposed to "Assigned"). Check out what needs to be done, add things appropriately, choose unassigned tickets and start hacking!

Submitting Patches

When you're starting out with development, you won't have push access to the central hg repository. The best way for you to submit your changes is by creating a source code diff and attaching it to the Trac ticket that you're working on. The command line is like this:

hg diff > filename.diff

Note: In order for patches to be accepted, you need to follow the Mozilla's Javascript style guide (especially with respect to indentation and variable naming). This helps to maintain consistency in Ubiquity's code.

Then, on the Trac ticket page, click the "Attach file" button and choose the file you just created. Add a bit of explanation about your changes, and click "Submit changes". Don't change the status of the ticket yet.

One of the core developers will review your patch and, if it's found to be good, will commit it to the core repository and close the ticket.

After you've been developing for a while and have had some patches accepted, someone from the core development team (having noticed how awesome you are) will contact you to talk about getting you direct push access to the repository.