20c78b021a86ba322d25ff67e88746a5202c8347
[privoxy.git] / doc / webserver / developer-manual / index.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
3
4 <html>
5 <head>
6   <title>Privoxy Developer Manual</title>
7   <meta name="GENERATOR" content=
8   "Modular DocBook HTML Stylesheet Version 1.79">
9   <link rel="NEXT" title="Introduction" href="introduction.html">
10   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
11   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
12 </head>
13
14 <body class="ARTICLE" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
15 "#840084" alink="#0000FF">
16   <div class="ARTICLE">
17     <div class="TITLEPAGE">
18       <h1 class="TITLE"><a name="AEN2" id="AEN2">Privoxy Developer
19       Manual</a></h1>
20
21       <p class="PUBDATE"><sub><a href=
22       "http://www.privoxy.org/user-manual/copyright.html" target=
23       "_top">Copyright</a> &copy; 2001-2016 by <a href=
24       "http://www.privoxy.org/" target="_top">Privoxy
25       Developers</a></sub><br></p>
26
27       <p class="PUBDATE">$Id: developer-manual.sgml,v 2.67 2016/02/26
28       12:27:32 fabiankeil Exp $<br></p>
29
30       <div>
31         <div class="ABSTRACT">
32           <a name="AEN9" id="AEN9"></a>
33
34           <p>The developer manual provides guidance on coding, testing,
35           packaging, documentation and other issues of importance to those
36           involved with <span class="APPLICATION">Privoxy</span> development.
37           It is mandatory (and helpful!) reading for anyone who wants to join
38           the team. Note that it's currently out of date and may not be
39           entirely correct. As always, patches are welcome.</p>
40
41           <p>Please note that this document is constantly evolving. This copy
42           represents the state at the release of version 3.0.25. You can find
43           the latest version of the this manual at <a href=
44           "http://www.privoxy.org/developer-manual/" target=
45           "_top">http://www.privoxy.org/developer-manual/</a>. Please have a
46           look at the <a href=
47           "http://www.privoxy.org/user-manual/contact.html" target=
48           "_top">contact section in the user manual</a> if you are interested
49           in contacting the developers.</p>
50         </div>
51       </div>
52       <hr>
53     </div>
54
55     <div class="TOC">
56       <dl>
57         <dt><b>Table of Contents</b></dt>
58
59         <dt>1. <a href="introduction.html">Introduction</a></dt>
60
61         <dd>
62           <dl>
63             <dt>1.1. <a href="introduction.html#QUICKSTART">Quickstart to
64             Privoxy Development</a></dt>
65           </dl>
66         </dd>
67
68         <dt>2. <a href="cvs.html">The CVS Repository</a></dt>
69
70         <dd>
71           <dl>
72             <dt>2.1. <a href="cvs.html#CVSACCESS">Access to CVS</a></dt>
73
74             <dt>2.2. <a href="cvs.html#CVSBRANCHES">Branches</a></dt>
75
76             <dt>2.3. <a href="cvs.html#CVSCOMMIT">CVS Commit
77             Guidelines</a></dt>
78           </dl>
79         </dd>
80
81         <dt>3. <a href="documentation.html">Documentation Guidelines</a></dt>
82
83         <dd>
84           <dl>
85             <dt>3.1. <a href="documentation.html#SGML">Quickstart to Docbook
86             and SGML</a></dt>
87
88             <dt>3.2. <a href="documentation.html#DOCSTYLE"><span class=
89             "APPLICATION">Privoxy</span> Documentation Style</a></dt>
90
91             <dt>3.3. <a href="documentation.html#AEN207">Privoxy Custom
92             Entities</a></dt>
93           </dl>
94         </dd>
95
96         <dt>4. <a href="coding.html">Coding Guidelines</a></dt>
97
98         <dd>
99           <dl>
100             <dt>4.1. <a href="coding.html#S1">Introduction</a></dt>
101
102             <dt>4.2. <a href="coding.html#S2">Using Comments</a></dt>
103
104             <dd>
105               <dl>
106                 <dt>4.2.1. <a href="coding.html#S3">Comment, Comment,
107                 Comment</a></dt>
108
109                 <dt>4.2.2. <a href="coding.html#S4">Use blocks for
110                 comments</a></dt>
111
112                 <dt>4.2.3. <a href="coding.html#S5">Keep Comments on their
113                 own line</a></dt>
114
115                 <dt>4.2.4. <a href="coding.html#S6">Comment each logical
116                 step</a></dt>
117
118                 <dt>4.2.5. <a href="coding.html#S7">Comment All Functions
119                 Thoroughly</a></dt>
120
121                 <dt>4.2.6. <a href="coding.html#S8">Comment at the end of
122                 braces if the content is more than one screen length</a></dt>
123               </dl>
124             </dd>
125
126             <dt>4.3. <a href="coding.html#S9">Naming Conventions</a></dt>
127
128             <dd>
129               <dl>
130                 <dt>4.3.1. <a href="coding.html#S10">Variable Names</a></dt>
131
132                 <dt>4.3.2. <a href="coding.html#S11">Function Names</a></dt>
133
134                 <dt>4.3.3. <a href="coding.html#S12">Header file
135                 prototypes</a></dt>
136
137                 <dt>4.3.4. <a href="coding.html#S13">Enumerations, and
138                 #defines</a></dt>
139
140                 <dt>4.3.5. <a href="coding.html#S14">Constants</a></dt>
141               </dl>
142             </dd>
143
144             <dt>4.4. <a href="coding.html#S15">Using Space</a></dt>
145
146             <dd>
147               <dl>
148                 <dt>4.4.1. <a href="coding.html#S16">Put braces on a line by
149                 themselves.</a></dt>
150
151                 <dt>4.4.2. <a href="coding.html#S17">ALL control statements
152                 should have a block</a></dt>
153
154                 <dt>4.4.3. <a href="coding.html#S18">Do not belabor/blow-up
155                 boolean expressions</a></dt>
156
157                 <dt>4.4.4. <a href="coding.html#S19">Use white space freely
158                 because it is free</a></dt>
159
160                 <dt>4.4.5. <a href="coding.html#S20">Don't use white space
161                 around structure operators</a></dt>
162
163                 <dt>4.4.6. <a href="coding.html#S21">Make the last brace of a
164                 function stand out</a></dt>
165
166                 <dt>4.4.7. <a href="coding.html#S22">Use 3 character
167                 indentions</a></dt>
168               </dl>
169             </dd>
170
171             <dt>4.5. <a href="coding.html#S23">Initializing</a></dt>
172
173             <dd>
174               <dl>
175                 <dt>4.5.1. <a href="coding.html#S24">Initialize all
176                 variables</a></dt>
177               </dl>
178             </dd>
179
180             <dt>4.6. <a href="coding.html#S25">Functions</a></dt>
181
182             <dd>
183               <dl>
184                 <dt>4.6.1. <a href="coding.html#S26">Name functions that
185                 return a boolean as a question.</a></dt>
186
187                 <dt>4.6.2. <a href="coding.html#S27">Always specify a return
188                 type for a function.</a></dt>
189
190                 <dt>4.6.3. <a href="coding.html#S28">Minimize function calls
191                 when iterating by using variables</a></dt>
192
193                 <dt>4.6.4. <a href="coding.html#S29">Pass and Return by Const
194                 Reference</a></dt>
195
196                 <dt>4.6.5. <a href="coding.html#S30">Pass and Return by
197                 Value</a></dt>
198
199                 <dt>4.6.6. <a href="coding.html#S31">Names of include
200                 files</a></dt>
201
202                 <dt>4.6.7. <a href="coding.html#S32">Provide multiple
203                 inclusion protection</a></dt>
204
205                 <dt>4.6.8. <a href="coding.html#S33">Use `extern "C"` when
206                 appropriate</a></dt>
207
208                 <dt>4.6.9. <a href="coding.html#S34">Where Possible, Use
209                 Forward Struct Declaration Instead of Includes</a></dt>
210               </dl>
211             </dd>
212
213             <dt>4.7. <a href="coding.html#S35">General Coding
214             Practices</a></dt>
215
216             <dd>
217               <dl>
218                 <dt>4.7.1. <a href="coding.html#S36">Turn on
219                 warnings</a></dt>
220
221                 <dt>4.7.2. <a href="coding.html#S37">Provide a default case
222                 for all switch statements</a></dt>
223
224                 <dt>4.7.3. <a href="coding.html#S38">Try to avoid falling
225                 through cases in a switch statement.</a></dt>
226
227                 <dt>4.7.4. <a href="coding.html#S40">Don't mix size_t and
228                 other types</a></dt>
229
230                 <dt>4.7.5. <a href="coding.html#S41">Declare each variable
231                 and struct on its own line.</a></dt>
232
233                 <dt>4.7.6. <a href="coding.html#S42">Use malloc/zalloc
234                 sparingly</a></dt>
235
236                 <dt>4.7.7. <a href="coding.html#S43">The Programmer Who Uses
237                 'malloc' is Responsible for Ensuring 'free'</a></dt>
238
239                 <dt>4.7.8. <a href="coding.html#S44">Add loaders to the
240                 `file_list' structure and in order</a></dt>
241
242                 <dt>4.7.9. <a href="coding.html#S45">"Uncertain" new code
243                 and/or changes to existing code, use XXX</a></dt>
244               </dl>
245             </dd>
246
247             <dt>4.8. <a href="coding.html#S46">Addendum: Template for files
248             and function comment blocks:</a></dt>
249           </dl>
250         </dd>
251
252         <dt>5. <a href="testing.html">Testing Guidelines</a></dt>
253
254         <dd>
255           <dl>
256             <dt>5.1. <a href="testing.html#TESTING-PLAN">Testplan for
257             releases</a></dt>
258           </dl>
259         </dd>
260
261         <dt>6. <a href="newrelease.html">Releasing a New Version</a></dt>
262
263         <dd>
264           <dl>
265             <dt>6.1. <a href="newrelease.html#VERSIONNUMBERS">Version
266             numbers</a></dt>
267
268             <dt>6.2. <a href="newrelease.html#BEFORERELEASE">Before the
269             Release: Freeze</a></dt>
270
271             <dt>6.3. <a href="newrelease.html#THERELEASE">Building and
272             Releasing the Packages</a></dt>
273
274             <dd>
275               <dl>
276                 <dt>6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
277                 Privoxy Packaging</a></dt>
278
279                 <dt>6.3.2. <a href=
280                 "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a></dt>
281
282                 <dt>6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
283                 Conectiva or Red Hat RPM</a></dt>
284
285                 <dt>6.3.4. <a href=
286                 "newrelease.html#NEWRELEASE-OS2">OS/2</a></dt>
287
288                 <dt>6.3.5. <a href=
289                 "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a></dt>
290
291                 <dt>6.3.6. <a href=
292                 "newrelease.html#NEWRELEASE-WINDOWS">Windows</a></dt>
293
294                 <dt>6.3.7. <a href=
295                 "newrelease.html#NEWRELEASE-DEBIAN">Debian</a></dt>
296
297                 <dt>6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
298                 X</a></dt>
299
300                 <dt>6.3.9. <a href=
301                 "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a></dt>
302               </dl>
303             </dd>
304
305             <dt>6.4. <a href="newrelease.html#RELEASING">Uploading and
306             Releasing Your Package</a></dt>
307
308             <dt>6.5. <a href="newrelease.html#AFTERRELEASE">After the
309             Release</a></dt>
310           </dl>
311         </dd>
312
313         <dt>7. <a href="webserver-update.html">Update the Webserver</a></dt>
314       </dl>
315     </div>
316   </div>
317
318   <div class="NAVFOOTER">
319     <hr align="left" width="100%">
320
321     <table summary="Footer navigation table" width="100%" border="0"
322     cellpadding="0" cellspacing="0">
323       <tr>
324         <td width="33%" align="left" valign="top">&nbsp;</td>
325
326         <td width="34%" align="center" valign="top">&nbsp;</td>
327
328         <td width="33%" align="right" valign="top"><a href=
329         "introduction.html" accesskey="N">Next</a></td>
330       </tr>
331
332       <tr>
333         <td width="33%" align="left" valign="top">&nbsp;</td>
334
335         <td width="34%" align="center" valign="top">&nbsp;</td>
336
337         <td width="33%" align="right" valign="top">Introduction</td>
338       </tr>
339     </table>
340   </div>
341 </body>
342 </html>