Skip to content

Home

Jump to bottom Edit New page
myrdd edited this page Oct 3, 2014 · 19 revisions

RequestPolicy Development Wiki

Welcome to the RequestPolicy Development Wiki! This wiki is intended to encourage more people to become RequestPolicy developers and contributors.

Note that if you're having an idea for RequestPolicy, please talk about it in the issue tracker. What you shouldn't do is spending months implementing a feature in silence and then find yourself disappointed if we don't want to merge your changes. This would be frustrating for you, the other developers, and the RequestPolicy users.

Getting the Source Code

If you'd like to download the RequestPolicy source code from our version control system, you can do so with:

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

The above command will create a directory called requestpolicy. Under that is a src directory where the source code lives.

By the way, any XPI file (the extension file you install in your browser) contains all of the source code as well. XPI files are just zip archives which you can extract like any other. However, in version control there's a chrome.manifest file for local development that you'll probably want to use even if you're working from an extracted XPI.

Building the Extension XPI

Currently, ant is used. To build, run the following commands:

cd src
ant

After the build completes, the xpi will be located at dist/requestpolicy.xpi.

Developing Without Rebuilding the XPI

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.

Working with the Code

Now that you have a development environment setup, you can start tinkering with the code. The first thing to do is to change the RequestPolicy version number. To do this, edit the file src/install.rdf and, for example, change:

<em:version>0.5.23</em:version>

to:

<em:version>0.5.23-yourname1</em:version>

Now restart Firefox (the instance running your development profile you setup in the steps above) and check about:addons to verify that the new version number is shown there. If it is, you're almost ready to start developing.

The most common problem to hit at this point is that your version of Firefox is not supported by RequestPolicy (or, at least, is not supported by the particular RequestPolicy code you're starting development with). If necessary, you can force RequestPolicy to work with your version of Firefox by editing the file src/install.rdf and changing the values of minVersion or maxVersion.

The next thing to do is to enable RequestPolicy's logging. In Firefox, go to the URL about:config. Search for the keys containing requestpolicy. Locate the one called extensions.requestpolicy.log. Double-click this row to change the value to true. Now quit/exit/close Firefox. Note that you need to quit Firefox using File > Quit or by closing all browser windows. If you kill Firefox, e.g. with CTRL+c, the setting won't be saved because Firefox is a bit silly about when it decides to write settings changes to the settings files in your Firefox profile's directory.

Now, start Firefox again and be sure to start it '''from a command line'''. The logging will be done to stderr, not to Firefox's error console. So, if you don't start Firefox in a way that lets you see or capture stderr, you won't have access to the logged information. Assuming that when you start Firefox from a command line you see bunches of RequestPolicy log messages in the terminal you started Firefox from, you're ready to start developing.

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 &

Unit tests

There are two types of unit tests: MozMill tests and xpcshell tests. You can find setup instructions below. MozMill is used to test UI functionality, whereas the xpcshell is used for tests which only need access to XPCOM.

So far there are only few unit tests, so contributions are very welcome. To ensure quality of RP, every new feature should always get a unit test.

If you have any suggestion, please post it issue #51 or in a new one. If you have any questions, don't hesitate to ask! :)

MozMill

Install and configure

If you want to run the MozMill tests, first install MozMill and get the mozmill-tests repository. Instructions you can find here.

In the mozmill-tests folder, create a symbolic link firefox/tests/addons/requestpolicy@requestpolicy.com/ which links to the test/mozmill directory of the RP source code. After that, you have to add a 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.

To be able to access the test html files, you need a web server on port 80. One very simple method is to use python – execute sudo python -m SimpleHTTPServer 80 in RP's test/html/ directory.

Run

Finally, the mozmill command is

mozmill --addon-manifests=${path_to_RP_source}/tests/mozmill/addon-manifest.ini -b ${path_to_firefox_bin} -m ${path_to_mozmill-tests_folder}/firefox/tests/addons/requestpolicy@requestpolicy.com/manifest.ini

xpcshell

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

The commands I ran after fulfilling the prerequisites were:

# create a new directory where you want it
mkdir moz && cd moz

# get the source (also takes quite long)
hg clone https://hg.mozilla.org/mozilla-central/

cd mozilla-central/
./mach build

Creating a symlink

The bash scripts that are prepared for RP expect the mozilla-central/ folder to be in the /moz/ root directory. The easiest way is to create a symbolic link:

# replace ${MOZ_DIRECTORY} by the folder containing "mozilla-central"
sudo ln -is ${MOZ_DIRECTORY} /moz

Run

# run all of RP's xpcshell unit tests
tests/run-xpcshell-tests.sh

# run only one test by add the filename (without path) as the first argument
tests/run-xpcshell-tests.sh test_xyz.js

some random information

links

good to know

glossary

  • ruleset: a list of rules. can be empty.
  • rule: contains some selection specification (e.g. origin and destination) and a policy
  • policy: whether requests matching a rule are allowed or blocked
Add a custom footer
Clone this wiki locally