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, 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 2.7 2006/07/18 14:48:50 david__schmidt 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.4.
  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#CONTACT-BUGS"
 577 >Report Bugs</A
 578 ></DT
 579 ><DT
 580 >8.3. <A
 581 HREF="contact.html#CONTACT-FEATURE"
 582 >Request New Features</A
 583 ></DT
 584 ><DT
 585 >8.4. <A
 586 HREF="contact.html#CONTACT-ADS"
 587 >Report Ads or Other Actions-Related Problems</A
 588 ></DT
 589 ><DT
 590 >8.5. <A
 591 HREF="contact.html#CONTACT-OTHER"
 592 >Other</A
 593 ></DT
 594 ></DL
 595 ></DD
 596 ><DT
 597 >9. <A
 598 HREF="copyright.html"
 599 >Privoxy Copyright, License and History</A
 600 ></DT
 601 ><DD
 602 ><DL
 603 ><DT
 604 >9.1. <A
 605 HREF="copyright.html#AEN1161"
 606 >License</A
 607 ></DT
 608 ><DT
 609 >9.2. <A
 610 HREF="copyright.html#AEN1177"
 611 >History</A
 612 ></DT
 613 ></DL
 614 ></DD
 615 ><DT
 616 >10. <A
 617 HREF="seealso.html"
 618 >See also</A
 619 ></DT
 620 ></DL
 621 ></DIV
 622 ></DIV
 623 ><DIV
 624 CLASS="NAVFOOTER"
 625 ><HR
 626 ALIGN="LEFT"
 627 WIDTH="100%"><TABLE
 628 SUMMARY="Footer navigation table"
 629 WIDTH="100%"
 630 BORDER="0"
 631 CELLPADDING="0"
 632 CELLSPACING="0"
 633 ><TR
 634 ><TD
 635 WIDTH="33%"
 636 ALIGN="left"
 637 VALIGN="top"
 638 >&nbsp;</TD
 639 ><TD
 640 WIDTH="34%"
 641 ALIGN="center"
 642 VALIGN="top"
 643 >&nbsp;</TD
 644 ><TD
 645 WIDTH="33%"
 646 ALIGN="right"
 647 VALIGN="top"
 648 ><A
 649 HREF="introduction.html"
 650 ACCESSKEY="N"
 651 >Next</A
 652 ></TD
 653 ></TR
 654 ><TR
 655 ><TD
 656 WIDTH="33%"
 657 ALIGN="left"
 658 VALIGN="top"
 659 >&nbsp;</TD
 660 ><TD
 661 WIDTH="34%"
 662 ALIGN="center"
 663 VALIGN="top"
 664 >&nbsp;</TD
 665 ><TD
 666 WIDTH="33%"
 667 ALIGN="right"
 668 VALIGN="top"
 669 >Introduction</TD
 670 ></TR
 671 ></TABLE
 672 ></DIV
 673 ></BODY
 674 ></HTML
 675 >