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