Restartless-Template

Simple template project for developing restartless Firefox Developer Tools addons.

Workflow

This template allows you to create restartless Firefox add-ons. This means that your workflow can also benefit from it, and reduce the (likely annoying) code->build->install lag. See documentation about setting up a bootstrapped addon extension environment for some in-depth explanation on how to do this.

tl;dr: A "Firefox extension proxy file" is a simple way of telling Firefox where an add-on is located, via an absolute path. Whenever you change the contents of the add-on, simply re-enabling it will update it; no need to tediously drag-and-drop-install it anymore.

How to iterate fast

The quick and easy version

This will probably work in most unix-like shell environments, like in OS X and Linux:

git clone https://github.com/victorporof/Restartless-Template.git
cd Restartless-Template
./configure -i "your-addon-id" -n "YourAddonName" -d "Your addon description" -a "Your name" -P "default"

Caveats: Temporarily, until issue #3 is fixed:

./configure can only be used once after cloning the repo;
-i and -n must not contain spaces, and only use alphanumeric characters.

That's it :) Now, after you change something in the add-on, simply re-enable it for it to update automatically. You can do this from the about:addons page in Firefox: click the "Disable", then the "Enable" button for your add-on.

The detailed version

Step 0. Clone this repository.

Step 1. It's a good idea to customize your add-on's id and name now, before things get too complex. By default, this template has a vanilla my-addon id and MyAddon name. You should modify this using ./configure.

./configure -i awesome-addon-id to set the id; this will be useful when creating an extension proxy file.
./configure -n AwesomeTool to set the name; this will be displayed in the Toolbox and various Firefox menus.

Initially, please try to only use alphanumeric characters for the add-on's id and name.

Optionally, you can also specify the add-on's author, version, description etc.:

./configure -v 1.0 to set the version; this is useful for tracking bugs and letting your users know which add-on version they're using.
./configure -d "An awesome description" to set the description; this will be shown on addons.mozilla.org when publishing your add-on.
./configure -a "Your name" to set the autor's name; this will be, as well, shown on addons.mozilla.org.

Step 2. Locate your Firefox profile directory. Read this for more information. It's usually in these folders:

OS X: ~/Library/Application Support/Firefox/Profiles/<profile folder>
Linux: ~/.mozilla/firefox/<profile folder>
Windows: %APPDATA%\Mozilla\Firefox\Profiles\<profile folder>

Optionally, you might want to create a new Firefox profile used just for the development of your add-on. This will prevent unexpectedly and accidentally altering your main profile if you make mistakes during the development process. Read more about how to do this here.

Step 3. Create a file in the "extensions" directory under your profile directory with the extension's ID as the file name. If there's no "extensions" folder, create it. The extension's ID is in the install.rdf file.

For example, with this vanilla template, the extension proxy file name would be my-addon@mozilla.com.

Step 4. Set the (plain text) contents of this file to be the path to the directory that contains install.rdf (where you cloned this repository).

For example, the extension proxy file's contents could be ~/home/myself/work/Restartless-Template.

Step 5. Restart Firefox. A dialog asking you whether "you would like to modify Firefox with the add-on" might show up; please allow the installation and continue.

Open Firefox Developer Tools using Ctrl/Cmd+Shift+I and you'll see your new addon in the Toolbox.

Debugging

Starting with Firefox 31 (download Aurora), you can easily debug your add-on using the built-in developer tools. Turn this on, then simply go to the about:addons page and click the "Debug" button next to your add-on. Keep in mind that scripts are lazily evaluated, so if no code was executed, no source files will be shown.

Theming

Starting with Firefox 29, the developer tools can be "light" or "dark" themed, based on a user preference in the Options panel of the Toolbox. To make your add-on look good regardless of the theme, you should use the .theme-dark and .theme-light selectors, as exemplified in skin/style.css.

.theme-dark #my-node {
  color: #f5f7fa;
}
.theme-light #my-node {
  color: #ed2655;
}

Take a look at this wiki for the recommended pallete used by default throughout the Firefox developer tools. Try using those colors for a consistent look and feel.

Localizing

It's always nice having your add-on available in multiple languages.

Add your localized strings to strings.dtd and strings.properties.

Generally, strings.dtd is used for static messages, added in the markup as soon as it's loaded, e.g in tool.xhtml. On the other hand, strings.properties is used for dynamic messages, which need to be set (or formatted) programatically, e.g. in tool.js.

Your default language bundle is specified by the chrome.manifest.

Remoting

The Firefox Developer Tools have support for remote debugging. The protocol is described in depth here. If you want to make your add-on work with remote debugging, you'll have to support remote targets and allow the add-on to use them.

Certain tools in Firefox will always use remote targets, so, for example, your add-on won't show up in the App Manager if remote targets are not supported.

Take a look at firefox-client repo for an example use of the remote debugging API.

Releasing

Simply make inside the project folder to build and archive the latest version of the add-on. A build directory will be created, containing an .xpi file representing your add-on. Subsequent calls to make will update the add-on file with the latest changes.

To wipe the build directory, use make clean.

If you use git tags to nicely version your project, you can use make head to build a "release" version of your add-on based on the latest commit. This will not take uncommitted changes into consideration.

Publishing

Go to https://addons.mozilla.org/developers/ and publish your new awesome add-on.

There's some (under development) documentation about the Developer Tools API. If you need help, please ask around on irc.mozilla.org, in #devtools.

Thank you. Have fun!

victorporof / firefox-restartless-template