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