doc/text/developer-manual.txt

   1 Privoxy Developer Manual
   2
   3 By: Privoxy Developers
   4
   5 $Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 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. 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 and
  23 enhancements.
  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 of the User Manual on how to
  27 contact the developers.
  28
  29 -------------------------------------------------------------------------------
  30
  31 Table of Contents
  32 1. Introduction
  33 2. Quickstart to Privoxy Development
  34 3. Documentation Guidelines
  35 4. Coding Guidelines
  36
  37     4.1. Introduction
  38     4.2. Using Comments
  39
  40         4.2.1. Comment, Comment, Comment
  41         4.2.2. Use blocks for comments
  42         4.2.3. Keep Comments on their own line
  43         4.2.4. Comment each logical step
  44         4.2.5. Comment All Functions Thoroughly
  45         4.2.6. Comment at the end of braces if the content is more than one
  46             screen length
  47
  48     4.3. Naming Conventions
  49
  50         4.3.1. Variable Names
  51         4.3.2. Function Names
  52         4.3.3. Header file prototypes
  53         4.3.4. Enumerations, and #defines
  54         4.3.5. Constants
  55
  56     4.4. Using Space
  57
  58         4.4.1. Put braces on a line by themselves.
  59         4.4.2. ALL control statements should have a block
  60         4.4.3. Do not belabor/blow-up boolean expressions
  61         4.4.4. Use white space freely because it is free
  62         4.4.5. Don't use white space around structure operators
  63         4.4.6. Make the last brace of a function stand out
  64         4.4.7. Use 3 character indentions
  65
  66     4.5. Initializing
  67
  68         4.5.1. Initialize all variables
  69
  70     4.6. Functions
  71
  72         4.6.1. Name functions that return a boolean as a question.
  73         4.6.2. Always specify a return type for a function.
  74         4.6.3. Minimize function calls when iterating by using variables
  75         4.6.4. Pass and Return by Const Reference
  76         4.6.5. Pass and Return by Value
  77         4.6.6. Names of include files
  78         4.6.7. Provide multiple inclusion protection
  79         4.6.8. Use `extern "C"` when appropriate
  80         4.6.9. Where Possible, Use Forward Struct Declaration Instead of
  81             Includes
  82
  83     4.7. General Coding Practices
  84
  85         4.7.1. Turn on warnings
  86         4.7.2. Provide a default case for all switch statements
  87         4.7.3. Try to avoid falling through cases in a switch statement.
  88         4.7.4. Use 'long' or 'short' Instead of 'int'
  89         4.7.5. Don't mix size_t and other types
  90         4.7.6. Declare each variable and struct on its own line.
  91         4.7.7. Use malloc/zalloc sparingly
  92         4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
  93             'free'
  94         4.7.9. Add loaders to the `file_list' structure and in order
  95         4.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME
  96
  97     4.8. Addendum: Template for files and function comment blocks:
  98
  99 5. Version Control Guidelines
 100 6. Testing Guidelines
 101
 102     6.1. Testplan for releases
 103     6.2. Test reports
 104
 105 7. Releasing a new version
 106
 107     7.1. Before the Release
 108     7.2. Update the webserver
 109     7.3. SuSE or Red Hat
 110     7.4. OS/2
 111     7.5. Solaris
 112     7.6. Windows
 113     7.7. Debian
 114     7.8. Mac OSX
 115     7.9. FreeBSD
 116     7.10. Tarball
 117     7.11. HP-UX 11
 118     7.12. Amiga OS
 119     7.13. AIX
 120
 121 8. Contact the developers
 122 9. Copyright and History
 123 10. See also
 124
 125 1. Introduction
 126
 127 Privoxy, as an heir to Junkbuster, is an Open Source project and licensed under
 128 the GPL. As such, Privoxy development is potentially open to anyone who has the
 129 time, knowledge, and desire to contribute in any capacity. Our goals are simply
 130 to continue the mission, to improve Privoxy, and to make it available to as
 131 wide an audience as possible.
 132
 133 One does not have to be a programmer to contribute. Packaging, testing, and
 134 porting, are all important jobs as well.
 135
 136 -------------------------------------------------------------------------------
 137
 138 2. Quickstart to Privoxy Development
 139
 140 You'll need an account on Sourceforge to support our development. Mail your ID
 141 to the list and wait until a project manager has added you.
 142
 143 For the time being (read, this section is under construction), please note the
 144 following guidelines for changing stuff in the code. If it is
 145
 146  1. A bugfix / clean-up / cosmetic thing: shoot
 147
 148  2. A new feature that can be turned off: shoot
 149
 150  3. A clear improvement w/o side effects on other parts of the code: shoot
 151
 152  4. A matter of taste: ask the list
 153
 154  5. A major redesign of some part of the code: ask the list
 155
 156 -------------------------------------------------------------------------------
 157
 158 3. Documentation Guidelines
 159
 160 All formal documents are maintained in docbook SGML and located in the doc/
 161 source directory. You will need docbook and the docbook stylesheets (or
 162 comparable alternatives), and either jade or openjade installed in order to
 163 build docs from source. Currently there is user-manual, FAQ, and, of course
 164 this, the developer-manual in this format.
 165
 166 Other, less formal documents (e.g. README, LICENSE) are maintained as plain
 167 text files in the toplevel source directory.
 168
 169 Packagers are encouraged to include this documentation. For those without the
 170 ability to build the docs locally, text versions of each are kept in CVS. Or
 171 HTML versions can be downloaded from the www.privoxy.org website, which should
 172 be fairly current.
 173
 174 Formal documents are built with the Makefile targets of make dok, or
 175 alternately make redhat-dok. If you have problems, try both. The build process
 176 uses the document SGML sources in doc/source to update all text files in doc/
 177 text and to update all HTML documents in doc/webserver.
 178
 179 Documentation writers should please make sure documents build successfully
 180 before committing to CVS.
 181
 182 How do you update the webserver (i.e. the pages on privoxy.org)?
 183
 184  1. First, build the docs by running make dok (or alternately make redhat-dok).
 185
 186  2. Run make webserver which copies all files from doc/webserver to the
 187     sourceforge webserver via scp.
 188
 189 -------------------------------------------------------------------------------
 190
 191 4. Coding Guidelines
 192
 193 4.1. Introduction
 194
 195 This set of standards is designed to make our lives easier. It is developed
 196 with the simple goal of helping us keep the "new and improved Privoxy"
 197 consistent and reliable. Thus making maintenance easier and increasing chances
 198 of success of the project.
 199
 200 And that of course comes back to us as individuals. If we can increase our
 201 development and product efficiencies then we can solve more of the request for
 202 changes/improvements and in general feel good about ourselves. ;->
 203
 204 -------------------------------------------------------------------------------
 205
 206 4.2. Using Comments
 207
 208 4.2.1. Comment, Comment, Comment
 209
 210 Explanation:
 211
 212 Comment as much as possible without commenting the obvious. For example do not
 213 comment "aVariable is equal to bVariable". Instead explain why aVariable should
 214 be equal to the bVariable. Just because a person can read code does not mean
 215 they will understand why or what is being done. A reader may spend a lot more
 216 time figuring out what is going on when a simple comment or explanation would
 217 have prevented the extra research. Please help your brother IJB'ers out!
 218
 219 The comments will also help justify the intent of the code. If the comment
 220 describes something different than what the code is doing then maybe a
 221 programming error is occurring.
 222
 223 Example:
 224
 225 /* if page size greater than 1k ... */
 226 if ( PageLength() > 1024 )
 227 {
 228     ... "block" the page up ...
 229 }
 230
 231 /* if page size is small, send it in blocks */
 232 if ( PageLength() > 1024 )
 233 {
 234     ... "block" the page up ...
 235 }
 236
 237 This demonstrates 2 cases of "what not to do".  The first is a
 238 "syntax comment".  The second is a comment that does not fit what
 239 is actually being done.
 240
 241 -------------------------------------------------------------------------------
 242
 243 4.2.2. Use blocks for comments
 244
 245 Explanation:
 246
 247 Comments can help or they can clutter. They help when they are differentiated
 248 from the code they describe. One line comments do not offer effective
 249 separation between the comment and the code. Block identifiers do, by
 250 surrounding the code with a clear, definable pattern.
 251
 252 Example:
 253
 254 /*********************************************************************
 255  * This will stand out clearly in your code!
 256  *********************************************************************/
 257 if ( thisVariable == thatVariable )
 258 {
 259    DoSomethingVeryImportant();
 260 }
 261
 262
 263 /* unfortunately, this may not */
 264 if ( thisVariable == thatVariable )
 265 {
 266    DoSomethingVeryImportant();
 267 }
 268
 269
 270 if ( thisVariable == thatVariable ) /* this may not either */
 271 {
 272    DoSomethingVeryImportant();
 273 }
 274
 275 Exception:
 276
 277 If you are trying to add a small logic comment and do not wish to "disrubt" the
 278 flow of the code, feel free to use a 1 line comment which is NOT on the same
 279 line as the code.
 280
 281 -------------------------------------------------------------------------------
 282
 283 4.2.3. Keep Comments on their own line
 284
 285 Explanation:
 286
 287 It goes back to the question of readability. If the comment is on the same line
 288 as the code it will be harder to read than the comment that is on its own line.
 289
 290 There are three exceptions to this rule, which should be violated freely and
 291 often: during the definition of variables, at the end of closing braces, when
 292 used to comment parameters.
 293
 294 Example:
 295
 296 /*********************************************************************
 297  * This will stand out clearly in your code,
 298  * But the second example won't.
 299  *********************************************************************/
 300 if ( thisVariable == thatVariable )
 301 {
 302    DoSomethingVeryImportant();
 303 }
 304
 305 if ( thisVariable == thatVariable ) /*can you see me?*/
 306 {
 307    DoSomethingVeryImportant(); /*not easily*/
 308 }
 309
 310
 311 /*********************************************************************
 312  * But, the encouraged exceptions:
 313  *********************************************************************/
 314 int urls_read     = 0;     /* # of urls read + rejected */
 315 int urls_rejected = 0;     /* # of urls rejected */
 316
 317 if ( 1 == X )
 318 {
 319    DoSomethingVeryImportant();
 320 }
 321
 322
 323 short DoSomethingVeryImportant(
 324    short firstparam,   /* represents something */
 325    short nextparam     /* represents something else */ )
 326 {
 327    ...code here...
 328
 329 }   /* -END- DoSomethingVeryImportant */
 330
 331 -------------------------------------------------------------------------------
 332
 333 4.2.4. Comment each logical step
 334
 335 Explanation:
 336
 337 Logical steps should be commented to help others follow the intent of the
 338 written code and comments will make the code more readable.
 339
 340 If you have 25 lines of code without a comment, you should probably go back
 341 into it to see where you forgot to put one.
 342
 343 Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
 344 these are usually major logic containers.
 345
 346 -------------------------------------------------------------------------------
 347
 348 4.2.5. Comment All Functions Thoroughly
 349
 350 Explanation:
 351
 352 A reader of the code should be able to look at the comments just prior to the
 353 beginning of a function and discern the reason for its existence and the
 354 consequences of using it. The reader should not have to read through the code
 355 to determine if a given function is safe for a desired use. The proper
 356 information thoroughly presented at the introduction of a function not only
 357 saves time for subsequent maintenance or debugging, it more importantly aids in
 358 code reuse by allowing a user to determine the safety and applicability of any
 359 function for the problem at hand. As a result of such benefits, all functions
 360 should contain the information presented in the addendum section of this
 361 document.
 362
 363 -------------------------------------------------------------------------------
 364
 365 4.2.6. Comment at the end of braces if the content is more than one screen
 366 length
 367
 368 Explanation:
 369
 370 Each closing brace should be followed on the same line by a comment that
 371 describes the origination of the brace if the original brace is off of the
 372 screen, or otherwise far away from the closing brace. This will simplify the
 373 debugging, maintenance, and readability of the code.
 374
 375 As a suggestion , use the following flags to make the comment and its brace
 376 more readable:
 377
 378 use following a closing brace: } /* -END- if() or while () or etc... */
 379
 380 Example:
 381
 382 if ( 1 == X )
 383 {
 384    DoSomethingVeryImportant();
 385    ...some long list of commands...
 386 } /* -END- if x is 1 */
 387
 388 or:
 389
 390 if ( 1 == X )
 391 {
 392    DoSomethingVeryImportant();
 393    ...some long list of commands...
 394 } /* -END- if ( 1 == X ) */
 395
 396 -------------------------------------------------------------------------------
 397
 398 4.3. Naming Conventions
 399
 400 4.3.1. Variable Names
 401
 402 Explanation:
 403
 404 Use all lowercase, and seperate words via an underscore ('_'). Do not start an
 405 identifier with an underscore. (ANSI C reserves these for use by the compiler
 406 and system headers.) Do not use identifiers which are reserved in ANSI C++.
 407 (E.g. template, class, true, false, ...). This is in case we ever decide to
 408 port Privoxy to C++.
 409
 410 Example:
 411
 412 int ms_iis5_hack = 0;
 413
 414 Instead of:
 415
 416 int msiis5hack = 0; int msIis5Hack = 0;
 417
 418 -------------------------------------------------------------------------------
 419
 420 4.3.2. Function Names
 421
 422 Explanation:
 423
 424 Use all lowercase, and seperate words via an underscore ('_'). Do not start an
 425 identifier with an underscore. (ANSI C reserves these for use by the compiler
 426 and system headers.) Do not use identifiers which are reserved in ANSI C++.
 427 (E.g. template, class, true, false, ...). This is in case we ever decide to
 428 port Privoxy to C++.
 429
 430 Example:
 431
 432 int load_some_file( struct client_state *csp )
 433
 434 Instead of:
 435
 436 int loadsomefile( struct client_state *csp )
 437 int loadSomeFile( struct client_state *csp )
 438
 439 -------------------------------------------------------------------------------
 440
 441 4.3.3. Header file prototypes
 442
 443 Explanation:
 444
 445 Use a descriptive parameter name in the function prototype in header files. Use
 446 the same parameter name in the header file that you use in the c file.
 447
 448 Example:
 449
 450 (.h) extern int load_aclfile( struct client_state *csp );
 451 (.c) int load_aclfile( struct client_state *csp )
 452
 453 Instead of:
 454
 455 (.h) extern int load_aclfile( struct client_state * ); or
 456 (.h) extern int load_aclfile();
 457 (.c) int load_aclfile( struct client_state *csp )
 458
 459 -------------------------------------------------------------------------------
 460
 461 4.3.4. Enumerations, and #defines
 462
 463 Explanation:
 464
 465 Use all capital letters, with underscores between words. Do not start an
 466 identifier with an underscore. (ANSI C reserves these for use by the compiler
 467 and system headers.)
 468
 469 Example:
 470
 471 (enumeration) : enum Boolean { FALSE, TRUE };
 472 (#define) : #define DEFAULT_SIZE 100;
 473
 474 Note: We have a standard naming scheme for #defines that toggle a feature in
 475 the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word)
 476 description.
 477
 478 Example:
 479
 480 #define FEATURE_FORCE 1
 481
 482 #ifdef FEATURE_FORCE
 483 #define FORCE_PREFIX blah
 484 #endif /* def FEATURE_FORCE */
 485
 486 -------------------------------------------------------------------------------
 487
 488 4.3.5. Constants
 489
 490 Explanation:
 491
 492 Spell common words out entirely (do not remove vowels).
 493
 494 Use only widely-known domain acronyms and abbreviations. Capitalize all letters
 495 of an acronym.
 496
 497 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
 498 terminate a name with an underscore.
 499
 500 Example:
 501
 502 #define USE_IMAGE_LIST 1
 503
 504 Instead of:
 505
 506 #define USE_IMG_LST 1 or
 507 #define _USE_IMAGE_LIST 1 or
 508 #define USE_IMAGE_LIST_ 1 or
 509 #define use_image_list 1 or
 510 #define UseImageList 1
 511
 512 -------------------------------------------------------------------------------
 513
 514 4.4. Using Space
 515
 516 4.4.1. Put braces on a line by themselves.
 517
 518 Explanation:
 519
 520 The brace needs to be on a line all by itself, not at the end of the statement.
 521 Curly braces should line up with the construct that they're associated with.
 522 This practice makes it easier to identify the opening and closing braces for a
 523 block.
 524
 525 Example:
 526
 527 if ( this == that )
 528 {
 529    ...
 530 }
 531
 532 Instead of:
 533
 534 if ( this == that ) { ... }
 535
 536 or
 537
 538 if ( this == that ) { ... }
 539
 540 Note: In the special case that the if-statement is inside a loop, and it is
 541 trivial, i.e. it tests for a condidtion that is obvious from the purpose of the
 542 block, one-liners as above may optically preserve the loop structure and make
 543 it easier to read.
 544
 545 Status: developer-discrection.
 546
 547 Example exception:
 548
 549 while ( more lines are read )
 550 {
 551    /* Please document what is/is not a comment line here */
 552    if ( it's a comment ) continue;
 553
 554    do_something( line );
 555 }
 556
 557 -------------------------------------------------------------------------------
 558
 559 4.4.2. ALL control statements should have a block
 560
 561 Explanation:
 562
 563 Using braces to make a block will make your code more readable and less prone
 564 to error. All control statements should have a block defined.
 565
 566 Example:
 567
 568 if ( this == that )
 569 {
 570    DoSomething();
 571    DoSomethingElse();
 572 }
 573
 574 Instead of:
 575
 576 if ( this == that ) DoSomething(); DoSomethingElse();
 577
 578 or
 579
 580 if ( this == that ) DoSomething();
 581
 582 Note: The first example in "Instead of" will execute in a manner other than
 583 that which the developer desired (per indentation). Using code braces would
 584 have prevented this "feature". The "explanation" and "exception" from the point
 585 above also applies.
 586
 587 -------------------------------------------------------------------------------
 588
 589 4.4.3. Do not belabor/blow-up boolean expressions
 590
 591 Example:
 592
 593 structure->flag = ( condition );
 594
 595 Instead of:
 596
 597 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
 598
 599 Note: The former is readable and consice. The later is wordy and inefficient.
 600 Please assume that any developer new to the project has at least a "good"
 601 knowledge of C/C++. (Hope I do not offend by that last comment ... 8-)
 602
 603 -------------------------------------------------------------------------------
 604
 605 4.4.4. Use white space freely because it is free
 606
 607 Explanation:
 608
 609 Make it readable. The notable exception to using white space freely is listed
 610 in the next guideline.
 611
 612 Example:
 613
 614 int firstValue   = 0;
 615 int someValue    = 0;
 616 int anotherValue = 0;
 617 int thisVariable = 0;
 618
 619 if ( thisVariable == thatVariable )
 620
 621 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
 622
 623 -------------------------------------------------------------------------------
 624
 625 4.4.5. Don't use white space around structure operators
 626
 627 Explanation:
 628
 629 - structure pointer operator ( "->" ) - member operator ( "." ) - functions and
 630 parentheses
 631
 632 It is a general coding practice to put pointers, references, and function
 633 parentheses next to names. With spaces, the connection between the object and
 634 variable/function name is not as clear.
 635
 636 Example:
 637
 638 aStruct->aMember;
 639 aStruct.aMember;
 640 FunctionName();
 641
 642 Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
 643
 644 -------------------------------------------------------------------------------
 645
 646 4.4.6. Make the last brace of a function stand out
 647
 648 Example:
 649
 650 int function1( ... )
 651 {
 652    ...code...
 653    return( retCode );
 654
 655 }   /* -END- function1 */
 656
 657
 658 int function2( ... )
 659 {
 660 }   /* -END- function2 */
 661
 662 Instead of:
 663
 664 int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { }
 665
 666 Note: Use 1 blank line before the closing brace and 2 lines afterwards. This
 667 makes the end of function standout to the most casual viewer. Although function
 668 comments help seperate functions, this is still a good coding practice. In
 669 fact, I follow these rules when using blocks in "for", "while", "do" loops, and
 670 long if {} statements too. After all whitespace is free!
 671
 672 Status: developer-discrection on the number of blank lines. Enforced is the end
 673 of function comments.
 674
 675 -------------------------------------------------------------------------------
 676
 677 4.4.7. Use 3 character indentions
 678
 679 Explanation:
 680
 681 If some use 8 character TABs and some use 3 character TABs, the code can look *
 682 very* ragged. So use 3 character indentions only. If you like to use TABs, pass
 683 your code through a filter such as "expand -t3" before checking in your code.
 684
 685 Example:
 686
 687 static const char * const url_code_map[256] =
 688 {
 689    NULL, ...
 690 };
 691
 692
 693 int function1( ... )
 694 {
 695    if ( 1 )
 696    {
 697       return( ALWAYS_TRUE );
 698    }
 699    else
 700    {
 701       return( HOW_DID_YOU_GET_HERE );
 702    }
 703
 704    return( NEVER_GETS_HERE );
 705
 706 }
 707
 708 -------------------------------------------------------------------------------
 709
 710 4.5. Initializing
 711
 712 4.5.1. Initialize all variables
 713
 714 Explanation:
 715
 716 Do not assume that the variables declared will not be used until after they
 717 have been assigned a value somewhere else in the code. Remove the chance of
 718 accidentally using an unassigned variable.
 719
 720 Example:
 721
 722 short anShort = 0;
 723 float aFloat  = 0;
 724 struct *ptr = NULL;
 725
 726 Note: It is much easier to debug a SIGSEGV if the message says you are trying
 727 to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a
 728 SIGSEV vs. arrayPtr[0].
 729
 730 Status: developer-discrection if and only if the variable is assigned a value
 731 "shortly after" declaration.
 732
 733 -------------------------------------------------------------------------------
 734
 735 4.6. Functions
 736
 737 4.6.1. Name functions that return a boolean as a question.
 738
 739 Explanation:
 740
 741 Value should be phrased as a question that would logically be answered as a
 742 true or false statement
 743
 744 Example:
 745
 746 ShouldWeBlockThis();
 747 ContainsAnImage();
 748 IsWebPageBlank();
 749
 750 -------------------------------------------------------------------------------
 751
 752 4.6.2. Always specify a return type for a function.
 753
 754 Explanation:
 755
 756 The default return for a function is an int. To avoid ambiguity, create a
 757 return for a function when the return has a purpose, and create a void return
 758 type if the function does not need to return anything.
 759
 760 -------------------------------------------------------------------------------
 761
 762 4.6.3. Minimize function calls when iterating by using variables
 763
 764 Explanation:
 765
 766 It is easy to write the following code, and a clear argument can be made that
 767 the code is easy to understand:
 768
 769 Example:
 770
 771 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
 772 {
 773    ....
 774 }
 775
 776 Note: Unfortunately, this makes a function call for each and every iteration.
 777 This increases the overhead in the program, because the compiler has to look up
 778 the function each time, call it, and return a value. Depending on what occurs
 779 in the blockListLength() call, it might even be creating and destroying
 780 structures with each iteration, even though in each case it is comparing "cnt"
 781 to the same value, over and over. Remember too - even a call to blockListLength
 782 () is a function call, with the same overhead.
 783
 784 Instead of using a function call during the iterations, assign the value to a
 785 variable, and evaluate using the variable.
 786
 787 Example:
 788
 789 size_t len = blockListLength();
 790
 791 for ( size_t cnt = 0; cnt < len; cnt ++ )
 792 {
 793    ....
 794 }
 795
 796 Exceptions: if the value of blockListLength() *may* change or could *
 797 potentially* change, then you must code the function call in the for/while
 798 loop.
 799
 800 -------------------------------------------------------------------------------
 801
 802 4.6.4. Pass and Return by Const Reference
 803
 804 Explanation:
 805
 806 This allows a developer to define a const pointer and call your function. If
 807 your function does not have the const keyword, we may not be able to use your
 808 function. Consider strcmp, if it were defined as: extern int strcmp( char *s1,
 809 char *s2 );
 810
 811 I could then not use it to compare argv's in main: int main( int argc, const
 812 char *argv[] ) { strcmp( argv[0], "privoxy" ); }
 813
 814 Both these pointers are *const*! If the c runtime library maintainers do it, we
 815 should too.
 816
 817 -------------------------------------------------------------------------------
 818
 819 4.6.5. Pass and Return by Value
 820
 821 Explanation:
 822
 823 Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes
 824 or less). Aka, a function declaration like: int load_aclfile( struct
 825 client_state csp )
 826
 827 would not work. So, to be consistent, we should declare all prototypes with
 828 "pass by value": int load_aclfile( struct client_state *csp )
 829
 830 -------------------------------------------------------------------------------
 831
 832 4.6.6. Names of include files
 833
 834 Explanation:
 835
 836 Your include statements should contain the file name without a path. The path
 837 should be listed in the Makefile, using -I as processor directive to search the
 838 indicated paths. An exception to this would be for some proprietary software
 839 that utilizes a partial path to distinguish their header files from system or
 840 other header files.
 841
 842 Example:
 843
 844 #include <iostream.h>     /* This is not a local include */
 845 #include "config.h"       /* This IS a local include */
 846
 847 Exception:
 848
 849 /* This is not a local include, but requires a path element. */
 850 #include <sys/fileName.h>
 851
 852 Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
 853 This duplicates the #include "file.h" behaviour.
 854
 855 -------------------------------------------------------------------------------
 856
 857 4.6.7. Provide multiple inclusion protection
 858
 859 Explanation:
 860
 861 Prevents compiler and linker errors resulting from redefinition of items.
 862
 863 Wrap each header file with the following syntax to prevent multiple inclusions
 864 of the file. Of course, replace PROJECT_H with your file name, with "." Changed
 865 to "_", and make it uppercase.
 866
 867 Example:
 868
 869 #ifndef PROJECT_H_INCLUDED
 870 #define PROJECT_H_INCLUDED
 871  ...
 872 #endif /* ndef PROJECT_H_INCLUDED */
 873
 874 -------------------------------------------------------------------------------
 875
 876 4.6.8. Use `extern "C"` when appropriate
 877
 878 Explanation:
 879
 880 If our headers are included from C++, they must declare our functions as
 881 `extern "C"`. This has no cost in C, but increases the potential re-usability
 882 of our code.
 883
 884 Example:
 885
 886 #ifdef __cplusplus
 887 extern "C"
 888 {
 889 #endif /* def __cplusplus */
 890
 891 ... function definitions here ...
 892
 893 #ifdef __cplusplus
 894 }
 895 #endif /* def __cplusplus */
 896
 897 -------------------------------------------------------------------------------
 898
 899 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
 900
 901 Explanation:
 902
 903 Useful in headers that include pointers to other struct's. Modifications to
 904 excess header files may cause needless compiles.
 905
 906 Example:
 907
 908 /*********************************************************************
 909  * We're avoiding an include statement here!
 910  *********************************************************************/
 911 struct file_list;
 912 extern file_list *xyz;
 913
 914 Note: If you declare "file_list xyz;" (without the pointer), then including the
 915 proper header file is necessary. If you only want to prototype a pointer,
 916 however, the header file is unneccessary.
 917
 918 Status: Use with discrection.
 919
 920 -------------------------------------------------------------------------------
 921
 922 4.7. General Coding Practices
 923
 924 4.7.1. Turn on warnings
 925
 926 Explanation
 927
 928 Compiler warnings are meant to help you find bugs. You should turn on as many
 929 as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as
 930 possible.
 931
 932 -------------------------------------------------------------------------------
 933
 934 4.7.2. Provide a default case for all switch statements
 935
 936 Explanation:
 937
 938 What you think is guaranteed is never really guaranteed. The value that you
 939 don't think you need to check is the one that someday will be passed. So, to
 940 protect yourself from the unknown, always have a default step in a switch
 941 statement.
 942
 943 Example:
 944
 945 switch( hash_string( cmd ) )
 946 {
 947    case hash_actions_file :
 948       ... code ...
 949       break;
 950
 951    case hash_confdir :
 952       ... code ...
 953       break;
 954
 955    default :
 956       log_error( ... );
 957       ... anomly code goes here ...
 958       continue; / break; / exit( 1 ); / etc ...
 959
 960 } /* end switch( hash_string( cmd ) ) */
 961
 962 Note: If you already have a default condition, you are obviously exempt from
 963 this point. Of note, most of the WIN32 code calls `DefWindowProc' after the
 964 switch statement. This API call *should* be included in a default statement.
 965
 966 Another Note: This is not so much a readability issue as a robust programming
 967 issue. The "anomly code goes here" may be no more than a print to the STDERR
 968 stream (as in load_config). Or it may really be an ABEND condition.
 969
 970 Status: Programmer discretion is advised.
 971
 972 -------------------------------------------------------------------------------
 973
 974 4.7.3. Try to avoid falling through cases in a switch statement.
 975
 976 Explanation:
 977
 978 In general, you will want to have a 'break' statement within each 'case' of a
 979 switch statement. This allows for the code to be more readable and
 980 understandable, and furthermore can prevent unwanted surprises if someone else
 981 later gets creative and moves the code around.
 982
 983 The language allows you to plan the fall through from one case statement to
 984 another simply by omitting the break statement within the case statement. This
 985 feature does have benefits, but should only be used in rare cases. In general,
 986 use a break statement for each case statement.
 987
 988 If you choose to allow fall through, you should comment both the fact of the
 989 fall through and reason why you felt it was necessary.
 990
 991 -------------------------------------------------------------------------------
 992
 993 4.7.4. Use 'long' or 'short' Instead of 'int'
 994
 995 Explanation:
 996
 997 On 32-bit platforms, int usually has the range of long. On 16-bit platforms,
 998 int has the range of short.
 999
