Labs/Ubiquity/Ubiquity 0.1 Development Tutorial
Note: these instructions cover development through current versions of Ubiquity, including versions 0.5.x.
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
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:
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:
This will put a copy of the Ubiquity source into the home directory on your computer. You need execute all the hg commands below from inside that directory.
Installing the Source Version of the Extension
Uninstall your current version of Ubiquity from your Firefox Addons and then run:
python manage.py install --profile=<profile name>
(Replace <profile name> with the name of the profile into which you prefer to install the extension.)
If you haven't created any profiles, then the profile you are using is called 'default'. To install Ubiquity into the default profile, do this:
python manage.py install --profile=default
This will generate a new build of the Ubiquity extension from the source checkout and install it with your local Firefox instance.
Now you are all set to become a pro Ubiquity hacker!
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
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.
To build an XPI for Ubiquity, just run:
python manage.py 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.
(TODO: find a style guide for HTML + CSS)
The heart of the code can be found in the subdirectories:
To get started, you may want to first take a look at the built-in and standard commands, which are in the files:
ubiquity/builtin-feeds/builtincmds.js ubiquity/standard-feeds/*.js ubiquity/standard-feeds/*.xhtml
The feeds 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 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 or built-in nountypes, 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:
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 ubiquity.mozilla.com.
Finding Something to Work On
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"). You can also search for the keyword "good-for-beginners". Check out what needs to be done, add things appropriately, choose unassigned tickets and start hacking!
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
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.