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