Developing RequestPolicy requires some prerequisites. If you only want to build the XPI file, possibly with some changes, you need only a few things.

A full development environment, on the other hand, includes an environment for running all unit tests. In case of the full dev environment you'll need to prepare much more, so that I recommend you to create a chroot directory.

Getting the Source Code

sudo apt-get install git

git clone https://github.com/RequestPolicyContinued/requestpolicy.git

Building the addon

sudo apt-get install make zip preprocess

make

Running Firefox and RP with Mozrunner

sudo apt-get install python-virtualenv

Download the file you need from Mozilla's FTP server. Extract the files into ${rp_root_dir}/.mozilla/software/firefox/nightly/. The binary file named firefox should be directly in that directory.

Hint: If you want, you could also install Fx Nightly elsewhere and create a symlink from ${rp_root_dir}/.mozilla/software/firefox/nightly/ to that directory.

make run

Running unit tests

Setting up an environment for unit testing is optional. You probably won't need it if you do just a few changes to the code.

xpcshell tests

Getting and building firefox

To be able to run the xpcshell you need to build firefox. Be prepared for a long compilation time – up to one hour or even more. You can find build instructions here. Note that a .mozconfig file is not necessary. (If you already have your own firefox build, you don't need to rebuild of course.)

# create a new directory /moz
sudo mkdir /moz
cd /moz

# get the source (also takes quite long)
hg clone https://hg.mozilla.org/mozilla-central/
# alternatively you can use git:
# git clone https://git.mozilla.org/integration/gecko-dev.git mozilla-central

cd mozilla-central/
sudo ./mach bootstrap
./mach build

./tests/run-xpcshell-tests.sh

Marionette

To run Marionette tests you currently need to manually set up a Web Server (port 80), including support for PHP. The web server's root directory has to be test/content/.

Besides the Web Server, you need to create aliases for the Web Server. To do that, add the following new line to your /etc/hosts file:

Not all of those domains are used at the moment, but they will, so add them all. By the way, .test is a reserved TLD.

sudo apt-get install python-virtualenv

make marionette

This will automatically download the python packages into a virtualenv directory.

enable logging

Logging is independant from the previous steps and can be done for any firefox profile. RequestPolicy's logging gives a lot of information about what is going on, so at least for delevoping it's recommended enable it.

By the way, besides RequestPolicy's own logging there's the Browser Console. Sometimes its output is very helpful for debugging. There's an issue about moving RequestPolicy's logging to the Browser Console, see #563.

summary

On about:config, set extensions.requestpolicy.log to true. Logging is done to stderr.

more in detail

To enable logging open the URL about:config in firefox and search for the keys containing requestpolicy. Locate the one called extensions.requestpolicy.log. Double-click this row to change the value to true. Logging should now be enabled immediately, but to see the output, you need to start firefox from the command line. The logging will be done to stderr, not to Firefox's error console.

If you want to capture the logged information to a file, you can redirect stderr to a file when you start Firefox. For example, the following command will start Firefox in the background and will redirect both stdout and stderr to a file named rp.log:

firefox -no-remote -P PROFILENAME >rp.log 2>&1 &

Developing Without Rebuilding the XPI (obsolete)

It's annoying to have to rebuild and reinstall the extension constantly during
development. To avoid that, you can create a "proxy" extension by creating a
file in your Firefox profile's extensions directory which tells Firefox that
it should look for the unpackaged extension files in a directory of your
choice.

Quick instructions

Detailed instructions

To install a proxy extension, first create a new Firefox profile through the
Firefox profile manager. To open the profile manager:

firefox -no-remote -profilemanager

Start Firefox using that profile, either selecting it in the profile manager
or using the command:

firefox -no-remote -P PROFILENAME

After you've created the new profile, figure out the
profile directory.
On Linux, it will often be ~/.mozilla/firefox/*/.
I'll call this PROFILE_DIRECTORY from here on out.

Next, use the following commands to create the proxy extension file for
RequestPolicy in your new profile.

# Change directory to your new profile's directory.
cd PROFILE_DIRECTORY

# Create the 'extensions' directory and change to that directory.
mkdir -p extensions
cd extensions

# Create a file called 'requestpolicy@requestpolicy.com' with a single
# line in the file which is the path to the 'src' directory.
echo "/path/to/requestpolicy/src" > requestpolicy@requestpolicy.com

Now start Firefox again using that profile. Firefox should now consider the
extension installed. To verify this, go to Tools > Addons > Extensions. You
should see RequestPolicy listed among the extensions.

Troubleshooting

If RequestPolicy is not installed at this point, you may need to repeat the
above steps to create the proxy extension file before trying again. This is
because if Firefox sees a problem with your proxy extension file (e.g. it's
named incorrectly or the path to the src directory in the file is
incorrect), Firefox may delete the file.

Note that you shouldn't try to install the extension xpi in a profile where
you've already created the proxy extension. To use an xpi that you've built,
use a new profile.

Setting up a development environment