doc/webserver/developer-manual/index.html

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