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>