1000 Status: open-to-debate. In the case of most FSF projects (including X/
1001 GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I
1002 forget the exact typedefs now). Should we add these to IJB now that we have a
1003 "configure" script?
1004
1005 -------------------------------------------------------------------------------
1006
1007 4.7.5. Don't mix size_t and other types
1008
1009 Explanation:
1010
1011 The type of size_t varies across platforms. Do not make assumptions about
1012 whether it is signed or unsigned, or about how long it is. Do not compare a
1013 size_t against another variable of a different type (or even against a
1014 constant) without casting one of the values. Try to avoid using size_t if you
1015 can.
1016
1017 -------------------------------------------------------------------------------
1018
1019 4.7.6. Declare each variable and struct on its own line.
1020
1021 Explanation:
1022
1023 It can be tempting to declare a series of variables all on one line. Don't.
1024
1025 Example:
1026
1027 long a = 0;
1028 long b = 0;
1029 long c = 0;
1030
1031 Instead of:
1032
1033 long a, b, c;
1034
1035 Explanation: - there is more room for comments on the individual variables -
1036 easier to add new variables without messing up the original ones - when
1037 searching on a variable to find its type, there is less clutter to "visually"
1038 eliminate
1039
1040 Exceptions: when you want to declare a bunch of loop variables or other trivial
1041 variables; feel free to declare them on 1 line. You should, although, provide a
1042 good comment on their functions.
1043
1044 Status: developer-discrection.
1045
1046 -------------------------------------------------------------------------------
1047
1048 4.7.7. Use malloc/zalloc sparingly
1049
1050 Explanation:
1051
1052 Create a local stuct (on the stack) if the variable will live and die within
1053 the context of one function call.
1054
1055 Only "malloc" a struct (on the heap) if the variable's life will extend beyond
1056 the context of one function call.
1057
1058 Example:
1059
1060 If a function creates a struct and stores a pointer to it in a
1061 list, then it should definately be allocated via `malloc'.
1062
1063 -------------------------------------------------------------------------------
1064
1065 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1066
1067 Explanation:
1068
1069 If you have to "malloc" an instance, you are responsible for insuring that the
1070 instance is `free'd, even if the deallocation event falls within some other
1071 programmer's code. You are also responsible for ensuring that deletion is
1072 timely (i.e. not too soon, not too late). This is known as "low-coupling" and
1073 is a "good thing (tm)". You may need to offer a free/unload/destuctor type
1074 function to accomodate this.
1075
1076 Example:
1077
1078 int load_re_filterfile( struct client_state *csp ) { ... }
1079 static void unload_re_filterfile( void *f ) { ... }
1080
1081 Exceptions:
1082
1083 The developer cannot be expected to provide `free'ing functions for C run-time
1084 library functions ... such as `strdup'.
1085
1086 Status: developer-discrection. The "main" use of this standard is for
1087 allocating and freeing data structures (complex or nested).
1088
1089 -------------------------------------------------------------------------------
1090
1091 4.7.9. Add loaders to the `file_list' structure and in order
1092
1093 Explanation:
1094
1095 I have ordered all of the "blocker" file code to be in alpha order. It is
1096 easier to add/read new blockers when you expect a certain order.
1097
1098 Note: It may appear that the alpha order is broken in places by POPUP tests
1099 coming before PCRS tests. But since POPUPs can also be referred to as
1100 KILLPOPUPs, it is clear that it should come first.
1101
1102 -------------------------------------------------------------------------------
1103
1104 4.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME
1105
1106 Explanation:
1107
1108 If you have enough confidence in new code or confidence in your changes, but
1109 are not *quite* sure of the reprocussions, add this:
1110
1111 /* FIXME: this code has a logic error on platform XYZ, * attempthing to fix */
1112 #ifdef PLATFORM ...changed code here... #endif
1113
1114 or:
1115
1116 /* FIXME: I think the original author really meant this... */ ...changed code
1117 here...
1118
1119 or:
1120
1121 /* FIXME: new code that *may* break something else... */ ...new code here...
1122
1123 Note: If you make it clear that this may or may not be a "good thing (tm)", it
1124 will be easier to identify and include in the project (or conversly exclude
1125 from the project).
1126
1127 -------------------------------------------------------------------------------
1128
1129 4.8. Addendum: Template for files and function comment blocks:
1130
1131 Example for file comments:
1132
1133 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $";
1134 /*********************************************************************
1135  *
1136  * File        :  $Source$
1137  *
1138  * Purpose     :  (Fill me in with a good description!)
1139  *
1140  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1141  *                Privoxy team. http://www.privoxy.org/
1142  *
1143  *                Based on the Internet Junkbuster originally written
1144  *                by and Copyright (C) 1997 Anonymous Coders and
1145  *                Junkbusters Corporation.  http://www.junkbusters.com
1146  *
1147  *                This program is free software; you can redistribute it
1148  *                and/or modify it under the terms of the GNU General
1149  *                Public License as published by the Free Software
1150  *                Foundation; either version 2 of the License, or (at
1151  *                your option) any later version.
1152  *
1153  *                This program is distributed in the hope that it will
1154  *                be useful, but WITHOUT ANY WARRANTY; without even the
1155  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1156  *                PARTICULAR PURPOSE.  See the GNU General Public
1157  *                License for more details.
1158  *
1159  *                The GNU General Public License should be included with
1160  *                this file.  If not, you can view it at
1161  *                http://www.gnu.org/copyleft/gpl.html
1162  *                or write to the Free Software Foundation, Inc., 59
1163  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1164  *
1165  * Revisions   :
1166  *    $Log$
1167  *
1168  *********************************************************************/
1169
1170
1171 #include "config.h"
1172
1173    ...necessary include files for us to do our work...
1174
1175 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1176
1177 Note: This declares the rcs variables that should be added to the
1178 "show-proxy-args" page. If this is a brand new creation by you, you are free to
1179 change the "Copyright" section to represent the rights you wish to maintain.
1180
1181 Note: The formfeed character that is present right after the comment flower box
1182 is handy for (X|GNU)Emacs users to skip the verbige and get to the heart of the
1183 code (via `forward-page' and `backward-page'). Please include it if you can.
1184
1185 Example for file header comments:
1186
1187 #ifndef _FILENAME_H
1188 #define _FILENAME_H
1189 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $"
1190 /*********************************************************************
1191  *
1192  * File        :  $Source$
1193  *
1194  * Purpose     :  (Fill me in with a good description!)
1195  *
1196  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1197  *                Privoxy team. http://www.privoxy.org/
1198  *
1199  *                Based on the Internet Junkbuster originally written
1200  *                by and Copyright (C) 1997 Anonymous Coders and
1201  *                Junkbusters Corporation.  http://www.junkbusters.com
1202  *
1203  *                This program is free software; you can redistribute it
1204  *                and/or modify it under the terms of the GNU General
1205  *                Public License as published by the Free Software
1206  *                Foundation; either version 2 of the License, or (at
1207  *                your option) any later version.
1208  *
1209  *                This program is distributed in the hope that it will
1210  *                be useful, but WITHOUT ANY WARRANTY; without even the
1211  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1212  *                PARTICULAR PURPOSE.  See the GNU General Public
1213  *                License for more details.
1214  *
1215  *                The GNU General Public License should be included with
1216  *                this file.  If not, you can view it at
1217  *                http://www.gnu.org/copyleft/gpl.html
1218  *                or write to the Free Software Foundation, Inc., 59
1219  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1220  *
1221  * Revisions   :
1222  *    $Log$
1223  *
1224  *********************************************************************/
1225
1226
1227 #include "project.h"
1228
1229 #ifdef __cplusplus
1230 extern "C" {
1231 #endif
1232
1233    ... function headers here ...
1234
1235
1236 /* Revision control strings from this header and associated .c file */
1237 extern const char FILENAME_rcs[];
1238 extern const char FILENAME_h_rcs[];
1239
1240
1241 #ifdef __cplusplus
1242 } /* extern "C" */
1243 #endif
1244
1245 #endif /* ndef _FILENAME_H */
1246
1247 /*
1248   Local Variables:
1249   tab-width: 3
1250   end:
1251 */
1252
1253 Example for function comments:
1254
1255 /*********************************************************************
1256  *
1257  * Function    :  FUNCTION_NAME
1258  *
1259  * Description :  (Fill me in with a good description!)
1260  *
1261  * parameters  :
1262  *          1  :  param1 = pointer to an important thing
1263  *          2  :  x      = pointer to something else
1264  *
1265  * Returns     :  0 => Ok, everything else is an error.
1266  *
1267  *********************************************************************/
1268 int FUNCTION_NAME( void *param1, const char *x )
1269 {
1270    ...
1271    return( 0 );
1272
1273 }
1274
1275 Note: If we all follow this practice, we should be able to parse our code to
1276 create a "self-documenting" web page.
1277
1278 -------------------------------------------------------------------------------
1279
1280 5. Version Control Guidelines
1281
1282 To be filled. note on cvs comments. Don't only comment what you did, but also
1283 why you did it!
1284
1285 -------------------------------------------------------------------------------
1286
1287 6. Testing Guidelines
1288
1289 To be filled.
1290
1291 -------------------------------------------------------------------------------
1292
1293 6.1. Testplan for releases
1294
1295 Explain release numbers. major, minor. developer releases. etc.
1296
1297  1. Remove any existing rpm with rpm -e
1298
1299  2. Remove any file that was left over. This includes (but is not limited to)
1300
1301       + /var/log/privoxy
1302
1303       + /etc/privoxy
1304
1305       + /usr/sbin/privoxy
1306
1307       + /etc/init.d/privoxy
1308
1309       + /usr/doc/privoxy*
1310
1311  3. Install the rpm. Any error messages?
1312
1313  4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
1314     privoxy stop). Reboot your machine. Does autostart work?
1315
1316  5. Start browsing. Does Privoxy work? Logfile written?
1317
1318  6. Remove the rpm. Any error messages? All files removed?
1319
1320 -------------------------------------------------------------------------------
1321
1322 6.2. Test reports
1323
1324 Please submit test reports only with the test form at sourceforge. Three simple
1325 steps:
1326
1327   * Select category: the distribution you test on.
1328
1329   * Select group: the version of Privoxy that we are about to release.
1330
1331   * Fill the Summary and Detailed Description with something intelligent (keep
1332     it short and precise).
1333
1334 Do not mail to the mailinglist (we cannot keep track on issues there).
1335
1336 -------------------------------------------------------------------------------
1337
1338 7. Releasing a new version
1339
1340 To minimize trouble with distribution contents, webpage errors and the like, we
1341 strongly encourage you to follow this section if you prepare a new release of
1342 code or new pages on the webserver.
1343
1344 The following programs are required to follow this process: ncftpput (ncftp),
1345 scp (ssh), gmake (GNU's version of make), autoconf, cvs, ???.
1346
1347 -------------------------------------------------------------------------------
1348
1349 7.1. Before the Release
1350
1351 The following must be done by one of the developers prior to each new release:
1352
1353   * Make sure that everybody who has worked on the code in the last couple of
1354     days has had a chance to yell "no!" in case they have pending changes/fixes
1355     in their pipelines.
1356
1357   * Increment the version number in configure.in in CVS. Also, the RPM release
1358     number in configure.in. Do NOT touch version information after export from
1359     CVS. All packages will use the version and release data from configure.in.
1360     Local files should not be changed, except prior to a CVS commit!!! This way
1361     we are all on the same page!
1362
1363   * If the default actionsfile has changed since last release, bump up its
1364     version info in this line:
1365
1366       {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1367
1368
1369     Then change the version info in doc/webserver/actions/index.php, line:
1370     '$required_actions_file_version = "A.B";'
1371
1372   * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z" (where
1373     X = major, Y = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z
1374     (won't work) etc.
1375
1376   * The first package uploaded should be the official "tarball" release. This
1377     is built with the "make tarball-dist" Makefile target, and then can be
1378     uploaded with "make tarball-upload" (see below).
1379
1380 -------------------------------------------------------------------------------
1381
1382 7.2. Update the webserver
1383
1384 All files must be group-readable and group-writable (or no one else will be
1385 able to change them). To update the webserver, create any pages locally in the
1386 doc/webserver directory (or create new directories under doc/webserver), then
1387 do
1388
1389   make webserver
1390
1391
1392 Note that "make dok" (or "make redhat-dok") creates doc/webserver/user-manual,
1393 doc/webserver/developer-manual, doc/webserver/faq and doc/webserver/man-page
1394 automatically.
1395
1396 Please do NOT use any other means of transferring files to the webserver. "make
1397 webserver" not only uploads, but will make sure that the appropriate
1398 permissions are preserved for shared group access.
1399
1400 -------------------------------------------------------------------------------
1401
1402 7.3. SuSE or Red Hat
1403
1404 Ensure that you have the latest code version. Hence run:
1405
1406   cd current
1407   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1408   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1409
1410
1411 first.
1412
1413   autoheader && autoconf && ./configure
1414
1415
1416 Then do
1417
1418   make suse-dist or make redhat-dist
1419
1420
1421 To upload the package to Sourceforge, simply issue
1422
1423   make suse-upload or make redhat-upload
1424
1425
1426 Go to the displayed URL and release the file publicly on Sourceforge.
1427
1428 -------------------------------------------------------------------------------
1429
1430 7.4. OS/2
1431
1432 Ensure that you have the latest code version. Hence run:
1433
1434   cd current
1435   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1436   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1437
1438
1439 first.
1440
1441   autoheader && autoconf && ./configure
1442
1443
1444 Then do FIXME.
1445
1446 -------------------------------------------------------------------------------
1447
1448 7.5. Solaris
1449
1450 Login to Sourceforge's compilefarm via ssh
1451
1452   ssh cf.sourceforge.net
1453
1454
1455 Choose the right operating system (not the Debian one). If you have downloaded
1456 Privoxy before,
1457
1458   cd current
1459   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1460   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1461
1462
1463 If not, please checkout Privoxy via CVS first. Run:
1464
1465   autoheader && autoconf && ./configure
1466
1467
1468 Then run
1469
1470   gmake solaris-dist
1471
1472
1473 which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
1474 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1475 archive to Sourceforge's ftp server and release the file publicly.
1476
1477 -------------------------------------------------------------------------------
1478
1479 7.6. Windows
1480
1481 Ensure that you have the latest code version. Hence run
1482
1483   cd current
1484   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1485   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1486
1487
1488 Run:
1489
1490   autoheader && autoconf && ./configure
1491
1492
1493 Then do FIXME.
1494
1495 -------------------------------------------------------------------------------
1496
1497 7.7. Debian
1498
1499 Ensure that you have the latest code version. Hence run:
1500
1501   cd current
1502   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1503   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1504
1505
1506 first. Run:
1507
1508   autoheader && autoconf && ./configure
1509
1510
1511 Then do FIXME.
1512
1513 -------------------------------------------------------------------------------
1514
1515 7.8. Mac OSX
1516
1517 Login to Sourceforge's compilefarm via ssh
1518
1519   ssh cf.sourceforge.net
1520
1521
1522 Choose the right operating system. If you have downloaded Privoxy before,
1523
1524   cd current
1525   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1526   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1527
1528
1529 If not, please checkout Privoxy via CVS first. Run:
1530
1531  autoheader && autoconf && ./configure
1532
1533
1534 Then run:
1535
1536   make macosx-dist
1537
1538
1539 which creates a gzip'ed tar archive. Sadly, you cannot use make macosx-upload
1540 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1541 archive to Sourceforge's ftp server and release the file publicly.
1542
1543 -------------------------------------------------------------------------------
1544
1545 7.9. FreeBSD
1546
1547 Change the version number of Privoxy in the configure.in file. Run:
1548
1549   autoheader && autoconf && ./configure
1550
1551
1552 Then ...
1553
1554 Login to Sourceforge's compilefarm via ssh:
1555
1556   ssh cf.sourceforge.net
1557
1558
1559 Choose the right operating system. If you have downloaded Privoxy before,
1560
1561   cd current
1562   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1563   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1564
1565
1566 If not, please checkout Privoxy via CVS first. Run:
1567
1568   autoheader && autoconf && ./configure
1569
1570
1571 Then run:
1572
1573   gmake freebsd-dist
1574
1575
1576 which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
1577 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1578 archive to Sourceforge's ftp server and release the file publicly.
1579
1580 -------------------------------------------------------------------------------
1581
1582 7.10. Tarball
1583
1584 Ensure that you have the latest code version. Hence run:
1585
1586   cd current
1587   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1588   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1589
1590
1591 first. Run:
1592
1593   make clobber
1594   autoheader && autoconf && ./configure
1595
1596
1597 Then do:
1598
1599   make tarball-dist
1600
1601
1602 To upload the package to Sourceforge, simply issue
1603
1604   make tarball-upload
1605
1606
1607 Goto the displayed URL and release the file publicly on Sourceforge.
1608
1609 -------------------------------------------------------------------------------
1610
1611 7.11. HP-UX 11
1612
1613 Ensure that you have the latest code version. Hence run:
1614
1615   cd current
1616   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1617   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1618
1619
1620 first. Run:
1621
1622   autoheader && autoconf && ./configure
1623
1624
1625 Then do FIXME.
1626
1627 -------------------------------------------------------------------------------
1628
1629 7.12. Amiga OS
1630
1631 Ensure that you have the latest code version. Hence run:
1632
1633   cd current
1634   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1635   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1636
1637
1638 first. Run:
1639
1640   autoheader && autoconf && ./configure
1641
1642
1643 Then do FIXME.
1644
1645 -------------------------------------------------------------------------------
1646
1647 7.13. AIX
1648
1649 Login to Sourceforge's compilefarm via ssh:
1650
1651   ssh cf.sourceforge.net
1652
1653
1654 Choose the right operating system. If you have downloaded Privoxy before:
1655
1656   cd current
1657   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1658   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1659
1660
1661 If not, please checkout Privoxy via CVS first. Run:
1662
1663   autoheader && autoconf && ./configure
1664
1665
1666 Then run:
1667
1668   make aix-dist
1669
1670
1671 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
1672 the Sourceforge machine (no ncftpput). You now have to manually upload the
1673 archive to Sourceforge's ftp server and release the file publicly.
1674
1675 -------------------------------------------------------------------------------
1676
1677 8. Contact the developers
1678
1679 Please see the contact page in the user-manual for details.
1680
1681 -------------------------------------------------------------------------------
1682
1683 9. Copyright and History
1684
1685 Please see the user-manual for information on Copyright and History.
1686
1687 -------------------------------------------------------------------------------
1688
1689 10. See also
1690
1691 Please see the user-manual for others references.
1692