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