Setting up a development environment

Setting up a development environment

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 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.

Building the addon

At first you need to…

• get (clone) the source code
• install the build requirements

Then, to build the XPI, run

make

Running Firefox and RPC with Mozrunner

You will need:

• virtualenv

Installation on Debian-based systems:

sudo apt-get install python-virtualenv

Isolated Firefox installation

In order to not mess up your daily environment, the build and test processes use an isolated binary and Firefox's profile. Multiples Firefox versions can also be installed for testing purpose.

Download Firefox for RPC

Because the make process don't sign the XPI, a nightly build or developer edition of Firefox is needed. Those versions can be downloaded for Mozilla's FTP server. For testing purpose, you should at least download:

• latest ESR nightly build (here)
• latest nightly build (here) Note: At the moment, Firefox 57+ doesn't support Request Policy so the best option is to download an older version of the developer edition from here

1. Download the wanted versions tar.bz2 archive according to your OS, architecture (i686 for 32-bits, x86_64 for 64-bits) and language.
2. Extract the files into ${rp_root_dir}/dev_env/browsers/firefox/<firefox_version> (for instance replace <firefox_version> with "ff-52.5.1-esr-linux-i686")
3. Make a symlink to the default version you want to use (so you can change easily later):

cd ${rp_root_dir}/dev_env/browsers/firefox/
ln -sf ./<firefox_version> default-rp-dev

When you're done:

make run

Running tests

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

xpcshell unit 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.)

This is what I ran in a chroot environment:

# 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://github.com/mozilla/gecko-dev.git mozilla-central

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

Run all xpcshell tests:

./tests/run-xpcshell-tests.sh

Marionette UI tests

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:

127.0.0.1       maindomain.test www.maindomain.test sub-1.maindomain.test sub-2.maindomain.test otherdomain.test www.otherdomain.test sub-1.otherdomain.test sub-2.otherdomain.test thirddomain.test www.thirddomain.test sub-1.thirddomain.test sub-2.thirddomain.test

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.

Now you need:

• virtualenv
• Zip
• preprocess.py

Installation on Debian-based systems:

sudo apt-get install python-virtualenv zip preprocess

Run all marionette UI tests:

make marionette

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

Mocha Unit Tests

Some JS unit tests are available under /tests/unit. To launch them with Mocha:

make mocha

---

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

1. Create a new firefox profile, e.g. called rp-dev.
2. Start firefox with the new profile (e.g. firefox -no-remote -P rp-dev) and close it again.
3. Figure out the profile directory, go there and run this command: echo "/path/to/requestpolicy/src" > requestpolicy@requestpolicy.com (or do it by hand).

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

Now close this Firefox instance.

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.