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