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