doc/webserver/developer-manual/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Privoxy Developer Manual</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
   9 REL="NEXT"
  10 TITLE="Introduction"
  11 HREF="introduction.html"><LINK
  12 REL="STYLESHEET"
  13 TYPE="text/css"
  14 HREF="../p_doc.css"><META
  15 HTTP-EQUIV="Content-Type"
  16 CONTENT="text/html;
  17 charset=ISO-8859-1"></HEAD
  18 ><BODY
  19 CLASS="ARTICLE"
  20 BGCOLOR="#EEEEEE"
  21 TEXT="#000000"
  22 LINK="#0000FF"
  23 VLINK="#840084"
  24 ALINK="#0000FF"
  25 ><DIV
  26 CLASS="ARTICLE"
  27 ><DIV
  28 CLASS="TITLEPAGE"
  29 ><H1
  30 CLASS="TITLE"
  31 ><A
  32 NAME="AEN2"
  33 >Privoxy Developer Manual</A
  34 ></H1
  35 ><P
  36 CLASS="PUBDATE"
  37 >     <SUB
  38 >
  39
  40       <A
  41 HREF="https://www.privoxy.org/user-manual/copyright.html"
  42 TARGET="_top"
  43 >Copyright</A
  44 >
  45       © 2001-2016 by
  46       <A
  47 HREF="https://www.privoxy.org/"
  48 TARGET="_top"
  49 >Privoxy Developers</A
  50 >
  51      </SUB
  52 >
  53     <BR></P
  54 ><P
  55 CLASS="PUBDATE"
  56 >$Id: developer-manual.sgml,v 2.83 2017/06/08 13:08:39 fabiankeil Exp $<BR></P
  57 ><DIV
  58 ><DIV
  59 CLASS="ABSTRACT"
  60 ><P
  61 ></P
  62 ><A
  63 NAME="AEN9"
  64 ></A
  65 ><P
  66 > The developer manual provides guidance on coding, testing, packaging, documentation
  67  and other issues of importance to those involved with
  68  <SPAN
  69 CLASS="APPLICATION"
  70 >Privoxy</SPAN
  71 > development. It is mandatory (and helpful!) reading
  72  for anyone who wants to join the team. Note that it's currently out of date
  73  and may not be entirely correct. As always, patches are welcome.</P
  74 ><P
  75 > Please note that this document is constantly evolving. This copy represents
  76  the state at the release of version 3.0.27.
  77  You can find the latest version of the this manual at <A
  78 HREF="https://www.privoxy.org/developer-manual/"
  79 TARGET="_top"
  80 >https://www.privoxy.org/developer-manual/</A
  81 >.
  82  Please have a look at the
  83  <A
  84 HREF="https://www.privoxy.org/user-manual/contact.html"
  85 TARGET="_top"
  86 >contact section in the user manual</A
  87 >
  88  if you are interested in contacting the developers.</P
  89 ><P
  90 ></P
  91 ></DIV
  92 ></DIV
  93 ><HR></DIV
  94 ><DIV
  95 CLASS="TOC"
  96 ><DL
  97 ><DT
  98 ><B
  99 >Table of Contents</B
 100 ></DT
 101 ><DT
 102 >1. <A
 103 HREF="introduction.html"
 104 >Introduction</A
 105 ></DT
 106 ><DD
 107 ><DL
 108 ><DT
 109 >1.1. <A
 110 HREF="introduction.html#QUICKSTART"
 111 >Quickstart to Privoxy Development</A
 112 ></DT
 113 ></DL
 114 ></DD
 115 ><DT
 116 >2. <A
 117 HREF="cvs.html"
 118 >The CVS Repository</A
 119 ></DT
 120 ><DD
 121 ><DL
 122 ><DT
 123 >2.1. <A
 124 HREF="cvs.html#CVSACCESS"
 125 >Access to CVS</A
 126 ></DT
 127 ><DT
 128 >2.2. <A
 129 HREF="cvs.html#CVSBRANCHES"
 130 >Branches</A
 131 ></DT
 132 ><DT
 133 >2.3. <A
 134 HREF="cvs.html#CVSCOMMIT"
 135 >CVS Commit Guidelines</A
 136 ></DT
 137 ></DL
 138 ></DD
 139 ><DT
 140 >3. <A
 141 HREF="documentation.html"
 142 >Documentation Guidelines</A
 143 ></DT
 144 ><DD
 145 ><DL
 146 ><DT
 147 >3.1. <A
 148 HREF="documentation.html#SGML"
 149 >Quickstart to Docbook and SGML</A
 150 ></DT
 151 ><DT
 152 >3.2. <A
 153 HREF="documentation.html#DOCSTYLE"
 154 ><SPAN
 155 CLASS="APPLICATION"
 156 >Privoxy</SPAN
 157 > Documentation Style</A
 158 ></DT
 159 ><DT
 160 >3.3. <A
 161 HREF="documentation.html#AEN206"
 162 >Privoxy Custom Entities</A
 163 ></DT
 164 ></DL
 165 ></DD
 166 ><DT
 167 >4. <A
 168 HREF="coding.html"
 169 >Coding Guidelines</A
 170 ></DT
 171 ><DD
 172 ><DL
 173 ><DT
 174 >4.1. <A
 175 HREF="coding.html#S1"
 176 >Introduction</A
 177 ></DT
 178 ><DT
 179 >4.2. <A
 180 HREF="coding.html#S2"
 181 >Using Comments</A
 182 ></DT
 183 ><DD
 184 ><DL
 185 ><DT
 186 >4.2.1. <A
 187 HREF="coding.html#S3"
 188 >Comment, Comment, Comment</A
 189 ></DT
 190 ><DT
 191 >4.2.2. <A
 192 HREF="coding.html#S4"
 193 >Use blocks for comments</A
 194 ></DT
 195 ><DT
 196 >4.2.3. <A
 197 HREF="coding.html#S5"
 198 >Keep Comments on their own line</A
 199 ></DT
 200 ><DT
 201 >4.2.4. <A
 202 HREF="coding.html#S6"
 203 >Comment each logical step</A
 204 ></DT
 205 ><DT
 206 >4.2.5. <A
 207 HREF="coding.html#S7"
 208 >Comment All Functions Thoroughly</A
 209 ></DT
 210 ><DT
 211 >4.2.6. <A
 212 HREF="coding.html#S8"
 213 >Comment at the end of braces if the
 214     content is more than one screen length</A
 215 ></DT
 216 ></DL
 217 ></DD
 218 ><DT
 219 >4.3. <A
 220 HREF="coding.html#S9"
 221 >Naming Conventions</A
 222 ></DT
 223 ><DD
 224 ><DL
 225 ><DT
 226 >4.3.1. <A
 227 HREF="coding.html#S10"
 228 >Variable Names</A
 229 ></DT
 230 ><DT
 231 >4.3.2. <A
 232 HREF="coding.html#S11"
 233 >Function Names</A
 234 ></DT
 235 ><DT
 236 >4.3.3. <A
 237 HREF="coding.html#S12"
 238 >Header file prototypes</A
 239 ></DT
 240 ><DT
 241 >4.3.4. <A
 242 HREF="coding.html#S13"
 243 >Enumerations, and #defines</A
 244 ></DT
 245 ><DT
 246 >4.3.5. <A
 247 HREF="coding.html#S14"
 248 >Constants</A
 249 ></DT
 250 ></DL
 251 ></DD
 252 ><DT
 253 >4.4. <A
 254 HREF="coding.html#S15"
 255 >Using Space</A
 256 ></DT
 257 ><DD
 258 ><DL
 259 ><DT
 260 >4.4.1. <A
 261 HREF="coding.html#S16"
 262 >Put braces on a line by themselves.</A
 263 ></DT
 264 ><DT
 265 >4.4.2. <A
 266 HREF="coding.html#S17"
 267 >ALL control statements should have a
 268     block</A
 269 ></DT
 270 ><DT
 271 >4.4.3. <A
 272 HREF="coding.html#S18"
 273 >Do not belabor/blow-up boolean
 274     expressions</A
 275 ></DT
 276 ><DT
 277 >4.4.4. <A
 278 HREF="coding.html#S19"
 279 >Use white space freely because it is
 280     free</A
 281 ></DT
 282 ><DT
 283 >4.4.5. <A
 284 HREF="coding.html#S20"
 285 >Don't use white space around structure
 286     operators</A
 287 ></DT
 288 ><DT
 289 >4.4.6. <A
 290 HREF="coding.html#S21"
 291 >Make the last brace of a function stand
 292     out</A
 293 ></DT
 294 ><DT
 295 >4.4.7. <A
 296 HREF="coding.html#S22"
 297 >Use 3 character indentions</A
 298 ></DT
 299 ></DL
 300 ></DD
 301 ><DT
 302 >4.5. <A
 303 HREF="coding.html#S23"
 304 >Initializing</A
 305 ></DT
 306 ><DD
 307 ><DL
 308 ><DT
 309 >4.5.1. <A
 310 HREF="coding.html#S24"
 311 >Initialize all variables</A
 312 ></DT
 313 ></DL
 314 ></DD
 315 ><DT
 316 >4.6. <A
 317 HREF="coding.html#S25"
 318 >Functions</A
 319 ></DT
 320 ><DD
 321 ><DL
 322 ><DT
 323 >4.6.1. <A
 324 HREF="coding.html#S26"
 325 >Name functions that return a boolean as a
 326     question.</A
 327 ></DT
 328 ><DT
 329 >4.6.2. <A
 330 HREF="coding.html#S27"
 331 >Always specify a return type for a
 332     function.</A
 333 ></DT
 334 ><DT
 335 >4.6.3. <A
 336 HREF="coding.html#S28"
 337 >Minimize function calls when iterating by
 338     using variables</A
 339 ></DT
 340 ><DT
 341 >4.6.4. <A
 342 HREF="coding.html#S29"
 343 >Pass and Return by Const Reference</A
 344 ></DT
 345 ><DT
 346 >4.6.5. <A
 347 HREF="coding.html#S30"
 348 >Pass and Return by Value</A
 349 ></DT
 350 ><DT
 351 >4.6.6. <A
 352 HREF="coding.html#S31"
 353 >Names of include files</A
 354 ></DT
 355 ><DT
 356 >4.6.7. <A
 357 HREF="coding.html#S32"
 358 >Provide multiple inclusion
 359     protection</A
 360 ></DT
 361 ><DT
 362 >4.6.8. <A
 363 HREF="coding.html#S33"
 364 >Use `extern "C"` when appropriate</A
 365 ></DT
 366 ><DT
 367 >4.6.9. <A
 368 HREF="coding.html#S34"
 369 >Where Possible, Use Forward Struct
 370     Declaration Instead of Includes</A
 371 ></DT
 372 ></DL
 373 ></DD
 374 ><DT
 375 >4.7. <A
 376 HREF="coding.html#S35"
 377 >General Coding Practices</A
 378 ></DT
 379 ><DD
 380 ><DL
 381 ><DT
 382 >4.7.1. <A
 383 HREF="coding.html#S36"
 384 >Turn on warnings</A
 385 ></DT
 386 ><DT
 387 >4.7.2. <A
 388 HREF="coding.html#S37"
 389 >Provide a default case for all switch
 390     statements</A
 391 ></DT
 392 ><DT
 393 >4.7.3. <A
 394 HREF="coding.html#S38"
 395 >Try to avoid falling through cases in a
 396     switch statement.</A
 397 ></DT
 398 ><DT
 399 >4.7.4. <A
 400 HREF="coding.html#S40"
 401 >Don't mix size_t and other types</A
 402 ></DT
 403 ><DT
 404 >4.7.5. <A
 405 HREF="coding.html#S41"
 406 >Declare each variable and struct on its
 407     own line.</A
 408 ></DT
 409 ><DT
 410 >4.7.6. <A
 411 HREF="coding.html#S42"
 412 >Use malloc/zalloc sparingly</A
 413 ></DT
 414 ><DT
 415 >4.7.7. <A
 416 HREF="coding.html#S43"
 417 >The Programmer Who Uses 'malloc' is
 418     Responsible for Ensuring 'free'</A
 419 ></DT
 420 ><DT
 421 >4.7.8. <A
 422 HREF="coding.html#S44"
 423 >Add loaders to the `file_list' structure
 424     and in order</A
 425 ></DT
 426 ><DT
 427 >4.7.9. <A
 428 HREF="coding.html#S45"
 429 >"Uncertain" new code and/or changes to
 430     existing code, use XXX</A
 431 ></DT
 432 ></DL
 433 ></DD
 434 ><DT
 435 >4.8. <A
 436 HREF="coding.html#S46"
 437 >Addendum: Template for files and function
 438     comment blocks:</A
 439 ></DT
 440 ></DL
 441 ></DD
 442 ><DT
 443 >5. <A
 444 HREF="testing.html"
 445 >Testing Guidelines</A
 446 ></DT
 447 ><DD
 448 ><DL
 449 ><DT
 450 >5.1. <A
 451 HREF="testing.html#TESTING-PLAN"
 452 >Testplan for releases</A
 453 ></DT
 454 ><DT
 455 >5.2. <A
 456 HREF="testing.html#FUZZING"
 457 >Fuzzing Privoxy</A
 458 ></DT
 459 ></DL
 460 ></DD
 461 ><DT
 462 >6. <A
 463 HREF="newrelease.html"
 464 >Releasing a New Version</A
 465 ></DT
 466 ><DD
 467 ><DL
 468 ><DT
 469 >6.1. <A
 470 HREF="newrelease.html#VERSIONNUMBERS"
 471 >Version numbers</A
 472 ></DT
 473 ><DT
 474 >6.2. <A
 475 HREF="newrelease.html#BEFORERELEASE"
 476 >Before the Release: Freeze</A
 477 ></DT
 478 ><DT
 479 >6.3. <A
 480 HREF="newrelease.html#THERELEASE"
 481 >Building and Releasing the Packages</A
 482 ></DT
 483 ><DD
 484 ><DL
 485 ><DT
 486 >6.3.1. <A
 487 HREF="newrelease.html#PACK-GUIDELINES"
 488 >Note on Privoxy Packaging</A
 489 ></DT
 490 ><DT
 491 >6.3.2. <A
 492 HREF="newrelease.html#NEWRELEASE-TARBALL"
 493 >Source Tarball</A
 494 ></DT
 495 ><DT
 496 >6.3.3. <A
 497 HREF="newrelease.html#NEWRELEASE-RPM"
 498 >SuSE, Conectiva or Red Hat RPM</A
 499 ></DT
 500 ><DT
 501 >6.3.4. <A
 502 HREF="newrelease.html#NEWRELEASE-OS2"
 503 >OS/2</A
 504 ></DT
 505 ><DT
 506 >6.3.5. <A
 507 HREF="newrelease.html#NEWRELEASE-SOLARIS"
 508 >Solaris</A
 509 ></DT
 510 ><DT
 511 >6.3.6. <A
 512 HREF="newrelease.html#NEWRELEASE-WINDOWS"
 513 >Windows</A
 514 ></DT
 515 ><DT
 516 >6.3.7. <A
 517 HREF="newrelease.html#NEWRELEASE-DEBIAN"
 518 >Debian</A
 519 ></DT
 520 ><DT
 521 >6.3.8. <A
 522 HREF="newrelease.html#NEWRELEASE-MACOSX"
 523 >Mac OS X</A
 524 ></DT
 525 ><DT
 526 >6.3.9. <A
 527 HREF="newrelease.html#NEWRELEASE-FREEBSD"
 528 >FreeBSD</A
 529 ></DT
 530 ></DL
 531 ></DD
 532 ><DT
 533 >6.4. <A
 534 HREF="newrelease.html#RELEASING"
 535 >Uploading and Releasing Your Package</A
 536 ></DT
 537 ><DT
 538 >6.5. <A
 539 HREF="newrelease.html#AFTERRELEASE"
 540 >After the Release</A
 541 ></DT
 542 ></DL
 543 ></DD
 544 ><DT
 545 >7. <A
 546 HREF="webserver-update.html"
 547 >Update the Webserver</A
 548 ></DT
 549 ></DL
 550 ></DIV
 551 ></DIV
 552 ><DIV
 553 CLASS="NAVFOOTER"
 554 ><HR
 555 ALIGN="LEFT"
 556 WIDTH="100%"><TABLE
 557 SUMMARY="Footer navigation table"
 558 WIDTH="100%"
 559 BORDER="0"
 560 CELLPADDING="0"
 561 CELLSPACING="0"
 562 ><TR
 563 ><TD
 564 WIDTH="33%"
 565 ALIGN="left"
 566 VALIGN="top"
 567 >&nbsp;</TD
 568 ><TD
 569 WIDTH="34%"
 570 ALIGN="center"
 571 VALIGN="top"
 572 >&nbsp;</TD
 573 ><TD
 574 WIDTH="33%"
 575 ALIGN="right"
 576 VALIGN="top"
 577 ><A
 578 HREF="introduction.html"
 579 ACCESSKEY="N"
 580 >Next</A
 581 ></TD
 582 ></TR
 583 ><TR
 584 ><TD
 585 WIDTH="33%"
 586 ALIGN="left"
 587 VALIGN="top"
 588 >&nbsp;</TD
 589 ><TD
 590 WIDTH="34%"
 591 ALIGN="center"
 592 VALIGN="top"
 593 >&nbsp;</TD
 594 ><TD
 595 WIDTH="33%"
 596 ALIGN="right"
 597 VALIGN="top"
 598 >Introduction</TD
 599 ></TR
 600 ></TABLE
 601 ></DIV
 602 ></BODY
 603 ></HTML
 604 >