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