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