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