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.38 2011/12/26
  26       17:05:40 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.19. 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#AEN217">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#S39">Use 'long' or 'short'
 224                 Instead of 'int'</a></dt>
 225
 226                 <dt>4.7.5. <a href="coding.html#S40">Don't mix size_t and
 227                 other types</a></dt>
 228
 229                 <dt>4.7.6. <a href="coding.html#S41">Declare each variable
 230                 and struct on its own line.</a></dt>
 231
 232                 <dt>4.7.7. <a href="coding.html#S42">Use malloc/zalloc
 233                 sparingly</a></dt>
 234
 235                 <dt>4.7.8. <a href="coding.html#S43">The Programmer Who Uses
 236                 'malloc' is Responsible for Ensuring 'free'</a></dt>
 237
 238                 <dt>4.7.9. <a href="coding.html#S44">Add loaders to the
 239                 `file_list' structure and in order</a></dt>
 240
 241                 <dt>4.7.10. <a href="coding.html#S45">"Uncertain" new code
 242                 and/or changes to existing code, use FIXME or XXX</a></dt>
 243               </dl>
 244             </dd>
 245
 246             <dt>4.8. <a href="coding.html#S46">Addendum: Template for files
 247             and function comment blocks:</a></dt>
 248           </dl>
 249         </dd>
 250
 251         <dt>5. <a href="testing.html">Testing Guidelines</a></dt>
 252
 253         <dd>
 254           <dl>
 255             <dt>5.1. <a href="testing.html#TESTING-PLAN">Testplan for
 256             releases</a></dt>
 257
 258             <dt>5.2. <a href="testing.html#TESTING-REPORT">Test
 259             reports</a></dt>
 260           </dl>
 261         </dd>
 262
 263         <dt>6. <a href="newrelease.html">Releasing a New Version</a></dt>
 264
 265         <dd>
 266           <dl>
 267             <dt>6.1. <a href="newrelease.html#VERSIONNUMBERS">Version
 268             numbers</a></dt>
 269
 270             <dt>6.2. <a href="newrelease.html#BEFORERELEASE">Before the
 271             Release: Freeze</a></dt>
 272
 273             <dt>6.3. <a href="newrelease.html#THERELEASE">Building and
 274             Releasing the Packages</a></dt>
 275
 276             <dd>
 277               <dl>
 278                 <dt>6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
 279                 Privoxy Packaging</a></dt>
 280
 281                 <dt>6.3.2. <a href=
 282                 "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a></dt>
 283
 284                 <dt>6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
 285                 Conectiva or Red Hat RPM</a></dt>
 286
 287                 <dt>6.3.4. <a href=
 288                 "newrelease.html#NEWRELEASE-OS2">OS/2</a></dt>
 289
 290                 <dt>6.3.5. <a href=
 291                 "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a></dt>
 292
 293                 <dt>6.3.6. <a href=
 294                 "newrelease.html#NEWRELEASE-WINDOWS">Windows</a></dt>
 295
 296                 <dt>6.3.7. <a href=
 297                 "newrelease.html#NEWRELEASE-DEBIAN">Debian</a></dt>
 298
 299                 <dt>6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
 300                 X</a></dt>
 301
 302                 <dt>6.3.9. <a href=
 303                 "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a></dt>
 304
 305                 <dt>6.3.10. <a href="newrelease.html#NEWRELEASE-HPUX">HP-UX
 306                 11</a></dt>
 307
 308                 <dt>6.3.11. <a href="newrelease.html#NEWRELEASE-AMIGA">Amiga
 309                 OS</a></dt>
 310
 311                 <dt>6.3.12. <a href=
 312                 "newrelease.html#NEWRELEASE-AIX">AIX</a></dt>
 313               </dl>
 314             </dd>
 315
 316             <dt>6.4. <a href="newrelease.html#RELEASING">Uploading and
 317             Releasing Your Package</a></dt>
 318
 319             <dt>6.5. <a href="newrelease.html#AFTERRELEASE">After the
 320             Release</a></dt>
 321           </dl>
 322         </dd>
 323
 324         <dt>7. <a href="webserver-update.html">Update the Webserver</a></dt>
 325
 326         <dt>8. <a href="contact.html">Contacting the developers, Bug
 327         Reporting and Feature Requests</a></dt>
 328
 329         <dd>
 330           <dl>
 331             <dt>8.1. <a href="contact.html#CONTACT-SUPPORT">Get
 332             Support</a></dt>
 333
 334             <dt>8.2. <a href="contact.html#REPORTING">Reporting
 335             Problems</a></dt>
 336
 337             <dd>
 338               <dl>
 339                 <dt>8.2.1. <a href="contact.html#CONTACT-ADS">Reporting Ads
 340                 or Other Configuration Problems</a></dt>
 341
 342                 <dt>8.2.2. <a href="contact.html#CONTACT-BUGS">Reporting
 343                 Bugs</a></dt>
 344               </dl>
 345             </dd>
 346
 347             <dt>8.3. <a href="contact.html#CONTACT-FEATURE">Request New
 348             Features</a></dt>
 349
 350             <dt>8.4. <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#AEN1231">License</a></dt>
 361
 362             <dt>9.2. <a href="copyright.html#AEN1247">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>