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