doc/webserver/developer-manual/index.html

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