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