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