-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathSetting-up-a-development-environment.html
182 lines (178 loc) · 13.8 KB
/
Setting-up-a-development-environment.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title></title>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
</style>
<link rel="stylesheet" href="./github-markdown.css">
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
<link rel="icon" type="image/x-icon" href="favicon.ico" />
</head>
<body>
<h1 id="setting-up-a-development-environment">Setting up a development environment</h1>
<p>Developing RequestPolicy requires some prerequisites. If you only want to build the XPI file, possibly with some changes, you need only a few things.</p>
<p>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.</p>
<h2 id="getting-the-source-code">Getting the Source Code</h2>
<p>You will need:</p>
<ul>
<li>Git</li>
</ul>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">sudo</span> apt-get install git</code></pre></div>
<hr />
<p>We use <code>git</code> as our version control system. This is how to get the code:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">git</span> clone https://github.com/RequestPolicyContinued/requestpolicy.git</code></pre></div>
<p>The command will create a directory called <code>requestpolicy</code>.</p>
<h2 id="building-the-addon">Building the addon</h2>
<p>You will need:</p>
<ul>
<li><a href="https://www.gnu.org/software/make/">GNU Make</a></li>
<li><a href="http://www.info-zip.org/Zip.html">Zip</a></li>
<li><a href="https://github.com/trentm/preprocess"><code>preprocess.py</code></a></li>
</ul>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">sudo</span> apt-get install make zip preprocess</code></pre></div>
<p>To build the XPI run</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">make</span></code></pre></div>
<h2 id="running-firefox-and-rp-with-mozrunner">Running Firefox and RP with Mozrunner</h2>
<p>You will need:</p>
<ul>
<li><code>virtualenv</code></li>
</ul>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">sudo</span> apt-get install python-virtualenv</code></pre></div>
<ul>
<li>Firefox Nightly</li>
</ul>
<p>Download the file you need from <a href="https://ftp.mozilla.org/pub/mozilla.org/firefox/nightly/latest-mozilla-central/">Mozilla's FTP server</a>. Extract the files into <code>${rp_root_dir}/.mozilla/software/firefox/nightly/</code>. The binary file named <code>firefox</code> should be directly in that directory.</p>
<p><strong>Hint:</strong> If you want, you could also install Fx Nightly elsewhere and create a symlink from <code>${rp_root_dir}/.mozilla/software/firefox/nightly/</code> to that directory.</p>
<p>When you're done:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">make</span> run</code></pre></div>
<h2 id="running-unit-tests">Running unit tests</h2>
<p>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.</p>
<h3 id="xpcshell-tests">xpcshell tests</h3>
<h4 id="getting-and-building-firefox">Getting and building firefox</h4>
<p>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 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions">here</a>. Note that a <code>.mozconfig</code> file is not necessary. (If you already have your own firefox build, you don't need to rebuild of course.)</p>
<p>This is what I ran in a chroot environment:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># create a new directory /moz</span>
<span class="kw">sudo</span> mkdir /moz
<span class="kw">cd</span> /moz
<span class="co"># get the source (also takes quite long)</span>
<span class="kw">hg</span> clone https://hg.mozilla.org/mozilla-central/
<span class="co"># alternatively you can use git:</span>
<span class="co"># git clone https://git.mozilla.org/integration/gecko-dev.git mozilla-central</span>
<span class="kw">cd</span> mozilla-central/
<span class="kw">sudo</span> ./mach bootstrap
<span class="kw">./mach</span> build</code></pre></div>
<p>Run all tests:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">./tests/run-xpcshell-tests.sh</span></code></pre></div>
<h3 id="marionette">Marionette</h3>
<p>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 <code>test/content/</code>.</p>
<p>Besides the Web Server, you need to create aliases for the Web Server. To do that, add the following new line to your <code>/etc/hosts</code> file:</p>
<pre><code>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</code></pre>
<p>Not all of those domains are used at the moment, but they will, so add them all. By the way, <code>.test</code> is a <a href="https://en.wikipedia.org/wiki/.test">reserved TLD</a>.</p>
<p>Now you need:</p>
<ul>
<li><code>virtualenv</code></li>
</ul>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">sudo</span> apt-get install python-virtualenv</code></pre></div>
<p>Run all marionette tests:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">make</span> marionette</code></pre></div>
<p>This will automatically download the python packages into a virtualenv directory.</p>
<hr />
<h2 id="enable-logging">enable logging</h2>
<p>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.</p>
<p>By the way, besides RequestPolicy's own logging there's the <a href="https://developer.mozilla.org/en-US/docs/Tools/Browser_Console">Browser Console</a>. Sometimes its output is very helpful for debugging. There's an issue about moving RequestPolicy's logging to the Browser Console, see <a href="https://github.com/RequestPolicyContinued/requestpolicy/issues/563">#563</a>.</p>
<h3 id="summary">summary</h3>
<p>On <code>about:config</code>, set <code>extensions.requestpolicy.log</code> to <code>true</code>. Logging is done to <code>stderr</code>.</p>
<h3 id="more-in-detail">more in detail</h3>
<p>To enable logging open the URL <code>about:config</code> in firefox and search for the keys containing <code>requestpolicy</code>. Locate the one called <code>extensions.requestpolicy.log</code>. Double-click this row to change the value to <code>true</code>. 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 <code>stderr</code>, not to Firefox's error console.</p>
<p>If you want to capture the logged information to a file, you can redirect <code>stderr</code> to a file when you start Firefox. For example, the following command will start Firefox in the background and will redirect both <code>stdout</code> and <code>stderr</code> to a file named <code>rp.log</code>:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">firefox</span> -no-remote -P PROFILENAME <span class="kw">></span>rp.log <span class="kw">2>&1</span> <span class="kw">&</span></code></pre></div>
<hr />
<h2 id="developing-without-rebuilding-the-xpi-obsolete">Developing Without Rebuilding the XPI (obsolete)</h2>
<p>It's annoying to have to rebuild and reinstall the extension constantly during<br />
development. To avoid that, you can create a "proxy" extension by creating a<br />
file in your Firefox profile's extensions directory which tells Firefox that<br />
it should look for the unpackaged extension files in a directory of your<br />
choice.</p>
<h3 id="quick-instructions">Quick instructions</h3>
<ol>
<li>Create a <a href="http://kb.mozillazine.org/Profile_Manager#Creating_a_new_profile">new firefox profile</a>, e.g. called <code>rp-dev</code>.</li>
<li>Start firefox with the new profile (e.g. <code>firefox -no-remote -P rp-dev</code>) and close it again.</li>
<li>Figure out the <a href="http://kb.mozillazine.org/Profile_folder_-_Firefox#Navigating_to_the_profile_folder">profile directory</a>, go there and run this command: <code>echo "/path/to/requestpolicy/src" > [email protected]</code> (or do it by hand).</li>
</ol>
<h3 id="detailed-instructions">Detailed instructions</h3>
<p>To install a proxy extension, first create a new Firefox profile through the<br />
Firefox profile manager. To open the profile manager:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">firefox</span> -no-remote -profilemanager</code></pre></div>
<p>Start Firefox using that profile, either selecting it in the profile manager<br />
or using the command:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">firefox</span> -no-remote -P PROFILENAME</code></pre></div>
<p>Now close this Firefox instance.</p>
<p>After you've created the new profile, figure out the<br />
<a href="http://kb.mozillazine.org/Profile_folder_-_Firefox#Navigating_to_the_profile_folder">profile directory</a>.<br />
On Linux, it will often be <code>~/.mozilla/firefox/*/</code>.<br />
I'll call this <code>PROFILE_DIRECTORY</code> from here on out.</p>
<p>Next, use the following commands to create the proxy extension file for<br />
RequestPolicy in your new profile.</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># Change directory to your new profile's directory.</span>
<span class="kw">cd</span> PROFILE_DIRECTORY
<span class="co"># Create the 'extensions' directory and change to that directory.</span>
<span class="kw">mkdir</span> -p extensions
<span class="kw">cd</span> extensions
<span class="co"># Create a file called '[email protected]' with a single</span>
<span class="co"># line in the file which is the path to the 'src' directory.</span>
<span class="kw">echo</span> <span class="st">"/path/to/requestpolicy/src"</span> <span class="kw">></span> [email protected]</code></pre></div>
<p>Now start Firefox again using that profile. Firefox should now consider the<br />
extension installed. To verify this, go to Tools > Addons > Extensions. You<br />
should see RequestPolicy listed among the extensions.</p>
<h3 id="troubleshooting">Troubleshooting</h3>
<p>If RequestPolicy is not installed at this point, you may need to repeat the<br />
above steps to create the proxy extension file before trying again. This is<br />
because if Firefox sees a problem with your proxy extension file (e.g. it's<br />
named incorrectly or the path to the <code>src</code> directory in the file is<br />
incorrect), Firefox may delete the file.</p>
<p>Note that you shouldn't try to install the extension xpi in a profile where<br />
you've already created the proxy extension. To use an xpi that you've built,<br />
use a new profile.</p>
</body>
</html>