doc/text/developer-manual.txt

   1 Privoxy Developer Manual
   2
   3 By: Privoxy Developers
   4
   5 $Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $
   6
   7 The developer manual gives the users information on how to help the developer
   8 team. It provides guidance on coding, testing, documentation and other issues.
   9
  10 Privoxy is a web proxy with advanced filtering capabilities for protecting
  11 privacy, filtering web page content, managing cookies, controlling access, and
  12 removing ads, banners, pop-ups and other obnoxious Internet junk. Privoxy has a
  13 very flexible configuration and can be customized to suit individual needs and
  14 tastes. Privoxy has application for both stand-alone systems and multi-user
  15 networks.
  16
  17 Privoxy is based on the code of the Internet Junkbuster (tm). Junkbuster was
  18 originally written by Junkbusters Corporation, and was released as free
  19 open-source software under the GNU GPL. Stefan Waldherr made many improvements,
  20 and started the SourceForge project to continue development.
  21
  22 Privoxy continues the Junkbuster tradition, but adds many refinements,
  23 enhancements and new features.
  24
  25 You can find the latest version of the this manual at http://www.privoxy.org/
  26 developer-manual/. Please see the Contact section on how to contact the
  27 developers.
  28
  29 -------------------------------------------------------------------------------
  30
  31 Table of Contents
  32
  33 1. Introduction
  34 3. Quickstart to Privoxy Development
  35 4. Documentation Guidelines
  36
  37     4.1. Quickstart to Docbook and SGML
  38     4.2. Privoxy Documentation Style
  39     4.3. Privoxy Custom Entities
  40
  41 5. Coding Guidelines
  42
  43     5.1. Introduction
  44     5.2. Using Comments
  45
  46         5.2.1. Comment, Comment, Comment
  47         5.2.2. Use blocks for comments
  48         5.2.3. Keep Comments on their own line
  49         5.2.4. Comment each logical step
  50         5.2.5. Comment All Functions Thoroughly
  51         5.2.6. Comment at the end of braces if the content is more than one
  52             screen length
  53
  54     5.3. Naming Conventions
  55
  56         5.3.1. Variable Names
  57         5.3.2. Function Names
  58         5.3.3. Header file prototypes
  59         5.3.4. Enumerations, and #defines
  60         5.3.5. Constants
  61
  62     5.4. Using Space
  63
  64         5.4.1. Put braces on a line by themselves.
  65         5.4.2. ALL control statements should have a block
  66         5.4.3. Do not belabor/blow-up boolean expressions
  67         5.4.4. Use white space freely because it is free
  68         5.4.5. Don't use white space around structure operators
  69         5.4.6. Make the last brace of a function stand out
  70         5.4.7. Use 3 character indentions
  71
  72     5.5. Initializing
  73
  74         5.5.1. Initialize all variables
  75
  76     5.6. Functions
  77
  78         5.6.1. Name functions that return a boolean as a question.
  79         5.6.2. Always specify a return type for a function.
  80         5.6.3. Minimize function calls when iterating by using variables
  81         5.6.4. Pass and Return by Const Reference
  82         5.6.5. Pass and Return by Value
  83         5.6.6. Names of include files
  84         5.6.7. Provide multiple inclusion protection
  85         5.6.8. Use `extern "C"` when appropriate
  86         5.6.9. Where Possible, Use Forward Struct Declaration Instead of
  87             Includes
  88
  89     5.7. General Coding Practices
  90
  91         5.7.1. Turn on warnings
  92         5.7.2. Provide a default case for all switch statements
  93         5.7.3. Try to avoid falling through cases in a switch statement.
  94         5.7.4. Use 'long' or 'short' Instead of 'int'
  95         5.7.5. Don't mix size_t and other types
  96         5.7.6. Declare each variable and struct on its own line.
  97         5.7.7. Use malloc/zalloc sparingly
  98         5.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
  99             'free'
 100         5.7.9. Add loaders to the `file_list' structure and in order
 101         5.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
 102
 103     5.8. Addendum: Template for files and function comment blocks:
 104
 105 6. Version Control Guidelines
 106 7. Testing Guidelines
 107
 108     7.1. Testplan for releases
 109     7.2. Test reports
 110
 111 8. Releasing a new version
 112
 113     8.1. Before the Release
 114     8.2. Update the webserver
 115     8.3. SuSE or Red Hat
 116     8.4. OS/2
 117     8.5. Solaris
 118     8.6. Windows
 119     8.7. Debian
 120     8.8. Mac OSX
 121     8.9. FreeBSD
 122     8.10. Tarball
 123     8.11. HP-UX 11
 124     8.12. Amiga OS
 125     8.13. AIX
 126
 127 9. Contacting the developers, Bug Reporting and Feature Requests
 128 10. Copyright and History
 129
 130     10.1. Copyright
 131     10.2. History
 132
 133 11. See also
 134
 135 -------------------------------------------------------------------------------
 136
 137 1. Introduction
 138
 139 Privoxy, as an heir to Junkbuster, is an Open Source project and licensed under
 140 the GPL. As such, Privoxy development is potentially open to anyone who has the
 141 time, knowledge, and desire to contribute in any capacity. Our goals are simply
 142 to continue the mission, to improve Privoxy, and to make it available to as
 143 wide an audience as possible.
 144
 145 One does not have to be a programmer to contribute. Packaging, testing, and
 146 porting, are all important jobs as well.
 147
 148 -------------------------------------------------------------------------------
 149
 150 3. Quickstart to Privoxy Development
 151
 152 You'll need an account on Sourceforge to support our development. Mail your ID
 153 to the list and wait until a project manager has added you.
 154
 155 For the time being (read, this section is under construction), please note the
 156 following guidelines for changing stuff in the code. If it is
 157
 158  1. A bugfix / clean-up / cosmetic thing: shoot
 159
 160  2. A new feature that can be turned off: shoot
 161
 162  3. A clear improvement w/o side effects on other parts of the code: shoot
 163
 164  4. A matter of taste: ask the list
 165
 166  5. A major redesign of some part of the code: ask the list
 167
 168 Note that near a major public release, we get a bit more cautious - if unsure,
 169 it doesn't hurt to ask first.
 170
 171 -------------------------------------------------------------------------------
 172
 173 4. Documentation Guidelines
 174
 175 All formal documents are maintained in Docbook SGML and located in the doc/
 176 source/* directory. You will need Docbook, the Docbook DTD's and the Docbook
 177 modular stylesheets (or comparable alternatives), and either jade or openjade
 178 (recommended) installed in order to build docs from source. Currently there is
 179 user-manual, FAQ, and, of course this, the developer-manual in this format. The
 180 README, AUTHORS privoxy.1 (man page) files are also now maintained as Docbook
 181 SGML. The finished files are all in the top-level source directory are
 182 generated files! Also, index.html, the Privoxy home page, is maintained as
 183 SGML. DO NOT edit these directly. Edit the SGML source, or contact someone
 184 involved in the documentation (at present Stefan and Hal).
 185
 186 Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as plain
 187 text files in the top-level source directory. At least for the time being.
 188
 189 Packagers are encouraged to include this documentation. For those without the
 190 ability to build the docs locally, text versions of each are kept in CVS. HTML
 191 versions are also now being kept in CVS under doc/webserver/*.
 192
 193 Formal documents are built with the Makefile targets of make dok, or
 194 alternately make redhat-dok. If you have problems, try both. The build process
 195 uses the document SGML sources in doc/source/*/* to update all text files in
 196 doc/text/ and to update all HTML documents in doc/webserver/.
 197
 198 Documentation writers should please make sure documents build successfully
 199 before committing to CVS, if possible.
 200
 201 How do you update the webserver (i.e. the pages on privoxy.org)?
 202
 203  1. First, build the docs by running make dok (or alternately make redhat-dok).
 204
 205  2. Run make webserver which copies all files from doc/webserver to the
 206     sourceforge webserver via scp.
 207
 208 Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html)
 209 so that those without the ability to build them locally, have access to them if
 210 needed. This is especially important just prior to a new release! Please do
 211 this after the $VERSION and other release specific data in configure.in has
 212 been updated (this is done just prior to a new release).
 213
 214 -------------------------------------------------------------------------------
 215
 216 4.1. Quickstart to Docbook and SGML
 217
 218 If you are not familiar with SGML, it is a markup language similar to HTML.
 219 Actually, not a mark up language per se, but a language used to define markup
 220 languages. In fact, HTML is an SGML application. Both will use "tags" to format
 221 text and other content. SGML tags can be much more varied, and flexible, but do
 222 much of the same kinds of things. The tags, or "elements", are definable in
 223 SGML. There is no set "standards". Since we are using Docbook, our tags are
 224 those that are defined by Docbook. Much of how the finish document is rendered
 225 is determined by the "stylesheets". The stylesheets determine how each tag gets
 226 translated to HTML, or other formats.
 227
 228 Tags in Docbook SGML need to be always "closed". If not, you will likely
 229 generate errors. Example: <title>My Title</title>. They are also
 230 case-insensitive, but we strongly suggest using all lower case. This keeps
 231 compatibility with [Docbook] XML.
 232
 233 Our documents use "sections" for the most part. Sections will be processed into
 234 HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to
 235 also generate the Table of Contents for each doc. Our TOC's are set to a depth
 236 of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will
 237 not. Each section requires a <title> element, and at least one <para>. There is
 238 a limit of five section levels in Docbook, but generally three should be
 239 sufficient for our purposes.
 240
 241 Some common elements that you likely will use:
 242
 243 , paragraph delimiter. Most text needs to be within paragraph elements (there
 244 are some exceptions).
 245 , the stylesheets make this italics.
 246 , files and directories.
 247 , command examples.
 248 , like
 249 , more or less.
 250 , list with bullets.
 251 , member of the above.
 252 , screen output, implies .
 253 , like HTML tag.
 254 , for, doh, quoting text.
 255
 256 Look at any of the existing docs for examples of all these and more.
 257
 258 -------------------------------------------------------------------------------
 259
 260 4.2. Privoxy Documentation Style
 261
 262 It will be easier if everyone follows a similar writing style. This just makes
 263 it easier to read what someone else has written if it is all done in a similar
 264 fashion.
 265
 266 Here it is:
 267
 268   * All tags should be lower case.
 269
 270   * Tags delimiting a block of text (even small blocks) should be on their own
 271     line. Like:
 272
 273      <para>
 274       Some text goes here.
 275      </para>
 276
 277
 278     Tags marking individual words, or few words, should be in-line:
 279
 280       Just to <emphasis>emphasize</emphasis>, some text goes here.
 281
 282
 283   * Tags should be nested and step indented for block text like: (except
 284     in-line tags)
 285
 286      <para>
 287       <itemizedlist>
 288        <para>
 289         <listitem>
 290           Some text goes here in our list example.
 291          </listitem>
 292        </para>
 293       </itemizedlist>
 294      </para>
 295
 296
 297     This makes it easier to find the text amongst the tags ;-)
 298
 299   * Use white space to separate logical divisions within a document, like
 300     between sections. Running everything together consistently makes it harder
 301     to read and work on.
 302
 303   * Do not hesitate to make comments. Comments can either use the <comment>
 304     element, or the <!-- --> style comment familiar from HTML. (Note in Docbook
 305     v4.x <comment> is replaced by <remark>.)
 306
 307   * We have an international audience. Refrain from slang, or English
 308     idiosyncrasies (too many to list :). Humor also does not translate well
 309     sometimes.
 310
 311   * Try to keep overall line lengths in source files to 80 characters or less
 312     for obvious reasons. This is not always possible, with lengthy URLs for
 313     instance.
 314
 315   * Our documents are available in differing formats. Right now, they are just
 316     plain text, and HTML, but PDF, and others is always a future possibility.
 317     Be careful with URLs (<ulink>), and avoid this mistake:
 318
 319     My favorite site is <ulink url="http://example.com">here</ulink>.
 320
 321     This will render as "My favorite site is here", which is not real helpful
 322     in a text doc. Better like this:
 323
 324     My favorite site is <ulink url="http://example.com">example.com</ulink>.
 325
 326   * All documents should be spell checked occasionally. aspell can check SGML
 327     with the -H option. (ispell I think too.)
 328
 329 -------------------------------------------------------------------------------
 330
 331 4.3. Privoxy Custom Entities
 332
 333 Privoxy documentation is using a number of customized "entities" to facilitate
 334 documentation maintenance.
 335
 336 We are using a set of "boilerplate" files with generic text, that is used by
 337 multiple docs. This way we can write something once, and use it repeatedly
 338 without having to re-write the same content over and over again. If editing
 339 such a file, keep in mind that it should be generic. That is the purpose; so it
 340 can be used in varying contexts without additional modifications.
 341
 342 We are also using what Docbook calls "internal entities". These are like
 343 variables in programming. Well, sort of. For instance, we have the p-version
 344 entity that contains the current Privoxy version string. You are strongly
 345 encouraged to use these where possible. Some of these obviously require
 346 re-setting with each release (done by the Makefile). A sampling of custom
 347 entities are listed below. See any of the main docs for examples.
 348
 349   * Re- "boilerplate" text entities are defined like:
 350
 351     <!entity supported SYSTEM "supported.sgml">
 352
 353     In this example, the contents of the file, supported.sgml is available for
 354     inclusion anywhere in the doc. To make this happen, just reference the now
 355     defined entity: &supported; (starts with an ampersand and ends with a
 356     semi-colon), and the contents will be dumped into the finished doc at that
 357     point.
 358
 359   * Commonly used "internal entities":
 360
 361     p-version: the Privoxy version string, e.g. "2.9.14".
 362     p-status: the project status, either "alpha", "beta", or "stable".
 363     p-not-stable: use to conditionally include text in "not stable" releases
 364     (e.g. "beta").
 365     p-stable: just the opposite.
 366     p-text: this doc is only generated as text.
 367
 368 There are others in various places that are defined for a specific purpose.
 369 Read the source!
 370
 371 -------------------------------------------------------------------------------
 372
 373 5. Coding Guidelines
 374
 375 5.1. Introduction
 376
 377 This set of standards is designed to make our lives easier. It is developed
 378 with the simple goal of helping us keep the "new and improved Privoxy"
 379 consistent and reliable. Thus making maintenance easier and increasing chances
 380 of success of the project.
 381
 382 And that of course comes back to us as individuals. If we can increase our
 383 development and product efficiencies then we can solve more of the request for
 384 changes/improvements and in general feel good about ourselves. ;->
 385
 386 -------------------------------------------------------------------------------
 387
 388 5.2. Using Comments
 389
 390 5.2.1. Comment, Comment, Comment
 391
 392 Explanation:
 393
 394 Comment as much as possible without commenting the obvious. For example do not
 395 comment "aVariable is equal to bVariable". Instead explain why aVariable should
 396 be equal to the bVariable. Just because a person can read code does not mean
 397 they will understand why or what is being done. A reader may spend a lot more
 398 time figuring out what is going on when a simple comment or explanation would
 399 have prevented the extra research. Please help your brother IJB'ers out!
 400
 401 The comments will also help justify the intent of the code. If the comment
 402 describes something different than what the code is doing then maybe a
 403 programming error is occurring.
 404
 405 Example:
 406
 407 /* if page size greater than 1k ... */
 408 if ( PageLength() > 1024 )
 409 {
 410     ... "block" the page up ...
 411 }
 412
 413 /* if page size is small, send it in blocks */
 414 if ( PageLength() > 1024 )
 415 {
 416     ... "block" the page up ...
 417 }
 418
 419 This demonstrates 2 cases of "what not to do".  The first is a
 420 "syntax comment".  The second is a comment that does not fit what
 421 is actually being done.
 422
 423 -------------------------------------------------------------------------------
 424
 425 5.2.2. Use blocks for comments
 426
 427 Explanation:
 428
 429 Comments can help or they can clutter. They help when they are differentiated
 430 from the code they describe. One line comments do not offer effective
 431 separation between the comment and the code. Block identifiers do, by
 432 surrounding the code with a clear, definable pattern.
 433
 434 Example:
 435
 436 /*********************************************************************
 437  * This will stand out clearly in your code!
 438  *********************************************************************/
 439 if ( thisVariable == thatVariable )
 440 {
 441    DoSomethingVeryImportant();
 442 }
 443
 444
 445 /* unfortunately, this may not */
 446 if ( thisVariable == thatVariable )
 447 {
 448    DoSomethingVeryImportant();
 449 }
 450
 451
 452 if ( thisVariable == thatVariable ) /* this may not either */
 453 {
 454    DoSomethingVeryImportant();
 455 }
 456
 457 Exception:
 458
 459 If you are trying to add a small logic comment and do not wish to "disrupt" the
 460 flow of the code, feel free to use a 1 line comment which is NOT on the same
 461 line as the code.
 462
 463 -------------------------------------------------------------------------------
 464
 465 5.2.3. Keep Comments on their own line
 466
 467 Explanation:
 468
 469 It goes back to the question of readability. If the comment is on the same line
 470 as the code it will be harder to read than the comment that is on its own line.
 471
 472 There are three exceptions to this rule, which should be violated freely and
 473 often: during the definition of variables, at the end of closing braces, when
 474 used to comment parameters.
 475
 476 Example:
 477
 478 /*********************************************************************
 479  * This will stand out clearly in your code,
 480  * But the second example won't.
 481  *********************************************************************/
 482 if ( thisVariable == thatVariable )
 483 {
 484    DoSomethingVeryImportant();
 485 }
 486
 487 if ( thisVariable == thatVariable ) /*can you see me?*/
 488 {
 489    DoSomethingVeryImportant(); /*not easily*/
 490 }
 491
 492
 493 /*********************************************************************
 494  * But, the encouraged exceptions:
 495  *********************************************************************/
 496 int urls_read     = 0;     /* # of urls read + rejected */
 497 int urls_rejected = 0;     /* # of urls rejected */
 498
 499 if ( 1 == X )
 500 {
 501    DoSomethingVeryImportant();
 502 }
 503
 504
 505 short DoSomethingVeryImportant(
 506    short firstparam,   /* represents something */
 507    short nextparam     /* represents something else */ )
 508 {
 509    ...code here...
 510
 511 }   /* -END- DoSomethingVeryImportant */
 512
 513 -------------------------------------------------------------------------------
 514
 515 5.2.4. Comment each logical step
 516
 517 Explanation:
 518
 519 Logical steps should be commented to help others follow the intent of the
 520 written code and comments will make the code more readable.
 521
 522 If you have 25 lines of code without a comment, you should probably go back
 523 into it to see where you forgot to put one.
 524
 525 Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
 526 these are usually major logic containers.
 527
 528 -------------------------------------------------------------------------------
 529
 530 5.2.5. Comment All Functions Thoroughly
 531
 532 Explanation:
 533
 534 A reader of the code should be able to look at the comments just prior to the
 535 beginning of a function and discern the reason for its existence and the
 536 consequences of using it. The reader should not have to read through the code
 537 to determine if a given function is safe for a desired use. The proper
 538 information thoroughly presented at the introduction of a function not only
 539 saves time for subsequent maintenance or debugging, it more importantly aids in
 540 code reuse by allowing a user to determine the safety and applicability of any
 541 function for the problem at hand. As a result of such benefits, all functions
 542 should contain the information presented in the addendum section of this
 543 document.
 544
 545 -------------------------------------------------------------------------------
 546
 547 5.2.6. Comment at the end of braces if the content is more than one screen
 548 length
 549
 550 Explanation:
 551
 552 Each closing brace should be followed on the same line by a comment that
 553 describes the origination of the brace if the original brace is off of the
 554 screen, or otherwise far away from the closing brace. This will simplify the
 555 debugging, maintenance, and readability of the code.
 556
 557 As a suggestion , use the following flags to make the comment and its brace
 558 more readable:
 559
 560 use following a closing brace: } /* -END- if() or while () or etc... */
 561
 562 Example:
 563
 564 if ( 1 == X )
 565 {
 566    DoSomethingVeryImportant();
 567    ...some long list of commands...
 568 } /* -END- if x is 1 */
 569
 570 or:
 571
 572 if ( 1 == X )
 573 {
 574    DoSomethingVeryImportant();
 575    ...some long list of commands...
 576 } /* -END- if ( 1 == X ) */
 577
 578 -------------------------------------------------------------------------------
 579
 580 5.3. Naming Conventions
 581
 582 5.3.1. Variable Names
 583
 584 Explanation:
 585
 586 Use all lowercase, and separate words via an underscore ('_'). Do not start an
 587 identifier with an underscore. (ANSI C reserves these for use by the compiler
 588 and system headers.) Do not use identifiers which are reserved in ANSI C++.
 589 (E.g. template, class, true, false, ...). This is in case we ever decide to
 590 port Privoxy to C++.
 591
 592 Example:
 593
 594 int ms_iis5_hack = 0;
 595
 596 Instead of:
 597
 598 int msiis5hack = 0; int msIis5Hack = 0;
 599
 600 -------------------------------------------------------------------------------
 601
 602 5.3.2. Function Names
 603
 604 Explanation:
 605
 606 Use all lowercase, and separate words via an underscore ('_'). Do not start an
 607 identifier with an underscore. (ANSI C reserves these for use by the compiler
 608 and system headers.) Do not use identifiers which are reserved in ANSI C++.
 609 (E.g. template, class, true, false, ...). This is in case we ever decide to
 610 port Privoxy to C++.
 611
 612 Example:
 613
 614 int load_some_file( struct client_state *csp )
 615
 616 Instead of:
 617
 618 int loadsomefile( struct client_state *csp )
 619 int loadSomeFile( struct client_state *csp )
 620
 621 -------------------------------------------------------------------------------
 622
 623 5.3.3. Header file prototypes
 624
 625 Explanation:
 626
 627 Use a descriptive parameter name in the function prototype in header files. Use
 628 the same parameter name in the header file that you use in the c file.
 629
 630 Example:
 631
 632 (.h) extern int load_aclfile( struct client_state *csp );
 633 (.c) int load_aclfile( struct client_state *csp )
 634
 635 Instead of:
 636
 637 (.h) extern int load_aclfile( struct client_state * ); or
 638 (.h) extern int load_aclfile();
 639 (.c) int load_aclfile( struct client_state *csp )
 640
 641 -------------------------------------------------------------------------------
 642
 643 5.3.4. Enumerations, and #defines
 644
 645 Explanation:
 646
 647 Use all capital letters, with underscores between words. Do not start an
 648 identifier with an underscore. (ANSI C reserves these for use by the compiler
 649 and system headers.)
 650
 651 Example:
 652
 653 (enumeration) : enum Boolean { FALSE, TRUE };
 654 (#define) : #define DEFAULT_SIZE 100;
 655
 656 Note: We have a standard naming scheme for #defines that toggle a feature in
 657 the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word)
 658 description.
 659
 660 Example:
 661
 662 #define FEATURE_FORCE 1
 663
 664 #ifdef FEATURE_FORCE
 665 #define FORCE_PREFIX blah
 666 #endif /* def FEATURE_FORCE */
 667
 668 -------------------------------------------------------------------------------
 669
 670 5.3.5. Constants
 671
 672 Explanation:
 673
 674 Spell common words out entirely (do not remove vowels).
 675
 676 Use only widely-known domain acronyms and abbreviations. Capitalize all letters
 677 of an acronym.
 678
 679 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
 680 terminate a name with an underscore.
 681
 682 Example:
 683
 684 #define USE_IMAGE_LIST 1
 685
 686 Instead of:
 687
 688 #define USE_IMG_LST 1 or
 689 #define _USE_IMAGE_LIST 1 or
 690 #define USE_IMAGE_LIST_ 1 or
 691 #define use_image_list 1 or
 692 #define UseImageList 1
 693
 694 -------------------------------------------------------------------------------
 695
 696 5.4. Using Space
 697
 698 5.4.1. Put braces on a line by themselves.
 699
 700 Explanation:
 701
 702 The brace needs to be on a line all by itself, not at the end of the statement.
 703 Curly braces should line up with the construct that they're associated with.
 704 This practice makes it easier to identify the opening and closing braces for a
 705 block.
 706
 707 Example:
 708
 709 if ( this == that )
 710 {
 711    ...
 712 }
 713
 714 Instead of:
 715
 716 if ( this == that ) { ... }
 717
 718 or
 719
 720 if ( this == that ) { ... }
 721
 722 Note: In the special case that the if-statement is inside a loop, and it is
 723 trivial, i.e. it tests for a condition that is obvious from the purpose of the
 724 block, one-liners as above may optically preserve the loop structure and make
 725 it easier to read.
 726
 727 Status: developer-discretion.
 728
 729 Example exception:
 730
 731 while ( more lines are read )
 732 {
 733    /* Please document what is/is not a comment line here */
 734    if ( it's a comment ) continue;
 735
 736    do_something( line );
 737 }
 738
 739 -------------------------------------------------------------------------------
 740
 741 5.4.2. ALL control statements should have a block
 742
 743 Explanation:
 744
 745 Using braces to make a block will make your code more readable and less prone
 746 to error. All control statements should have a block defined.
 747
 748 Example:
 749
 750 if ( this == that )
 751 {
 752    DoSomething();
 753    DoSomethingElse();
 754 }
 755
 756 Instead of:
 757
 758 if ( this == that ) DoSomething(); DoSomethingElse();
 759
 760 or
 761
 762 if ( this == that ) DoSomething();
 763
 764 Note: The first example in "Instead of" will execute in a manner other than
 765 that which the developer desired (per indentation). Using code braces would
 766 have prevented this "feature". The "explanation" and "exception" from the point
 767 above also applies.
 768
 769 -------------------------------------------------------------------------------
 770
 771 5.4.3. Do not belabor/blow-up boolean expressions
 772
 773 Example:
 774
 775 structure->flag = ( condition );
 776
 777 Instead of:
 778
 779 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
 780
 781 Note: The former is readable and concise. The later is wordy and inefficient.
 782 Please assume that any developer new to the project has at least a "good"
 783 knowledge of C/C++. (Hope I do not offend by that last comment ... 8-)
 784
 785 -------------------------------------------------------------------------------
 786
 787 5.4.4. Use white space freely because it is free
 788
 789 Explanation:
 790
 791 Make it readable. The notable exception to using white space freely is listed
 792 in the next guideline.
 793
 794 Example:
 795
 796 int firstValue   = 0;
 797 int someValue    = 0;
 798 int anotherValue = 0;
 799 int thisVariable = 0;
 800
 801 if ( thisVariable == thatVariable )
 802
 803 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
 804
 805 -------------------------------------------------------------------------------
 806
 807 5.4.5. Don't use white space around structure operators
 808
 809 Explanation:
 810
 811 - structure pointer operator ( "->" ) - member operator ( "." ) - functions and
 812 parentheses
 813
 814 It is a general coding practice to put pointers, references, and function
 815 parentheses next to names. With spaces, the connection between the object and
 816 variable/function name is not as clear.
 817
 818 Example:
 819
 820 aStruct->aMember;
 821 aStruct.aMember;
 822 FunctionName();
 823
 824 Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
 825
 826 -------------------------------------------------------------------------------
 827
 828 5.4.6. Make the last brace of a function stand out
 829
 830 Example:
 831
 832 int function1( ... )
 833 {
 834    ...code...
 835    return( retCode );
 836
 837 }   /* -END- function1 */
 838
 839
 840 int function2( ... )
 841 {
 842 }   /* -END- function2 */
 843
 844 Instead of:
 845
 846 int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { }
 847
 848 Note: Use 1 blank line before the closing brace and 2 lines afterward. This
 849 makes the end of function standout to the most casual viewer. Although function
 850 comments help separate functions, this is still a good coding practice. In
 851 fact, I follow these rules when using blocks in "for", "while", "do" loops, and
 852 long if {} statements too. After all whitespace is free!
 853
 854 Status: developer-discretion on the number of blank lines. Enforced is the end
 855 of function comments.
 856
 857 -------------------------------------------------------------------------------
 858
 859 5.4.7. Use 3 character indentions
 860
 861 Explanation:
 862
 863 If some use 8 character TABs and some use 3 character TABs, the code can look *
 864 very* ragged. So use 3 character indentions only. If you like to use TABs, pass
 865 your code through a filter such as "expand -t3" before checking in your code.
 866
 867 Example:
 868
 869 static const char * const url_code_map[256] =
 870 {
 871    NULL, ...
 872 };
 873
 874
 875 int function1( ... )
 876 {
 877    if ( 1 )
 878    {
 879       return( ALWAYS_TRUE );
 880    }
 881    else
 882    {
 883       return( HOW_DID_YOU_GET_HERE );
 884    }
 885
 886    return( NEVER_GETS_HERE );
 887
 888 }
 889
 890 -------------------------------------------------------------------------------
 891
 892 5.5. Initializing
 893
 894 5.5.1. Initialize all variables
 895
 896 Explanation:
 897
 898 Do not assume that the variables declared will not be used until after they
 899 have been assigned a value somewhere else in the code. Remove the chance of
 900 accidentally using an unassigned variable.
 901
 902 Example:
 903
 904 short anShort = 0;
 905 float aFloat  = 0;
 906 struct *ptr = NULL;
 907
 908 Note: It is much easier to debug a SIGSEGV if the message says you are trying
 909 to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a
 910 SIGSEV vs. arrayPtr[0].
 911
 912 Status: developer-discretion if and only if the variable is assigned a value
 913 "shortly after" declaration.
 914
 915 -------------------------------------------------------------------------------
 916
 917 5.6. Functions
 918
 919 5.6.1. Name functions that return a boolean as a question.
 920
 921 Explanation:
 922
 923 Value should be phrased as a question that would logically be answered as a
 924 true or false statement
 925
 926 Example:
 927
 928 ShouldWeBlockThis();
 929 ContainsAnImage();
 930 IsWebPageBlank();
 931
 932 -------------------------------------------------------------------------------
 933
 934 5.6.2. Always specify a return type for a function.
 935
 936 Explanation:
 937
 938 The default return for a function is an int. To avoid ambiguity, create a
 939 return for a function when the return has a purpose, and create a void return
 940 type if the function does not need to return anything.
 941
 942 -------------------------------------------------------------------------------
 943
 944 5.6.3. Minimize function calls when iterating by using variables
 945
 946 Explanation:
 947
 948 It is easy to write the following code, and a clear argument can be made that
 949 the code is easy to understand:
 950
 951 Example:
 952
 953 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
 954 {
 955    ....
 956 }
 957
 958 Note: Unfortunately, this makes a function call for each and every iteration.
 959 This increases the overhead in the program, because the compiler has to look up
 960 the function each time, call it, and return a value. Depending on what occurs
 961 in the blockListLength() call, it might even be creating and destroying
 962 structures with each iteration, even though in each case it is comparing "cnt"
 963 to the same value, over and over. Remember too - even a call to blockListLength
 964 () is a function call, with the same overhead.
 965
 966 Instead of using a function call during the iterations, assign the value to a
 967 variable, and evaluate using the variable.
 968
 969 Example:
 970
 971 size_t len = blockListLength();
 972
 973 for ( size_t cnt = 0; cnt < len; cnt ++ )
 974 {
 975    ....
 976 }
 977
 978 Exceptions: if the value of blockListLength() *may* change or could *
 979 potentially* change, then you must code the function call in the for/while
 980 loop.
 981
 982 -------------------------------------------------------------------------------
 983
 984 5.6.4. Pass and Return by Const Reference
 985
 986 Explanation:
 987
 988 This allows a developer to define a const pointer and call your function. If
 989 your function does not have the const keyword, we may not be able to use your
 990 function. Consider strcmp, if it were defined as: extern int strcmp( char *s1,
 991 char *s2 );
 992
 993 I could then not use it to compare argv's in main: int main( int argc, const
 994 char *argv[] ) { strcmp( argv[0], "privoxy" ); }
 995
 996 Both these pointers are *const*! If the c runtime library maintainers do it, we
 997 should too.
 998
 999 -------------------------------------------------------------------------------
1000
1001 5.6.5. Pass and Return by Value
1002
1003 Explanation:
1004
1005 Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes
1006 or less). Aka, a function declaration like: int load_aclfile( struct
1007 client_state csp )
1008
1009 would not work. So, to be consistent, we should declare all prototypes with
1010 "pass by value": int load_aclfile( struct client_state *csp )
1011
1012 -------------------------------------------------------------------------------
1013
1014 5.6.6. Names of include files
1015
1016 Explanation:
1017
1018 Your include statements should contain the file name without a path. The path
1019 should be listed in the Makefile, using -I as processor directive to search the
1020 indicated paths. An exception to this would be for some proprietary software
1021 that utilizes a partial path to distinguish their header files from system or
1022 other header files.
1023
1024 Example:
1025
1026 #include      /* This is not a local include */
1027 #include "config.h"       /* This IS a local include */
1028
1029 Exception:
1030
1031 /* This is not a local include, but requires a path element. */
1032 #include
1033
1034 Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
1035 This duplicates the #include "file.h" behavior.
1036
1037 -------------------------------------------------------------------------------
1038
1039 5.6.7. Provide multiple inclusion protection
1040
1041 Explanation:
1042
1043 Prevents compiler and linker errors resulting from redefinition of items.
1044
1045 Wrap each header file with the following syntax to prevent multiple inclusions
1046 of the file. Of course, replace PROJECT_H with your file name, with "." Changed
1047 to "_", and make it uppercase.
1048
1049 Example:
1050
1051 #ifndef PROJECT_H_INCLUDED
1052 #define PROJECT_H_INCLUDED
1053  ...
1054 #endif /* ndef PROJECT_H_INCLUDED */
1055
1056 -------------------------------------------------------------------------------
1057
1058 5.6.8. Use `extern "C"` when appropriate
1059
1060 Explanation:
1061
1062 If our headers are included from C++, they must declare our functions as
1063 `extern "C"`. This has no cost in C, but increases the potential re-usability
1064 of our code.
1065
1066 Example:
1067
1068 #ifdef __cplusplus
1069 extern "C"
1070 {
1071 #endif /* def __cplusplus */
1072
1073 ... function definitions here ...
1074
1075 #ifdef __cplusplus
1076 }
1077 #endif /* def __cplusplus */
1078
1079 -------------------------------------------------------------------------------
1080
1081 5.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
1082
1083 Explanation:
1084
1085 Useful in headers that include pointers to other struct's. Modifications to
1086 excess header files may cause needless compiles.
1087
1088 Example:
1089
1090 /*********************************************************************
1091  * We're avoiding an include statement here!
1092  *********************************************************************/
1093 struct file_list;
1094 extern file_list *xyz;
1095
1096 Note: If you declare "file_list xyz;" (without the pointer), then including the
1097 proper header file is necessary. If you only want to prototype a pointer,
1098 however, the header file is unnecessary.
1099
1100 Status: Use with discretion.
1101
1102 -------------------------------------------------------------------------------
1103
1104 5.7. General Coding Practices
1105
1106 5.7.1. Turn on warnings
1107
1108 Explanation
1109
1110 Compiler warnings are meant to help you find bugs. You should turn on as many
1111 as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as
1112 possible.
1113
1114 -------------------------------------------------------------------------------
1115
1116 5.7.2. Provide a default case for all switch statements
1117
1118 Explanation:
1119
1120 What you think is guaranteed is never really guaranteed. The value that you
1121 don't think you need to check is the one that someday will be passed. So, to
1122 protect yourself from the unknown, always have a default step in a switch
1123 statement.
1124
1125 Example:
1126
1127 switch( hash_string( cmd ) )
1128 {
1129    case hash_actions_file :
1130       ... code ...
1131       break;
1132
1133    case hash_confdir :
1134       ... code ...
1135       break;
1136
1137    default :
1138       log_error( ... );
1139       ... anomaly code goes here ...
1140       continue; / break; / exit( 1 ); / etc ...
1141
1142 } /* end switch( hash_string( cmd ) ) */
1143
1144 Note: If you already have a default condition, you are obviously exempt from
1145 this point. Of note, most of the WIN32 code calls `DefWindowProc' after the
1146 switch statement. This API call *should* be included in a default statement.
1147
1148 Another Note: This is not so much a readability issue as a robust programming
1149 issue. The "anomaly code goes here" may be no more than a print to the STDERR
1150 stream (as in load_config). Or it may really be an ABEND condition.
1151
1152 Status: Programmer discretion is advised.
1153
1154 -------------------------------------------------------------------------------
1155
1156 5.7.3. Try to avoid falling through cases in a switch statement.
1157
1158 Explanation:
1159
1160 In general, you will want to have a 'break' statement within each 'case' of a
1161 switch statement. This allows for the code to be more readable and
1162 understandable, and furthermore can prevent unwanted surprises if someone else
1163 later gets creative and moves the code around.
1164
1165 The language allows you to plan the fall through from one case statement to
1166 another simply by omitting the break statement within the case statement. This
1167 feature does have benefits, but should only be used in rare cases. In general,
1168 use a break statement for each case statement.
1169
1170 If you choose to allow fall through, you should comment both the fact of the
1171 fall through and reason why you felt it was necessary.
1172
1173 -------------------------------------------------------------------------------
1174
1175 5.7.4. Use 'long' or 'short' Instead of 'int'
1176
1177 Explanation:
1178
1179 On 32-bit platforms, int usually has the range of long. On 16-bit platforms,
1180 int has the range of short.
1181
1182 Status: open-to-debate. In the case of most FSF projects (including X/
1183 GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I
1184 forget the exact typedefs now). Should we add these to IJB now that we have a
1185 "configure" script?
1186
1187 -------------------------------------------------------------------------------
1188
1189 5.7.5. Don't mix size_t and other types
1190
1191 Explanation:
1192
1193 The type of size_t varies across platforms. Do not make assumptions about
1194 whether it is signed or unsigned, or about how long it is. Do not compare a
1195 size_t against another variable of a different type (or even against a
1196 constant) without casting one of the values. Try to avoid using size_t if you
1197 can.
1198
1199 -------------------------------------------------------------------------------
1200
1201 5.7.6. Declare each variable and struct on its own line.
1202
1203 Explanation:
1204
1205 It can be tempting to declare a series of variables all on one line. Don't.
1206
1207 Example:
1208
1209 long a = 0;
1210 long b = 0;
1211 long c = 0;
1212
1213 Instead of:
1214
1215 long a, b, c;
1216
1217 Explanation: - there is more room for comments on the individual variables -
1218 easier to add new variables without messing up the original ones - when
1219 searching on a variable to find its type, there is less clutter to "visually"
1220 eliminate
1221
1222 Exceptions: when you want to declare a bunch of loop variables or other trivial
1223 variables; feel free to declare them on 1 line. You should, although, provide a
1224 good comment on their functions.
1225
1226 Status: developer-discretion.
1227
1228 -------------------------------------------------------------------------------
1229
1230 5.7.7. Use malloc/zalloc sparingly
1231
1232 Explanation:
1233
1234 Create a local struct (on the stack) if the variable will live and die within
1235 the context of one function call.
1236
1237 Only "malloc" a struct (on the heap) if the variable's life will extend beyond
1238 the context of one function call.
1239
1240 Example:
1241
1242 If a function creates a struct and stores a pointer to it in a
1243 list, then it should definitely be allocated via `malloc'.
1244
1245 -------------------------------------------------------------------------------
1246
1247 5.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1248
1249 Explanation:
1250
1251 If you have to "malloc" an instance, you are responsible for insuring that the
1252 instance is `free'd, even if the deallocation event falls within some other
1253 programmer's code. You are also responsible for ensuring that deletion is
1254 timely (i.e. not too soon, not too late). This is known as "low-coupling" and
1255 is a "good thing (tm)". You may need to offer a free/unload/destuctor type
1256 function to accommodate this.
1257
1258 Example:
1259
1260 int load_re_filterfile( struct client_state *csp ) { ... }
1261 static void unload_re_filterfile( void *f ) { ... }
1262
1263 Exceptions:
1264
1265 The developer cannot be expected to provide `free'ing functions for C run-time
1266 library functions ... such as `strdup'.
1267
1268 Status: developer-discretion. The "main" use of this standard is for allocating
1269 and freeing data structures (complex or nested).
1270
1271 -------------------------------------------------------------------------------
1272
1273 5.7.9. Add loaders to the `file_list' structure and in order
1274
1275 Explanation:
1276
1277 I have ordered all of the "blocker" file code to be in alpha order. It is
1278 easier to add/read new blockers when you expect a certain order.
1279
1280 Note: It may appear that the alpha order is broken in places by POPUP tests
1281 coming before PCRS tests. But since POPUPs can also be referred to as
1282 KILLPOPUPs, it is clear that it should come first.
1283
1284 -------------------------------------------------------------------------------
1285
1286 5.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
1287
1288 Explanation:
1289
1290 If you have enough confidence in new code or confidence in your changes, but
1291 are not *quite* sure of the repercussions, add this:
1292
1293 /* FIXME: this code has a logic error on platform XYZ, * attempting to fix */ #
1294 ifdef PLATFORM ...changed code here... #endif
1295
1296 or:
1297
1298 /* FIXME: I think the original author really meant this... */ ...changed code
1299 here...
1300
1301 or:
1302
1303 /* FIXME: new code that *may* break something else... */ ...new code here...
1304
1305 Note: If you make it clear that this may or may not be a "good thing (tm)", it
1306 will be easier to identify and include in the project (or conversely exclude
1307 from the project).
1308
1309 -------------------------------------------------------------------------------
1310
1311 5.8. Addendum: Template for files and function comment blocks:
1312
1313 Example for file comments:
1314
1315 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $";
1316 /*********************************************************************
1317  *
1318  * File        :  $Source$
1319  *
1320  * Purpose     :  (Fill me in with a good description!)
1321  *
1322  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1323  *                Privoxy team. http://www.privoxy.org/
1324  *
1325  *                Based on the Internet Junkbuster originally written
1326  *                by and Copyright (C) 1997 Anonymous Coders and
1327  *                Junkbusters Corporation.  http://www.junkbusters.com
1328  *
1329  *                This program is free software; you can redistribute it
1330  *                and/or modify it under the terms of the GNU General
1331  *                Public License as published by the Free Software
1332  *                Foundation; either version 2 of the License, or (at
1333  *                your option) any later version.
1334  *
1335  *                This program is distributed in the hope that it will
1336  *                be useful, but WITHOUT ANY WARRANTY; without even the
1337  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1338  *                PARTICULAR PURPOSE.  See the GNU General Public
1339  *                License for more details.
1340  *
1341  *                The GNU General Public License should be included with
1342  *                this file.  If not, you can view it at
1343  *                http://www.gnu.org/copyleft/gpl.html
1344  *                or write to the Free Software Foundation, Inc., 59
1345  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1346  *
1347  * Revisions   :
1348  *    $Log$
1349  *
1350  *********************************************************************/
1351
1352
1353 #include "config.h"
1354
1355    ...necessary include files for us to do our work...
1356
1357 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1358
1359 Note: This declares the rcs variables that should be added to the
1360 "show-proxy-args" page. If this is a brand new creation by you, you are free to
1361 change the "Copyright" section to represent the rights you wish to maintain.
1362
1363 Note: The formfeed character that is present right after the comment flower box
1364 is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of
1365 the code (via `forward-page' and `backward-page'). Please include it if you
1366 can.
1367
1368 Example for file header comments:
1369
1370 #ifndef _FILENAME_H
1371 #define _FILENAME_H
1372 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $"
1373 /*********************************************************************
1374  *
1375  * File        :  $Source$
1376  *
1377  * Purpose     :  (Fill me in with a good description!)
1378  *
1379  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1380  *                Privoxy team. http://www.privoxy.org/
1381  *
1382  *                Based on the Internet Junkbuster originally written
1383  *                by and Copyright (C) 1997 Anonymous Coders and
1384  *                Junkbusters Corporation.  http://www.junkbusters.com
1385  *
1386  *                This program is free software; you can redistribute it
1387  *                and/or modify it under the terms of the GNU General
1388  *                Public License as published by the Free Software
1389  *                Foundation; either version 2 of the License, or (at
1390  *                your option) any later version.
1391  *
1392  *                This program is distributed in the hope that it will
1393  *                be useful, but WITHOUT ANY WARRANTY; without even the
1394  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1395  *                PARTICULAR PURPOSE.  See the GNU General Public
1396  *                License for more details.
1397  *
1398  *                The GNU General Public License should be included with
1399  *                this file.  If not, you can view it at
1400  *                http://www.gnu.org/copyleft/gpl.html
1401  *                or write to the Free Software Foundation, Inc., 59
1402  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1403  *
1404  * Revisions   :
1405  *    $Log$
1406  *
1407  *********************************************************************/
1408
1409
1410 #include "project.h"
1411
1412 #ifdef __cplusplus
1413 extern "C" {
1414 #endif
1415
1416    ... function headers here ...
1417
1418
1419 /* Revision control strings from this header and associated .c file */
1420 extern const char FILENAME_rcs[];
1421 extern const char FILENAME_h_rcs[];
1422
1423
1424 #ifdef __cplusplus
1425 } /* extern "C" */
1426 #endif
1427
1428 #endif /* ndef _FILENAME_H */
1429
1430 /*
1431   Local Variables:
1432   tab-width: 3
1433   end:
1434 */
1435
1436 Example for function comments:
1437
1438 /*********************************************************************
1439  *
1440  * Function    :  FUNCTION_NAME
1441  *
1442  * Description :  (Fill me in with a good description!)
1443  *
1444  * parameters  :
1445  *          1  :  param1 = pointer to an important thing
1446  *          2  :  x      = pointer to something else
1447  *
1448  * Returns     :  0 => Ok, everything else is an error.
1449  *
1450  *********************************************************************/
1451 int FUNCTION_NAME( void *param1, const char *x )
1452 {
1453    ...
1454    return( 0 );
1455
1456 }
1457
1458 Note: If we all follow this practice, we should be able to parse our code to
1459 create a "self-documenting" web page.
1460
1461 -------------------------------------------------------------------------------
1462
1463 6. Version Control Guidelines
1464
1465 To be filled. note on cvs comments. Don't only comment what you did, but also
1466 why you did it!
1467
1468 -------------------------------------------------------------------------------
1469
1470 7. Testing Guidelines
1471
1472 To be filled.
1473
1474 -------------------------------------------------------------------------------
1475
1476 7.1. Testplan for releases
1477
1478 Explain release numbers. major, minor. developer releases. etc.
1479
1480  1. Remove any existing rpm with rpm -e
1481
1482  2. Remove any file that was left over. This includes (but is not limited to)
1483
1484       + /var/log/privoxy
1485
1486       + /etc/privoxy
1487
1488       + /usr/sbin/privoxy
1489
1490       + /etc/init.d/privoxy
1491
1492       + /usr/doc/privoxy*
1493
1494  3. Install the rpm. Any error messages?
1495
1496  4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
1497     privoxy stop). Reboot your machine. Does autostart work?
1498
1499  5. Start browsing. Does Privoxy work? Logfile written?
1500
1501  6. Remove the rpm. Any error messages? All files removed?
1502
1503 -------------------------------------------------------------------------------
1504
1505 7.2. Test reports
1506
1507 Please submit test reports only with the test form at sourceforge. Three simple
1508 steps:
1509
1510   * Select category: the distribution you test on.
1511
1512   * Select group: the version of Privoxy that we are about to release.
1513
1514   * Fill the Summary and Detailed Description with something intelligent (keep
1515     it short and precise).
1516
1517 Do not mail to the mailinglist (we cannot keep track on issues there).
1518
1519 -------------------------------------------------------------------------------
1520
1521 8. Releasing a new version
1522
1523 To minimize trouble with distribution contents, web-page errors and the like,
1524 we strongly encourage you to follow this section if you prepare a new release
1525 of code or new pages on the webserver.
1526
1527 The following programs are required to follow this process: ncftpput (ncftp),
1528 scp (ssh), gmake (GNU's version of make), autoconf, cvs, ???.
1529
1530 Replace X, Y and Z with the actual version number (X = major, Y = minor, Z =
1531 point):
1532
1533 -------------------------------------------------------------------------------
1534
1535 8.1. Before the Release
1536
1537 The following must be done by one of the developers prior to each new release.
1538
1539   * Make sure that everybody who has worked on the code in the last couple of
1540     days has had a chance to yell "no!" in case they have pending changes/fixes
1541     in their pipelines.
1542
1543   * Increment the version number in configure.in in CVS. Also, increase or
1544     reset the RPM release number in configure.in as appropriate. Do NOT touch
1545     version information after export from CVS. All packages will use the
1546     version and release data from configure.in. Local files should not be
1547     changed, except prior to a CVS commit!!! This way we are all on the same
1548     page!
1549
1550   * If the default actionsfile has changed since last release, bump up its
1551     version info in this line:
1552
1553       {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1554
1555
1556     Then change the version info in doc/webserver/actions/index.php, line:
1557     '$required_actions_file_version = "A.B";'
1558
1559   * Commit all files that were changed in the above steps!
1560
1561   * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't
1562     use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1563
1564   * The first package uploaded should be the official "tarball" release, as
1565     required by the GPL. This is built with the "make tarball-dist" Makefile
1566     target, and then can be uploaded with "make tarball-upload" (see below).
1567
1568 -------------------------------------------------------------------------------
1569
1570 8.2. Update the webserver
1571
1572 All files must be group-readable and group-writable (or no one else will be
1573 able to change them)! To update the webserver, create any pages locally in the
1574 doc/webserver/* directory (or create new directories under doc/webserver), then
1575 do
1576
1577   make webserver
1578
1579
1580 This will do the upload to the webserver (www.privoxy.org).
1581
1582 Note that "make dok" (or "make redhat-dok") creates doc/webserver/user-manual,
1583 doc/webserver/developer-manual, doc/webserver/faq and doc/webserver/index.html
1584 automatically. (doc/webserver/man-page/privoxy-man-page.html is created by a
1585 separate Makefile target, "make man", due to dependencies on some obscure perl
1586 scripts. See comments in GNUmakefile.)
1587
1588 Someone should also commit these to CVS so that packagers without the ability
1589 to build docs locally, have access to them. This is a separate step, and should
1590 also be done before each official release.
1591
1592 Please do NOT use any other means of transferring files to the webserver. "make
1593 webserver" not only uploads, but will make sure that the appropriate
1594 permissions are preserved for shared group access.
1595
1596 -------------------------------------------------------------------------------
1597
1598 8.3. SuSE or Red Hat
1599
1600 Ensure that you have the latest code version. Hence run:
1601
1602   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1603   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1604   cd current
1605
1606
1607 first.
1608
1609   autoheader && autoconf && ./configure
1610
1611
1612 Then do
1613
1614   make suse-dist or make redhat-dist
1615
1616
1617 To upload the package to Sourceforge, simply issue
1618
1619   make suse-upload (or make redhat-upload)
1620
1621
1622 Go to the displayed URL and release the file publicly on Sourceforge.
1623
1624 -------------------------------------------------------------------------------
1625
1626 8.4. OS/2
1627
1628 Ensure that you have the latest code version. Hence run:
1629
1630   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1631   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1632   cd ..
1633   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
1634
1635
1636 You will need a mix of development tools. The main compilation takes place with
1637 IBM Visual Age C++. Some ancillary work takes place with GNU tools, available
1638 from various sources like hobbes.nmsu.edu. Specificially, you will need
1639 autoheader, autoconf and sh tools. The packaging takes place with WarpIN,
1640 available from various sources, including its home page: xworkplace.
1641
1642 Change directory to the os2setup directory. Edit the os2build.cmd file to set
1643 the final executable filename. For example,
1644
1645   installExeName='privoxyos2_setup_X.Y.Z.exe'
1646
1647
1648 Next, edit the IJB.wis file so the release number matches in the PACKAGEID
1649 section:
1650
1651   PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
1652
1653
1654 You're now ready to build. Run:
1655
1656   os2build
1657
1658
1659 And in the ./files directory you will have the WarpIN-installable executable.
1660 Upload this anonymously to uploads.sourceforge.net/incoming, create a release
1661 for it, and you're done.
1662
1663 -------------------------------------------------------------------------------
1664
1665 8.5. Solaris
1666
1667 Login to Sourceforge's compilefarm via ssh
1668
1669   ssh cf.sourceforge.net
1670
1671
1672 Choose the right operating system (not the Debian one). If you have downloaded
1673 Privoxy before,
1674
1675   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1676   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1677   cd current
1678
1679
1680 If not, please checkout Privoxy via CVS first. Run:
1681
1682   autoheader && autoconf && ./configure
1683
1684
1685 Then run
1686
1687   gmake solaris-dist
1688
1689
1690 which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
1691 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1692 archive to Sourceforge's ftp server and release the file publicly.
1693
1694 -------------------------------------------------------------------------------
1695
1696 8.6. Windows
1697
1698 You should ensure you have the latest version of Cygwin (from http://
1699 www.cygwin.com/). Run the following commands from within a Cygwin bash shell.
1700
1701 First check out a clean copy of the correct code version, by running:
1702
1703         mkdir dist
1704         cd dist
1705         cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1706         cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z .
1707
1708
1709 (Note: It is important that this is a clean copy of the code, do not re-use a
1710 working directory after you have manually compiled there).
1711
1712 Then you can build the package. This is fully automated, and is controlled by
1713 winsetup/GNUmakefile. All you need to do is:
1714
1715         cd winsetup
1716         make
1717
1718
1719 Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and
1720 upload it to SourceForge.
1721
1722 -------------------------------------------------------------------------------
1723
1724 8.7. Debian
1725
1726 Ensure that you have the latest code version. Hence run:
1727
1728   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1729   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1730   cd current
1731
1732
1733 first. Run:
1734
1735   autoheader && autoconf && ./configure
1736
1737
1738 Then do FIXME.
1739
1740 -------------------------------------------------------------------------------
1741
1742 8.8. Mac OSX
1743
1744 Ensure that you have the latest code version. Hence run:
1745
1746   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1747   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1748   cd ..
1749   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
1750
1751
1752 From the osxsetup directory, run:
1753
1754   build
1755
1756
1757 This will run autoheader, autoconf and configure as well as make. Finally, it
1758 will copy over the necessary files to the ./osxsetup/files directory for
1759 further processing by PackageMaker.
1760
1761 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the
1762 package name to match the release, and hit the "Create package" button. If you
1763 specify ./Privoxy.pkg as the output package name, you can then create the
1764 distributable zip file with the command:
1765
1766 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
1767
1768
1769 You can then upload privoxyosx_setup_x.y.z.zip anonymously to
1770 uploads.sourceforge.net/incoming, create a release for it, and you're done.
1771
1772 -------------------------------------------------------------------------------
1773
1774 8.9. FreeBSD
1775
1776 Change the version number of Privoxy in the configure.in file. Run:
1777
1778   autoheader && autoconf && ./configure
1779
1780
1781 Then ...
1782
1783 Login to Sourceforge's compilefarm via ssh:
1784
1785   ssh cf.sourceforge.net
1786
1787
1788 Choose the right operating system.
1789
1790   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1791   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1792   cd current
1793
1794
1795 Run:
1796
1797   autoheader && autoconf && ./configure
1798
1799
1800 Then run:
1801
1802   gmake freebsd-dist
1803
1804
1805 which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
1806 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1807 archive to Sourceforge's ftp server and release the file publicly.
1808
1809 -------------------------------------------------------------------------------
1810
1811 8.10. Tarball
1812
1813 Ensure that you have the right code version. Hence run:
1814
1815   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1816   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1817   cd current
1818
1819
1820 first. Run:
1821
1822   autoheader && autoconf && ./configure
1823
1824
1825 Then do:
1826
1827   make tarball-dist
1828
1829
1830 To upload the package to Sourceforge, simply issue
1831
1832   make tarball-upload
1833
1834
1835 Goto the displayed URL and release the file publicly on Sourceforge.
1836
1837 -------------------------------------------------------------------------------
1838
1839 8.11. HP-UX 11
1840
1841 Ensure that you have the latest code version. Hence run:
1842
1843   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1844   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1845   cd current
1846
1847
1848 first. Run:
1849
1850   autoheader && autoconf && ./configure
1851
1852
1853 Then do FIXME.
1854
1855 -------------------------------------------------------------------------------
1856
1857 8.12. Amiga OS
1858
1859 Ensure that you have the latest code version. Hence run:
1860
1861   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1862   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1863   cd current
1864
1865
1866 first. Run:
1867
1868   autoheader && autoconf && ./configure
1869
1870
1871 Then do FIXME.
1872
1873 -------------------------------------------------------------------------------
1874
1875 8.13. AIX
1876
1877 Login to Sourceforge's compilefarm via ssh:
1878
1879   ssh cf.sourceforge.net
1880
1881
1882 Choose the right operating system. If you have downloaded Privoxy before:
1883
1884   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1885   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1886   cd current
1887
1888
1889 If not, please checkout Privoxy via CVS first. Run:
1890
1891   autoheader && autoconf && ./configure
1892
1893
1894 Then run:
1895
1896   make aix-dist
1897
1898
1899 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
1900 the Sourceforge machine (no ncftpput). You now have to manually upload the
1901 archive to Sourceforge's ftp server and release the file publicly.
1902
1903 -------------------------------------------------------------------------------
1904
1905 9. Contacting the developers, Bug Reporting and Feature Requests
1906
1907 We value your feedback. However, to provide you with the best support, please
1908 note:
1909
1910   * Use the Sourceforge Support Forum to get help:
1911
1912         http://sourceforge.net/tracker/?group_id=11118&atid=211118
1913
1914
1915   * Submit bugs only through our Sourceforge Bug Forum:
1916
1917         http://sourceforge.net/tracker/?group_id=11118&atid=111118.
1918
1919
1920     Make sure that the bug has not already been submitted. Please try to verify
1921     that it is a Privoxy bug, and not a browser or site bug first. If you are
1922     using your own custom configuration, please try the stock configs to see if
1923     the problem is a configuration related bug. And if not using the latest
1924     development snapshot, please try the latest one. Or even better, CVS
1925     sources. Please be sure to include the Privoxy/Junkbuster version,
1926     platform, browser, any pertinent log data, any other relevant details
1927     (please be specific) and, if possible, some way to reproduce the bug.
1928
1929   * Submit feature requests only through our Sourceforge feature request forum:
1930
1931         http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
1932
1933
1934   * You can also send feedback on websites that Privoxy has problems with. Please bookmark
1935     the following link: "Privoxy - Submit Filter Feedback"
1936     . Once you surf to a page with problems, use the
1937     bookmark to send us feedback. We will look into the issue as soon as possible.
1938
1939
1940   * For any other issues, feel free to use the mailing lists:
1941
1942         http://sourceforge.net/mail/?group_id=11118.
1943
1944
1945     Anyone interested in actively participating in development and related
1946     discussions can also join the appropriate mailing list. Archives are
1947     available, too.
1948
1949 -------------------------------------------------------------------------------
1950
1951 10. Copyright and History
1952
1953 10.1. Copyright
1954
1955 Privoxy is free software; you can redistribute it and/or modify it under the
1956 terms of the GNU General Public License as published by the Free Software
1957 Foundation; either version 2 of the License, or (at your option) any later
1958 version.
1959
1960 This program is distributed in the hope that it will be useful, but WITHOUT ANY
1961 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
1962 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
1963 is available from the Free Software Foundation, Inc, 59 Temple Place - Suite
1964 330, Boston, MA 02111-1307, USA.
1965
1966 You should have received a copy of the GNU General Public License along with
1967 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
1968 Place, Suite 330, Boston, MA 02111-1307 USA.
1969
1970 -------------------------------------------------------------------------------
1971
1972 10.2. History
1973
1974 Privoxy is evolved, and derived from, the Internet Junkbuster, with many
1975 improvments and enhancements over the original.
1976
1977 Junkbuster was originally written by Anonymous Coders and Junkbusters
1978 Corporation, and was released as free open-source software under the GNU GPL.
1979 Stefan Waldherr made many improvements, and started the SourceForge project
1980 Privoxy to rekindle development. There are now several active developers
1981 contributing. The last stable release of Junkbuster was v2.0.2, which has now
1982 grown whiskers ;-).
1983
1984 -------------------------------------------------------------------------------
1985
1986 11. See also
1987
1988 Other references and sites of interest to Privoxy users:
1989
1990 http://www.privoxy.org/, The Privoxy Home page.
1991
1992 http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy on
1993 Sourceforge.
1994
1995 http://p.p/, access Privoxy from your browser. Alternately, http://
1996 config.privoxy.org may work in some situations where the first does not.
1997
1998 http://p.p/, and select "actions file feedback system" to submit "misses" to
1999 the developers.
2000
2001 http://www.junkbusters.com/ht/en/cookies.html
2002
2003 http://www.waldherr.org/junkbuster/
2004
2005 http://privacy.net/analyze/
2006
2007 http://www.squid-cache.org/
2008
2009
2010