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-2013 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.59 2016/01/17
  28       14:32:18 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.24. 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#AEN208">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
 259             <dt>5.2. <a href="testing.html#TESTING-REPORT">Test
 260             reports</a></dt>
 261           </dl>
 262         </dd>
 263
 264         <dt>6. <a href="newrelease.html">Releasing a New Version</a></dt>
 265
 266         <dd>
 267           <dl>
 268             <dt>6.1. <a href="newrelease.html#VERSIONNUMBERS">Version
 269             numbers</a></dt>
 270
 271             <dt>6.2. <a href="newrelease.html#BEFORERELEASE">Before the
 272             Release: Freeze</a></dt>
 273
 274             <dt>6.3. <a href="newrelease.html#THERELEASE">Building and
 275             Releasing the Packages</a></dt>
 276
 277             <dd>
 278               <dl>
 279                 <dt>6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
 280                 Privoxy Packaging</a></dt>
 281
 282                 <dt>6.3.2. <a href=
 283                 "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a></dt>
 284
 285                 <dt>6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
 286                 Conectiva or Red Hat RPM</a></dt>
 287
 288                 <dt>6.3.4. <a href=
 289                 "newrelease.html#NEWRELEASE-OS2">OS/2</a></dt>
 290
 291                 <dt>6.3.5. <a href=
 292                 "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a></dt>
 293
 294                 <dt>6.3.6. <a href=
 295                 "newrelease.html#NEWRELEASE-WINDOWS">Windows</a></dt>
 296
 297                 <dt>6.3.7. <a href=
 298                 "newrelease.html#NEWRELEASE-DEBIAN">Debian</a></dt>
 299
 300                 <dt>6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
 301                 X</a></dt>
 302
 303                 <dt>6.3.9. <a href=
 304                 "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a></dt>
 305
 306                 <dt>6.3.10. <a href="newrelease.html#NEWRELEASE-HPUX">HP-UX
 307                 11</a></dt>
 308
 309                 <dt>6.3.11. <a href="newrelease.html#NEWRELEASE-AMIGA">Amiga
 310                 OS</a></dt>
 311
 312                 <dt>6.3.12. <a href=
 313                 "newrelease.html#NEWRELEASE-AIX">AIX</a></dt>
 314               </dl>
 315             </dd>
 316
 317             <dt>6.4. <a href="newrelease.html#RELEASING">Uploading and
 318             Releasing Your Package</a></dt>
 319
 320             <dt>6.5. <a href="newrelease.html#AFTERRELEASE">After the
 321             Release</a></dt>
 322           </dl>
 323         </dd>
 324
 325         <dt>7. <a href="webserver-update.html">Update the Webserver</a></dt>
 326       </dl>
 327     </div>
 328   </div>
 329
 330   <div class="NAVFOOTER">
 331     <hr align="left" width="100%">
 332
 333     <table summary="Footer navigation table" width="100%" border="0"
 334     cellpadding="0" cellspacing="0">
 335       <tr>
 336         <td width="33%" align="left" valign="top">&nbsp;</td>
 337
 338         <td width="34%" align="center" valign="top">&nbsp;</td>
 339
 340         <td width="33%" align="right" valign="top"><a href=
 341         "introduction.html" accesskey="N">Next</a></td>
 342       </tr>
 343
 344       <tr>
 345         <td width="33%" align="left" valign="top">&nbsp;</td>
 346
 347         <td width="34%" align="center" valign="top">&nbsp;</td>
 348
 349         <td width="33%" align="right" valign="top">Introduction</td>
 350       </tr>
 351     </table>
 352   </div>
 353 </body>
 354 </html>