Getting the code

The official Pentadactyl source code is hosted on Google Code. The easiest way to get a copy of the latest code is to clone the main Mercurial repository:

hg clone http://dactyl.googlecode.com/hg/ dactyl

You can also browse the repository or monitor changes online.

Warning: If you're running Windows®, you may have trouble building or running from our repo due to Mercurial's handling of symbolic links. For a fix, see this FAQ entry.

Hacking the code

The best way to begin hacking Dactyl source code is by reading the included HACKING and README.E4X files, along with the developer :help page. After that, you may want to start working on a plugin before you dive into the main code.

Building an XPI

Once you have a copy of the source, you can easily build an XPI for any Dactyl project from the root of the tree by running:

make -C <project> xpi

For example, you can build a Pentadactyl XPI with,

make -C pentadactyl xpi

This resulting XPI will be placed in the downloads/ folder.

However, as creating and installing a new XPI file after each update is cumbersome, most developers run Pentadactyl directly from their working copies. This can usually be accomplished by running

make -C <project> install

This should automatically install an extension proxy in your profile directory. (You normally only ever need to do this once.)

Build dependencies

  • zip
  • gmake
  • Standard POSIX commands: awk, echo, sed, sh

While most developers use a Unix-like operating system, you can also build Pentadactyl on Windows with the help of MinGW's MSYS, Cygwin, or SFU.

Updating

You can update your repository to the latest development version by running

hg pull -u

Note: In order for some changes to take effect upon a restart, you may need to remove the XPC.mfasl file from your Firefox profile directory, or the contents of the startupCache/ directory in Firefox 4. Additionally, changing the following Firefox preferences may help you quicken your development cycle:

'browser.dom.window.dump.enabled'
When set to true, dactyl will dump certain debugging information to the console, including stack traces from exceptions in most parts of the code.
'nglayout.debug.disable_xul_cache'
When set to true, all chrome is loaded from scratch every time you open a new Firefox window, which removes the need for most restarts. Notable exceptions include code in the modules/ and components/ directories.
'nglayout.debug.disable_xul_fastload'
When set to true, disable caching of code between Firefox restarts. When unset, some changes will require the removal of XUL.mfasl or startupCache/* as noted above.

See also the Mozilla Development Center article on setting up extension development environment.

Submitting patches

If you make changes that you think are worth contributing back to the project, we recommend using the mercurial patchbomb extension. Once you've enabled it in your .hgrc, the following:

hg email -o -t dactyl-patches@googlegroups.com

will generate e-mails with properly formatted patches for all of the changesets you have made on top of the cloned repository. These patch emails should be sent to the patches mailing list.

Additionally, you would be well served by the Mercurial Queue extension if you plan to develop patches often.

Note: In order for a patch to be accepted, the following conditions must be met:

  • Any user-visible changes beyond basic bug fixes have to be accompanied by correct documentation and an entry in the NEWS file.
  • The commit message must be descriptive of the commit.
  • Any revision referenced in a commit message must be written as ‘revision {commit hash}’ where {commit hash} is an abbreviated Mercurial changeset ID (not a local revision number).
  • Any issue referenced by the commit must be written as ‘issue #{issue number}’, and if the commit closes an issue, it must contain the sentence ‘Closes issue #{issue number}’ or ‘Fixes issue #{issue number}’.