1 Privoxy Developer Manual
3 [Copyright[ (c) 2001-2008 by Privoxy Developers]]
5 $Id: developer-manual.txt,v 1.43 2008/01/19 21:41:36 hal9 Exp $
7 The developer manual provides guidance on coding, testing, packaging,
8 documentation and other issues of importance to those involved with
9 Privoxy development. It is mandatory (and helpful!) reading for anyone who
10 wants to join the team. Note that it's currently out of date and may not
11 be entirely correct. As always, patches are welcome.
13 Please note that this document is constantly evolving. This copy
14 represents the state at the release of version 3.0.8. You can find the
15 latest version of the this manual at
16 http://www.privoxy.org/developer-manual/. Please see the Contact section
17 on how to contact the developers.
19 --------------------------------------------------------------------------
25 1.1. Quickstart to Privoxy Development
33 2.3. CVS Commit Guidelines
35 3. Documentation Guidelines
37 3.1. Quickstart to Docbook and SGML
39 3.2. Privoxy Documentation Style
41 3.3. Privoxy Custom Entities
49 4.2.1. Comment, Comment, Comment
51 4.2.2. Use blocks for comments
53 4.2.3. Keep Comments on their own line
55 4.2.4. Comment each logical step
57 4.2.5. Comment All Functions Thoroughly
59 4.2.6. Comment at the end of braces if the
60 content is more than one screen length
62 4.3. Naming Conventions
68 4.3.3. Header file prototypes
70 4.3.4. Enumerations, and #defines
76 4.4.1. Put braces on a line by themselves.
78 4.4.2. ALL control statements should have a
81 4.4.3. Do not belabor/blow-up boolean
84 4.4.4. Use white space freely because it is free
86 4.4.5. Don't use white space around structure
89 4.4.6. Make the last brace of a function stand
92 4.4.7. Use 3 character indentions
96 4.5.1. Initialize all variables
100 4.6.1. Name functions that return a boolean as a
103 4.6.2. Always specify a return type for a
106 4.6.3. Minimize function calls when iterating by
109 4.6.4. Pass and Return by Const Reference
111 4.6.5. Pass and Return by Value
113 4.6.6. Names of include files
115 4.6.7. Provide multiple inclusion protection
117 4.6.8. Use `extern "C"` when appropriate
119 4.6.9. Where Possible, Use Forward Struct
120 Declaration Instead of Includes
122 4.7. General Coding Practices
124 4.7.1. Turn on warnings
126 4.7.2. Provide a default case for all switch
129 4.7.3. Try to avoid falling through cases in a
132 4.7.4. Use 'long' or 'short' Instead of 'int'
134 4.7.5. Don't mix size_t and other types
136 4.7.6. Declare each variable and struct on its
139 4.7.7. Use malloc/zalloc sparingly
141 4.7.8. The Programmer Who Uses 'malloc' is
142 Responsible for Ensuring 'free'
144 4.7.9. Add loaders to the `file_list' structure
147 4.7.10. "Uncertain" new code and/or changes to
148 existing code, use FIXME or XXX
150 4.8. Addendum: Template for files and function comment
153 5. Testing Guidelines
155 5.1. Testplan for releases
159 6. Releasing a New Version
163 6.2. Before the Release: Freeze
165 6.3. Building and Releasing the Packages
167 6.3.1. Note on Privoxy Packaging
169 6.3.2. Source Tarball
171 6.3.3. SuSE, Conectiva or Red Hat RPM
191 6.4. Uploading and Releasing Your Package
193 6.5. After the Release
195 7. Update the Webserver
197 8. Contacting the developers, Bug Reporting and Feature Requests
201 8.2. Reporting Problems
203 8.2.1. Reporting Ads or Other Configuration
206 8.2.2. Reporting Bugs
208 8.3. Request New Features
212 9. Privoxy Copyright, License and History
222 Privoxy, as an heir to Junkbuster, is a Free Software project and the code
223 is licensed under the GPL. As such, Privoxy development is potentially
224 open to anyone who has the time, knowledge, and desire to contribute in
225 any capacity. Our goals are simply to continue the mission, to improve
226 Privoxy, and to make it available to as wide an audience as possible.
228 One does not have to be a programmer to contribute. Packaging, testing,
229 documenting and porting, are all important jobs as well.
231 --------------------------------------------------------------------------
233 1.1. Quickstart to Privoxy Development
235 The first step is to join the developer's mailing list. You can submit
236 your ideas, or even better patches. Patches are best submitted to the
237 Sourceforge tracker set up for this purpose, but can be sent to the list
240 You will also need to have a cvs package installed, which will entail
241 having ssh installed as well (which seems to be a requirement of
242 SourceForge), in order to access the cvs repository. Having the GNU build
243 tools is also going to be important (particularly, autoconf and gmake).
245 For the time being (read, this section is under construction), you can
246 also refer to the extensive comments in the source code. In fact, reading
247 the code is recommended in any case.
249 --------------------------------------------------------------------------
251 2. The CVS Repository
253 If you become part of the active development team, you will eventually
254 need write access to our holy grail, the CVS repository. One of the team
255 members will need to set this up for you. Please read this chapter
256 completely before accessing via CVS.
258 --------------------------------------------------------------------------
262 The project's CVS repository is hosted on SourceForge. Please refer to the
263 chapters 6 and 7 in SF's site documentation for the technical access
264 details for your operating system. For historical reasons, the CVS server
265 is called ijbswa.cvs.sourceforge.net, the repository is called ijbswa, and
266 the source tree module is called current.
268 --------------------------------------------------------------------------
272 Within the CVS repository, there are modules and branches. As mentioned,
273 the sources are in the current "module". Other modules are present for
274 platform specific issues. There is a webview of the CVS hierarchy at
275 http://ijbswa.cvs.sourceforge.net/ijbswa/, which might help with
276 visualizing how these pieces fit together.
278 Branches are used to fork a sub-development path from the main trunk.
279 Within the current module where the sources are, there is always at least
280 one "branch" from the main trunk devoted to a stable release series. The
281 main trunk is where active development takes place for the next stable
282 series (e.g. 3.2.x). So just prior to each stable series (e.g. 3.0.x), a
283 branch is created just for stable series releases (e.g. 3.0.0 -> 3.0.1 ->
284 3.0.2, etc). Once the initial stable release of any stable branch has
285 taken place, this branch is only used for bugfixes, which have had prior
286 testing before being committed to CVS. (See Version Numbers below for
287 details on versioning.)
289 At one time there were two distinct branches: stable and unstable. The
290 more drastic changes were to be in the unstable branch. These branches
291 have now been merged to minimize time and effort of maintaining two
294 --------------------------------------------------------------------------
296 2.3. CVS Commit Guidelines
298 The source tree is the heart of every software project. Every effort must
299 be made to ensure that it is readable, compilable and consistent at all
300 times. There are differing guidelines for the stable branch and the main
301 development trunk, and we ask anyone with CVS access to strictly adhere to
302 the following guidelines:
304 Basic Guidelines, for all branches:
306 * Please don't commit even a small change without testing it thoroughly
307 first. When we're close to a public release, ask a fellow developer to
310 * Your commit message should give a concise overview of what you changed
311 (no big details) and why you changed it Just check previous messages
314 * Don't use the same message on multiple files, unless it equally
315 applies to all those files.
317 * If your changes span multiple files, and the code won't recompile
318 unless all changes are committed (e.g. when changing the signature of
319 a function), then commit all files one after another, without long
320 delays in between. If necessary, prepare the commit messages in
323 * Before changing things on CVS, make sure that your changes are in line
324 with the team's general consensus on what should be done.
326 * Note that near a major public release, we get more cautious. There is
327 always the possibility to submit a patch to the patch tracker instead.
329 --------------------------------------------------------------------------
331 3. Documentation Guidelines
333 All formal documents are maintained in Docbook SGML and located in the
334 doc/source/* directory. You will need Docbook, the Docbook DTD's and the
335 Docbook modular stylesheets (or comparable alternatives), and either jade
336 or openjade (recommended) installed in order to build docs from source.
337 Currently there is user-manual, FAQ, and, of course this, the
338 developer-manual in this format. The README, AUTHORS, INSTALL, privoxy.1
339 (man page), and config files are also now maintained as Docbook SGML.
340 These files, when built, in the top-level source directory are generated
341 files! Also, the Privoxy index.html (and a variation on this file,
342 privoxy-index.html, meant for inclusion with doc packages), are maintained
343 as SGML as well. DO NOT edit these directly. Edit the SGML source, or
344 contact someone involved in the documentation.
346 config requires some special handling. The reason it is maintained this
347 way is so that the extensive comments in the file mirror those in
348 user-manual. But the conversion process requires going from SGML to HTML
349 to text to special formatting required for the embedded comments. Some of
350 this does not survive so well. Especially some of the examples that are
351 longer than 80 characters. The build process for this file outputs to
352 config.new, which should be reviewed for errors and mis-formatting. Once
353 satisfied that it is correct, then it should be hand copied to config.
355 Other, less formal documents (e.g. LICENSE) are maintained as plain text
356 files in the top-level source directory.
358 Packagers are encouraged to include this documentation. For those without
359 the ability to build the docs locally, text versions of each are kept in
360 CVS. HTML versions are also being kept in CVS under doc/webserver/*. And
361 PDF version are kept in doc/pdf/*.
363 Formal documents are built with the Makefile targets of make dok, or
364 alternately make redhat-dok. If you have problems, try both. The build
365 process uses the document SGML sources in doc/source/*/* to update all
366 text files in doc/text/ and to update all HTML documents in
369 Documentation writers should please make sure documents build successfully
370 before committing to CVS, if possible.
372 How do you update the webserver (i.e. the pages on privoxy.org)?
374 1. First, build the docs by running make dok (or alternately make
375 redhat-dok). For PDF docs, do make dok-pdf.
377 2. Run make webserver which copies all files from doc/webserver to the
378 sourceforge webserver via scp.
380 Finished docs should be occasionally submitted to CVS
381 (doc/webserver/*/*.html) so that those without the ability to build them
382 locally, have access to them if needed. This is especially important just
383 prior to a new release! Please do this after the $VERSION and other
384 release specific data in configure.in has been updated (this is done just
385 prior to a new release).
387 --------------------------------------------------------------------------
389 3.1. Quickstart to Docbook and SGML
391 If you are not familiar with SGML, it is a markup language similar to
392 HTML. Actually, not a mark up language per se, but a language used to
393 define markup languages. In fact, HTML is an SGML application. Both will
394 use "tags" to format text and other content. SGML tags can be much more
395 varied, and flexible, but do much of the same kinds of things. The tags,
396 or "elements", are definable in SGML. There is no set "standards". Since
397 we are using Docbook, our tags are those that are defined by Docbook. Much
398 of how the finish document is rendered is determined by the "stylesheets".
399 The stylesheets determine how each tag gets translated to HTML, or other
402 Tags in Docbook SGML need to be always "closed". If not, you will likely
403 generate errors. Example: <title>My Title</title>. They are also
404 case-insensitive, but we strongly suggest using all lower case. This keeps
405 compatibility with [Docbook] XML.
407 Our documents use "sections" for the most part. Sections will be processed
408 into HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use
409 these to also generate the Table of Contents for each doc. Our TOC's are
410 set to a depth of three. Meaning sect1, sect2, and sect3 will have TOC
411 entries, but sect4 will not. Each section requires a <title> element, and
412 at least one <para>. There is a limit of five section levels in Docbook,
413 but generally three should be sufficient for our purposes.
415 Some common elements that you likely will use:
417 <para></para>, paragraph delimiter. Most text needs to be within paragraph
418 elements (there are some exceptions).
419 <emphasis></emphasis>, the stylesheets make this italics.
420 <filename></filename>, files and directories.
421 <command></command>, command examples.
422 <literallayout></literallayout>, like <pre>, more or less.
423 <itemizedlist></itemizedlist>, list with bullets.
424 <listitem></listitem>, member of the above.
425 <screen></screen>, screen output, implies <literallayout>.
426 <ulink url="example.com"></ulink>, like HTML <a> tag.
427 <quote></quote>, for, doh, quoting text.
429 Look at any of the existing docs for examples of all these and more.
431 You might also find "Writing Documentation Using DocBook - A Crash Course"
434 --------------------------------------------------------------------------
436 3.2. Privoxy Documentation Style
438 It will be easier if everyone follows a similar writing style. This just
439 makes it easier to read what someone else has written if it is all done in
444 * All tags should be lower case.
446 * Tags delimiting a block of text (even small blocks) should be on their
454 Tags marking individual words, or few words, should be in-line:
456 Just to <emphasis>emphasize</emphasis>, some text goes here.
459 * Tags should be nested and step indented for block text like: (except
466 Some text goes here in our list example.
473 This makes it easier to find the text amongst the tags ;-)
474 * Use white space to separate logical divisions within a document, like
475 between sections. Running everything together consistently makes it
476 harder to read and work on.
478 * Do not hesitate to make comments. Comments can either use the
479 <comment> element, or the <!-- --> style comment familiar from HTML.
480 (Note in Docbook v4.x <comment> is replaced by <remark>.)
482 * We have an international audience. Refrain from slang, or English
483 idiosyncrasies (too many to list :). Humor also does not translate
486 * Try to keep overall line lengths in source files to 80 characters or
487 less for obvious reasons. This is not always possible, with lengthy
490 * Our documents are available in differing formats. Right now, they are
491 just plain text, HTML, and PDF, but others are always a future
492 possibility. Be careful with URLs (<ulink>), and avoid this mistake:
494 My favorite site is <ulink url="http://example.com">here</ulink>.
496 This will render as "My favorite site is here", which is not real
497 helpful in a text doc. Better like this:
499 My favorite site is <ulink
500 url="http://example.com">example.com</ulink>.
502 * All documents should be spell checked occasionally. aspell can check
503 SGML with the -H option. (ispell I think too.)
505 --------------------------------------------------------------------------
507 3.3. Privoxy Custom Entities
509 Privoxy documentation is using a number of customized "entities" to
510 facilitate documentation maintenance.
512 We are using a set of "boilerplate" files with generic text, that is used
513 by multiple docs. This way we can write something once, and use it
514 repeatedly without having to re-write the same content over and over
515 again. If editing such a file, keep in mind that it should be generic.
516 That is the purpose; so it can be used in varying contexts without
517 additional modifications.
519 We are also using what Docbook calls "internal entities". These are like
520 variables in programming. Well, sort of. For instance, we have the
521 p-version entity that contains the current Privoxy version string. You are
522 strongly encouraged to use these where possible. Some of these obviously
523 require re-setting with each release (done by the Makefile). A sampling of
524 custom entities are listed below. See any of the main docs for examples.
526 * Re- "boilerplate" text entities are defined like:
528 <!entity supported SYSTEM "supported.sgml">
530 In this example, the contents of the file, supported.sgml is available
531 for inclusion anywhere in the doc. To make this happen, just reference
532 the now defined entity: &supported; (starts with an ampersand and ends
533 with a semi-colon), and the contents will be dumped into the finished
536 * Commonly used "internal entities":
538 p-version: the Privoxy version string, e.g. "3.0.8".
539 p-status: the project status, either "alpha", "beta", or "stable".
540 p-not-stable: use to conditionally include text in "not stable"
541 releases (e.g. "beta").
542 p-stable: just the opposite.
543 p-text: this doc is only generated as text.
545 There are others in various places that are defined for a specific
546 purpose. Read the source!
548 --------------------------------------------------------------------------
554 This set of standards is designed to make our lives easier. It is
555 developed with the simple goal of helping us keep the "new and improved
556 Privoxy" consistent and reliable. Thus making maintenance easier and
557 increasing chances of success of the project.
559 And that of course comes back to us as individuals. If we can increase our
560 development and product efficiencies then we can solve more of the request
561 for changes/improvements and in general feel good about ourselves. ;->
563 --------------------------------------------------------------------------
567 4.2.1. Comment, Comment, Comment
571 Comment as much as possible without commenting the obvious. For example do
572 not comment "variable_a is equal to variable_b". Instead explain why
573 variable_a should be equal to the variable_b. Just because a person can
574 read code does not mean they will understand why or what is being done. A
575 reader may spend a lot more time figuring out what is going on when a
576 simple comment or explanation would have prevented the extra research.
577 Please help your brother IJB'ers out!
579 The comments will also help justify the intent of the code. If the comment
580 describes something different than what the code is doing then maybe a
581 programming error is occurring.
585 /* if page size greater than 1k ... */
586 if ( page_length() > 1024 )
588 ... "block" the page up ...
591 /* if page size is small, send it in blocks */
592 if ( page_length() > 1024 )
594 ... "block" the page up ...
597 This demonstrates 2 cases of "what not to do". The first is a
598 "syntax comment". The second is a comment that does not fit what
599 is actually being done.
601 --------------------------------------------------------------------------
603 4.2.2. Use blocks for comments
607 Comments can help or they can clutter. They help when they are
608 differentiated from the code they describe. One line comments do not offer
609 effective separation between the comment and the code. Block identifiers
610 do, by surrounding the code with a clear, definable pattern.
614 /*********************************************************************
615 * This will stand out clearly in your code!
616 *********************************************************************/
617 if ( this_variable == that_variable )
619 do_something_very_important();
623 /* unfortunately, this may not */
624 if ( this_variable == that_variable )
626 do_something_very_important();
630 if ( this_variable == that_variable ) /* this may not either */
632 do_something_very_important();
637 If you are trying to add a small logic comment and do not wish to
638 "disrupt" the flow of the code, feel free to use a 1 line comment which is
639 NOT on the same line as the code.
641 --------------------------------------------------------------------------
643 4.2.3. Keep Comments on their own line
647 It goes back to the question of readability. If the comment is on the same
648 line as the code it will be harder to read than the comment that is on its
651 There are three exceptions to this rule, which should be violated freely
652 and often: during the definition of variables, at the end of closing
653 braces, when used to comment parameters.
657 /*********************************************************************
658 * This will stand out clearly in your code,
659 * But the second example won't.
660 *********************************************************************/
661 if ( this_variable == this_variable )
663 do_something_very_important();
666 if ( this_variable == this_variable ) /*can you see me?*/
668 do_something_very_important(); /*not easily*/
672 /*********************************************************************
673 * But, the encouraged exceptions:
674 *********************************************************************/
675 int urls_read = 0; /* # of urls read + rejected */
676 int urls_rejected = 0; /* # of urls rejected */
680 do_something_very_important();
684 short do_something_very_important(
685 short firstparam, /* represents something */
686 short nextparam /* represents something else */ )
690 } /* -END- do_something_very_important */
692 --------------------------------------------------------------------------
694 4.2.4. Comment each logical step
698 Logical steps should be commented to help others follow the intent of the
699 written code and comments will make the code more readable.
701 If you have 25 lines of code without a comment, you should probably go
702 back into it to see where you forgot to put one.
704 Most "for", "while", "do", etc... loops _probably_ need a comment. After
705 all, these are usually major logic containers.
707 --------------------------------------------------------------------------
709 4.2.5. Comment All Functions Thoroughly
713 A reader of the code should be able to look at the comments just prior to
714 the beginning of a function and discern the reason for its existence and
715 the consequences of using it. The reader should not have to read through
716 the code to determine if a given function is safe for a desired use. The
717 proper information thoroughly presented at the introduction of a function
718 not only saves time for subsequent maintenance or debugging, it more
719 importantly aids in code reuse by allowing a user to determine the safety
720 and applicability of any function for the problem at hand. As a result of
721 such benefits, all functions should contain the information presented in
722 the addendum section of this document.
724 --------------------------------------------------------------------------
726 4.2.6. Comment at the end of braces if the content is more than one screen
731 Each closing brace should be followed on the same line by a comment that
732 describes the origination of the brace if the original brace is off of the
733 screen, or otherwise far away from the closing brace. This will simplify
734 the debugging, maintenance, and readability of the code.
736 As a suggestion , use the following flags to make the comment and its
739 use following a closing brace: } /* -END- if() or while () or etc... */
745 do_something_very_important();
746 ...some long list of commands...
747 } /* -END- if x is 1 */
753 do_something_very_important();
754 ...some long list of commands...
755 } /* -END- if ( 1 == X ) */
757 --------------------------------------------------------------------------
759 4.3. Naming Conventions
761 4.3.1. Variable Names
765 Use all lowercase, and separate words via an underscore ('_'). Do not
766 start an identifier with an underscore. (ANSI C reserves these for use by
767 the compiler and system headers.) Do not use identifiers which are
768 reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in
769 case we ever decide to port Privoxy to C++.
773 int ms_iis5_hack = 0;
777 int msiis5hack = 0; int msIis5Hack = 0;
779 --------------------------------------------------------------------------
781 4.3.2. Function Names
785 Use all lowercase, and separate words via an underscore ('_'). Do not
786 start an identifier with an underscore. (ANSI C reserves these for use by
787 the compiler and system headers.) Do not use identifiers which are
788 reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in
789 case we ever decide to port Privoxy to C++.
793 int load_some_file( struct client_state *csp )
797 int loadsomefile( struct client_state *csp )
798 int loadSomeFile( struct client_state *csp )
800 --------------------------------------------------------------------------
802 4.3.3. Header file prototypes
806 Use a descriptive parameter name in the function prototype in header
807 files. Use the same parameter name in the header file that you use in the
812 (.h) extern int load_aclfile( struct client_state *csp );
813 (.c) int load_aclfile( struct client_state *csp )
817 (.h) extern int load_aclfile( struct client_state * ); or
818 (.h) extern int load_aclfile();
819 (.c) int load_aclfile( struct client_state *csp )
821 --------------------------------------------------------------------------
823 4.3.4. Enumerations, and #defines
827 Use all capital letters, with underscores between words. Do not start an
828 identifier with an underscore. (ANSI C reserves these for use by the
829 compiler and system headers.)
833 (enumeration) : enum Boolean { FALSE, TRUE };
834 (#define) : #define DEFAULT_SIZE 100;
836 Note: We have a standard naming scheme for #defines that toggle a feature
837 in the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2
842 #define FEATURE_FORCE 1
845 #define FORCE_PREFIX blah
846 #endif /* def FEATURE_FORCE */
848 --------------------------------------------------------------------------
854 Spell common words out entirely (do not remove vowels).
856 Use only widely-known domain acronyms and abbreviations. Capitalize all
857 letters of an acronym.
859 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
860 terminate a name with an underscore.
864 #define USE_IMAGE_LIST 1
868 #define USE_IMG_LST 1 or
869 #define _USE_IMAGE_LIST 1 or
870 #define USE_IMAGE_LIST_ 1 or
871 #define use_image_list 1 or
872 #define UseImageList 1
874 --------------------------------------------------------------------------
878 4.4.1. Put braces on a line by themselves.
882 The brace needs to be on a line all by itself, not at the end of the
883 statement. Curly braces should line up with the construct that they're
884 associated with. This practice makes it easier to identify the opening and
885 closing braces for a block.
896 if ( this == that ) { ... }
900 if ( this == that ) { ... }
902 Note: In the special case that the if-statement is inside a loop, and it
903 is trivial, i.e. it tests for a condition that is obvious from the purpose
904 of the block, one-liners as above may optically preserve the loop
905 structure and make it easier to read.
907 Status: developer-discretion.
911 while ( more lines are read )
913 /* Please document what is/is not a comment line here */
914 if ( it's a comment ) continue;
916 do_something( line );
919 --------------------------------------------------------------------------
921 4.4.2. ALL control statements should have a block
925 Using braces to make a block will make your code more readable and less
926 prone to error. All control statements should have a block defined.
938 if ( this == that ) do_something(); do_something_else();
942 if ( this == that ) do_something();
944 Note: The first example in "Instead of" will execute in a manner other
945 than that which the developer desired (per indentation). Using code braces
946 would have prevented this "feature". The "explanation" and "exception"
947 from the point above also applies.
949 --------------------------------------------------------------------------
951 4.4.3. Do not belabor/blow-up boolean expressions
955 structure->flag = ( condition );
959 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
961 Note: The former is readable and concise. The later is wordy and
962 inefficient. Please assume that any developer new to the project has at
963 least a "good" knowledge of C/C++. (Hope I do not offend by that last
966 --------------------------------------------------------------------------
968 4.4.4. Use white space freely because it is free
972 Make it readable. The notable exception to using white space freely is
973 listed in the next guideline.
979 int another_value = 0;
980 int this_variable = 0;
982 if ( this_variable == this_variable )
984 first_value = old_value + ( ( some_value - another_value ) - whatever )
986 --------------------------------------------------------------------------
988 4.4.5. Don't use white space around structure operators
992 - structure pointer operator ( "->" ) - member operator ( "." ) -
993 functions and parentheses
995 It is a general coding practice to put pointers, references, and function
996 parentheses next to names. With spaces, the connection between the object
997 and variable/function name is not as clear.
1005 Instead of: a_struct -> a_member; a_struct . a_member; function_name ();
1007 --------------------------------------------------------------------------
1009 4.4.6. Make the last brace of a function stand out
1013 int function1( ... )
1018 } /* -END- function1 */
1021 int function2( ... )
1023 } /* -END- function2 */
1027 int function1( ... ) { ...code... return( ret_code ); } int function2( ...
1030 Note: Use 1 blank line before the closing brace and 2 lines afterward.
1031 This makes the end of function standout to the most casual viewer.
1032 Although function comments help separate functions, this is still a good
1033 coding practice. In fact, I follow these rules when using blocks in "for",
1034 "while", "do" loops, and long if {} statements too. After all whitespace
1037 Status: developer-discretion on the number of blank lines. Enforced is the
1038 end of function comments.
1040 --------------------------------------------------------------------------
1042 4.4.7. Use 3 character indentions
1046 If some use 8 character TABs and some use 3 character TABs, the code can
1047 look *very* ragged. So use 3 character indentions only. If you like to use
1048 TABs, pass your code through a filter such as "expand -t3" before checking
1053 static const char * const url_code_map[256] =
1059 int function1( ... )
1063 return( ALWAYS_TRUE );
1067 return( HOW_DID_YOU_GET_HERE );
1070 return( NEVER_GETS_HERE );
1074 --------------------------------------------------------------------------
1078 4.5.1. Initialize all variables
1082 Do not assume that the variables declared will not be used until after
1083 they have been assigned a value somewhere else in the code. Remove the
1084 chance of accidentally using an unassigned variable.
1092 Note: It is much easier to debug a SIGSEGV if the message says you are
1093 trying to access memory address 00000000 and not 129FA012; or
1094 array_ptr[20] causes a SIGSEV vs. array_ptr[0].
1096 Status: developer-discretion if and only if the variable is assigned a
1097 value "shortly after" declaration.
1099 --------------------------------------------------------------------------
1103 4.6.1. Name functions that return a boolean as a question.
1107 Value should be phrased as a question that would logically be answered as
1108 a true or false statement
1112 should_we_block_this();
1113 contains_an_image();
1114 is_web_page_blank();
1116 --------------------------------------------------------------------------
1118 4.6.2. Always specify a return type for a function.
1122 The default return for a function is an int. To avoid ambiguity, create a
1123 return for a function when the return has a purpose, and create a void
1124 return type if the function does not need to return anything.
1126 --------------------------------------------------------------------------
1128 4.6.3. Minimize function calls when iterating by using variables
1132 It is easy to write the following code, and a clear argument can be made
1133 that the code is easy to understand:
1137 for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
1142 Note: Unfortunately, this makes a function call for each and every
1143 iteration. This increases the overhead in the program, because the
1144 compiler has to look up the function each time, call it, and return a
1145 value. Depending on what occurs in the block_list_length() call, it might
1146 even be creating and destroying structures with each iteration, even
1147 though in each case it is comparing "cnt" to the same value, over and
1148 over. Remember too - even a call to block_list_length() is a function
1149 call, with the same overhead.
1151 Instead of using a function call during the iterations, assign the value
1152 to a variable, and evaluate using the variable.
1156 size_t len = block_list_length();
1158 for ( size_t cnt = 0; cnt < len; cnt++ )
1163 Exceptions: if the value of block_list_length() *may* change or could
1164 *potentially* change, then you must code the function call in the
1167 --------------------------------------------------------------------------
1169 4.6.4. Pass and Return by Const Reference
1173 This allows a developer to define a const pointer and call your function.
1174 If your function does not have the const keyword, we may not be able to
1175 use your function. Consider strcmp, if it were defined as: extern int
1176 strcmp( char *s1, char *s2 );
1178 I could then not use it to compare argv's in main: int main( int argc,
1179 const char *argv[] ) { strcmp( argv[0], "privoxy" ); }
1181 Both these pointers are *const*! If the c runtime library maintainers do
1184 --------------------------------------------------------------------------
1186 4.6.5. Pass and Return by Value
1190 Most structures cannot fit onto a normal stack entry (i.e. they are not 4
1191 bytes or less). Aka, a function declaration like: int load_aclfile( struct
1194 would not work. So, to be consistent, we should declare all prototypes
1195 with "pass by value": int load_aclfile( struct client_state *csp )
1197 --------------------------------------------------------------------------
1199 4.6.6. Names of include files
1203 Your include statements should contain the file name without a path. The
1204 path should be listed in the Makefile, using -I as processor directive to
1205 search the indicated paths. An exception to this would be for some
1206 proprietary software that utilizes a partial path to distinguish their
1207 header files from system or other header files.
1211 #include <iostream.h> /* This is not a local include */
1212 #include "config.h" /* This IS a local include */
1216 /* This is not a local include, but requires a path element. */
1217 #include <sys/fileName.h>
1219 Note: Please! do not add "-I." to the Makefile without a _very_ good
1220 reason. This duplicates the #include "file.h" behavior.
1222 --------------------------------------------------------------------------
1224 4.6.7. Provide multiple inclusion protection
1228 Prevents compiler and linker errors resulting from redefinition of items.
1230 Wrap each header file with the following syntax to prevent multiple
1231 inclusions of the file. Of course, replace PROJECT_H with your file name,
1232 with "." Changed to "_", and make it uppercase.
1236 #ifndef PROJECT_H_INCLUDED
1237 #define PROJECT_H_INCLUDED
1239 #endif /* ndef PROJECT_H_INCLUDED */
1241 --------------------------------------------------------------------------
1243 4.6.8. Use `extern "C"` when appropriate
1247 If our headers are included from C++, they must declare our functions as
1248 `extern "C"`. This has no cost in C, but increases the potential
1249 re-usability of our code.
1256 #endif /* def __cplusplus */
1258 ... function definitions here ...
1262 #endif /* def __cplusplus */
1264 --------------------------------------------------------------------------
1266 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
1270 Useful in headers that include pointers to other struct's. Modifications
1271 to excess header files may cause needless compiles.
1275 /*********************************************************************
1276 * We're avoiding an include statement here!
1277 *********************************************************************/
1279 extern file_list *xyz;
1281 Note: If you declare "file_list xyz;" (without the pointer), then
1282 including the proper header file is necessary. If you only want to
1283 prototype a pointer, however, the header file is unnecessary.
1285 Status: Use with discretion.
1287 --------------------------------------------------------------------------
1289 4.7. General Coding Practices
1291 4.7.1. Turn on warnings
1295 Compiler warnings are meant to help you find bugs. You should turn on as
1296 many as possible. With GCC, the switch is "-Wall". Try and fix as many
1297 warnings as possible.
1299 --------------------------------------------------------------------------
1301 4.7.2. Provide a default case for all switch statements
1305 What you think is guaranteed is never really guaranteed. The value that
1306 you don't think you need to check is the one that someday will be passed.
1307 So, to protect yourself from the unknown, always have a default step in a
1312 switch( hash_string( cmd ) )
1314 case hash_actions_file :
1324 ... anomaly code goes here ...
1325 continue; / break; / exit( 1 ); / etc ...
1327 } /* end switch( hash_string( cmd ) ) */
1329 Note: If you already have a default condition, you are obviously exempt
1330 from this point. Of note, most of the WIN32 code calls `DefWindowProc'
1331 after the switch statement. This API call *should* be included in a
1334 Another Note: This is not so much a readability issue as a robust
1335 programming issue. The "anomaly code goes here" may be no more than a
1336 print to the STDERR stream (as in load_config). Or it may really be an
1339 Status: Programmer discretion is advised.
1341 --------------------------------------------------------------------------
1343 4.7.3. Try to avoid falling through cases in a switch statement.
1347 In general, you will want to have a 'break' statement within each 'case'
1348 of a switch statement. This allows for the code to be more readable and
1349 understandable, and furthermore can prevent unwanted surprises if someone
1350 else later gets creative and moves the code around.
1352 The language allows you to plan the fall through from one case statement
1353 to another simply by omitting the break statement within the case
1354 statement. This feature does have benefits, but should only be used in
1355 rare cases. In general, use a break statement for each case statement.
1357 If you choose to allow fall through, you should comment both the fact of
1358 the fall through and reason why you felt it was necessary.
1360 --------------------------------------------------------------------------
1362 4.7.4. Use 'long' or 'short' Instead of 'int'
1366 On 32-bit platforms, int usually has the range of long. On 16-bit
1367 platforms, int has the range of short.
1369 Status: open-to-debate. In the case of most FSF projects (including
1370 X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ...
1371 I forget the exact typedefs now). Should we add these to IJB now that we
1372 have a "configure" script?
1374 --------------------------------------------------------------------------
1376 4.7.5. Don't mix size_t and other types
1380 The type of size_t varies across platforms. Do not make assumptions about
1381 whether it is signed or unsigned, or about how long it is. Do not compare
1382 a size_t against another variable of a different type (or even against a
1383 constant) without casting one of the values.
1385 --------------------------------------------------------------------------
1387 4.7.6. Declare each variable and struct on its own line.
1391 It can be tempting to declare a series of variables all on one line.
1404 Explanation: - there is more room for comments on the individual variables
1405 - easier to add new variables without messing up the original ones - when
1406 searching on a variable to find its type, there is less clutter to
1407 "visually" eliminate
1409 Exceptions: when you want to declare a bunch of loop variables or other
1410 trivial variables; feel free to declare them on one line. You should,
1411 although, provide a good comment on their functions.
1413 Status: developer-discretion.
1415 --------------------------------------------------------------------------
1417 4.7.7. Use malloc/zalloc sparingly
1421 Create a local struct (on the stack) if the variable will live and die
1422 within the context of one function call.
1424 Only "malloc" a struct (on the heap) if the variable's life will extend
1425 beyond the context of one function call.
1429 If a function creates a struct and stores a pointer to it in a
1430 list, then it should definitely be allocated via `malloc'.
1432 --------------------------------------------------------------------------
1434 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1438 If you have to "malloc" an instance, you are responsible for insuring that
1439 the instance is `free'd, even if the deallocation event falls within some
1440 other programmer's code. You are also responsible for ensuring that
1441 deletion is timely (i.e. not too soon, not too late). This is known as
1442 "low-coupling" and is a "good thing (tm)". You may need to offer a
1443 free/unload/destructor type function to accommodate this.
1447 int load_re_filterfile( struct client_state *csp ) { ... }
1448 static void unload_re_filterfile( void *f ) { ... }
1452 The developer cannot be expected to provide `free'ing functions for C
1453 run-time library functions ... such as `strdup'.
1455 Status: developer-discretion. The "main" use of this standard is for
1456 allocating and freeing data structures (complex or nested).
1458 --------------------------------------------------------------------------
1460 4.7.9. Add loaders to the `file_list' structure and in order
1464 I have ordered all of the "blocker" file code to be in alpha order. It is
1465 easier to add/read new blockers when you expect a certain order.
1467 Note: It may appear that the alpha order is broken in places by POPUP
1468 tests coming before PCRS tests. But since POPUPs can also be referred to
1469 as KILLPOPUPs, it is clear that it should come first.
1471 --------------------------------------------------------------------------
1473 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME or
1478 If you have enough confidence in new code or confidence in your changes,
1479 but are not *quite* sure of the repercussions, add this:
1481 /* FIXME: this code has a logic error on platform XYZ, * attempting to fix
1482 */ #ifdef PLATFORM ...changed code here... #endif
1486 /* FIXME: I think the original author really meant this... */ ...changed
1491 /* FIXME: new code that *may* break something else... */ ...new code
1494 Note: If you make it clear that this may or may not be a "good thing
1495 (tm)", it will be easier to identify and include in the project (or
1496 conversely exclude from the project).
1498 --------------------------------------------------------------------------
1500 4.8. Addendum: Template for files and function comment blocks:
1502 Example for file comments:
1504 const char FILENAME_rcs[] = "$Id: developer-manual.txt,v 1.43 2008/01/19 21:41:36 hal9 Exp $";
1505 /*********************************************************************
1507 * File : $Source: /cvsroot/ijbswa/current/doc/text/developer-manual.txt,v $
1509 * Purpose : (Fill me in with a good description!)
1511 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
1512 * Privoxy team. http://www.privoxy.org/
1514 * Based on the Internet Junkbuster originally written
1515 * by and Copyright (C) 1997 Anonymous Coders and
1516 * Junkbusters Corporation. http://www.junkbusters.com
1518 * This program is free software; you can redistribute it
1519 * and/or modify it under the terms of the GNU General
1520 * Public License as published by the Free Software
1521 * Foundation; either version 2 of the License, or (at
1522 * your option) any later version.
1524 * This program is distributed in the hope that it will
1525 * be useful, but WITHOUT ANY WARRANTY; without even the
1526 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1527 * PARTICULAR PURPOSE. See the GNU General Public
1528 * License for more details.
1530 * The GNU General Public License should be included with
1531 * this file. If not, you can view it at
1532 * http://www.gnu.org/copyleft/gpl.html
1533 * or write to the Free Software Foundation, Inc.,
1534 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1538 * $Log: developer-manual.txt,v $
1539 * Revision 1.43 2008/01/19 21:41:36 hal9
1540 * Re-commit to solve various last minute issues for charsets, etc.
1543 *********************************************************************/
1548 ...necessary include files for us to do our work...
1550 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1552 Note: This declares the rcs variables that should be added to the
1553 "show-proxy-args" page. If this is a brand new creation by you, you are
1554 free to change the "Copyright" section to represent the rights you wish to
1557 Note: The formfeed character that is present right after the comment
1558 flower box is handy for (X|GNU)Emacs users to skip the verbiage and get to
1559 the heart of the code (via `forward-page' and `backward-page'). Please
1560 include it if you can.
1562 Example for file header comments:
1566 #define FILENAME_H_VERSION "$Id: developer-manual.txt,v 1.43 2008/01/19 21:41:36 hal9 Exp $"
1567 /*********************************************************************
1569 * File : $Source: /cvsroot/ijbswa/current/doc/text/developer-manual.txt,v $
1571 * Purpose : (Fill me in with a good description!)
1573 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
1574 * Privoxy team. http://www.privoxy.org/
1576 * Based on the Internet Junkbuster originally written
1577 * by and Copyright (C) 1997 Anonymous Coders and
1578 * Junkbusters Corporation. http://www.junkbusters.com
1580 * This program is free software; you can redistribute it
1581 * and/or modify it under the terms of the GNU General
1582 * Public License as published by the Free Software
1583 * Foundation; either version 2 of the License, or (at
1584 * your option) any later version.
1586 * This program is distributed in the hope that it will
1587 * be useful, but WITHOUT ANY WARRANTY; without even the
1588 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1589 * PARTICULAR PURPOSE. See the GNU General Public
1590 * License for more details.
1592 * The GNU General Public License should be included with
1593 * this file. If not, you can view it at
1594 * http://www.gnu.org/copyleft/gpl.html
1595 * or write to the Free Software Foundation, Inc.,
1596 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1600 * $Log: developer-manual.txt,v $
1601 * Revision 1.43 2008/01/19 21:41:36 hal9
1602 * Re-commit to solve various last minute issues for charsets, etc.
1605 *********************************************************************/
1608 #include "project.h"
1614 ... function headers here ...
1617 /* Revision control strings from this header and associated .c file */
1618 extern const char FILENAME_rcs[];
1619 extern const char FILENAME_h_rcs[];
1626 #endif /* ndef _FILENAME_H */
1634 Example for function comments:
1636 /*********************************************************************
1638 * Function : FUNCTION_NAME
1640 * Description : (Fill me in with a good description!)
1643 * 1 : param1 = pointer to an important thing
1644 * 2 : x = pointer to something else
1646 * Returns : 0 => Ok, everything else is an error.
1648 *********************************************************************/
1649 int FUNCTION_NAME( void *param1, const char *x )
1656 Note: If we all follow this practice, we should be able to parse our code
1657 to create a "self-documenting" web page.
1659 --------------------------------------------------------------------------
1661 5. Testing Guidelines
1665 --------------------------------------------------------------------------
1667 5.1. Testplan for releases
1669 Explain release numbers. major, minor. developer releases. etc.
1671 1. Remove any existing rpm with rpm -e
1673 2. Remove any file that was left over. This includes (but is not limited
1682 * /etc/init.d/privoxy
1686 3. Install the rpm. Any error messages?
1688 4. start,stop,status Privoxy with the specific script (e.g.
1689 /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart
1692 5. Start browsing. Does Privoxy work? Logfile written?
1694 6. Remove the rpm. Any error messages? All files removed?
1696 --------------------------------------------------------------------------
1700 Please submit test reports only with the test form at sourceforge. Three
1703 * Select category: the distribution you test on.
1705 * Select group: the version of Privoxy that we are about to release.
1707 * Fill the Summary and Detailed Description with something intelligent
1708 (keep it short and precise).
1710 Do not mail to the mailing list (we cannot keep track on issues there).
1712 --------------------------------------------------------------------------
1714 6. Releasing a New Version
1716 When we release versions of Privoxy, our work leaves our cozy secret lab
1717 and has to work in the cold RealWorld[tm]. Once it is released, there is
1718 no way to call it back, so it is very important that great care is taken
1719 to ensure that everything runs fine, and not to introduce problems in the
1722 So when releasing a new version, please adhere exactly to the procedure
1723 outlined in this chapter.
1725 The following programs are required to follow this process: ncftpput
1726 (ncftp), scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
1728 --------------------------------------------------------------------------
1730 6.1. Version numbers
1732 First you need to determine which version number the release will have.
1733 Privoxy version numbers consist of three numbers, separated by dots, like
1734 in X.Y.Z (e.g. 3.0.0), where:
1736 * X, the version major, is rarely ever changed. It is increased by one
1737 if turning a development branch into stable substantially changes the
1738 functionality, user interface or configuration syntax. Majors 1 and 2
1739 were Junkbuster, and 3 will be the first stable Privoxy release.
1741 * Y, the version minor, represents the branch within the major version.
1742 At any point in time, there are two branches being maintained: The
1743 stable branch, with an even minor, say, 2N, in which no functionality
1744 is being added and only bug-fixes are made, and 2N+1, the development
1745 branch, in which the further development of Privoxy takes place. This
1746 enables us to turn the code upside down and inside out, while at the
1747 same time providing and maintaining a stable version. The minor is
1748 reset to zero (and one) when the major is incremented. When a
1749 development branch has matured to the point where it can be turned
1750 into stable, the old stable branch 2N is given up (i.e. no longer
1751 maintained), the former development branch 2N+1 becomes the new stable
1752 branch 2N+2, and a new development branch 2N+3 is opened.
1754 * Z, the point or sub version, represents a release of the software
1755 within a branch. It is therefore incremented immediately before each
1756 code freeze. In development branches, only the even point versions
1757 correspond to actual releases, while the odd ones denote the evolving
1758 state of the sources on CVS in between. It follows that Z is odd on
1759 CVS in development branches most of the time. There, it gets increased
1760 to an even number immediately before a code freeze, and is increased
1761 to an odd number again immediately thereafter. This ensures that
1762 builds from CVS snapshots are easily distinguished from released
1763 versions. The point version is reset to zero when the minor changes.
1765 Stable branches work a little differently, since there should be
1766 little to no development happening in such branches. Remember, only
1767 bugfixes, which presumably should have had some testing before being
1768 committed. Stable branches will then have their version reported as
1769 0.0.0, during that period between releases when changes are being
1770 added. This is to denote that this code is not for release. Then as
1771 the release nears, the version is bumped according: e.g. 3.0.1 ->
1774 In summary, the main CVS trunk is the development branch where new
1775 features are being worked on for the next stable series. This should
1776 almost always be where the most activity takes place. There is always at
1777 least one stable branch from the trunk, e.g now it is 3.0, which is only
1778 used to release stable versions. Once the initial *.0 release of the
1779 stable branch has been done, then as a rule, only bugfixes that have had
1780 prior testing should be committed to the stable branch. Once there are
1781 enough bugfixes to justify a new release, the version of this branch is
1782 again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable
1783 releases from within the stable branch. 3.1.x is currently the main trunk,
1784 and where work on 3.2.x is taking place. If any questions, please post to
1785 the devel list before committing to a stable branch!
1787 Developers should remember too that if they commit a bugfix to the stable
1788 branch, this will more than likely require a separate submission to the
1789 main trunk, since these are separate development trees within CVS. If you
1790 are working on both, then this would require at least two separate check
1791 outs (i.e main trunk, and the stable release branch, which is v_3_0_branch
1794 --------------------------------------------------------------------------
1796 6.2. Before the Release: Freeze
1798 The following must be done by one of the developers prior to each new
1801 * Make sure that everybody who has worked on the code in the last couple
1802 of days has had a chance to yell "no!" in case they have pending
1803 changes/fixes in their pipelines. Announce the freeze so that nobody
1804 will interfere with last minute changes.
1806 * Increment the version number (point from odd to even in development
1807 branches!) in configure.in. (RPM spec files will need to be
1808 incremented as well.)
1810 * If default.action has changed since last release (i.e. software
1811 release or standalone actions file release), bump up its version info
1812 to A.B in this line:
1814 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1816 Then change the version info in doc/webserver/actions/index.php, line:
1817 '$required_actions_file_version = "A.B";'
1819 * All documentation should be rebuild after the version bump. Finished
1820 docs should be then be committed to CVS (for those without the ability
1821 to build these). Some docs may require rather obscure processing
1822 tools. config, the man page (and the html version of the man page),
1823 and the PDF docs fall in this category. REAMDE, the man page, AUTHORS,
1824 and config should all also be committed to CVS for other packagers.
1825 The formal docs should be uploaded to the webserver. See the Section
1826 "Updating the webserver" in this manual for details.
1828 * The User Manual is also used for context sensitive help for the CGI
1829 editor. This is version sensitive, so that the user will get
1830 appropriate help for his/her release. So with each release a fresh
1831 version should be uploaded to the webserver (this is in addition to
1832 the main User Manual link from the main page since we need to keep
1833 manuals for various versions available). The CGI pages will link to
1834 something like http://privoxy.org/$(VERSION)/user-manual/. This will
1835 need to be updated for each new release. There is no Makefile target
1836 for this at this time!!! It needs to be done manually.
1838 * All developers should look at the ChangeLog and make sure noteworthy
1839 changes are referenced.
1841 * Commit all files that were changed in the above steps!
1843 * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z".
1844 Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1846 * If the release was in a development branch, increase the point version
1847 from even to odd (X.Y.(Z+1)) again in configure.in and commit your
1850 * On the webserver, copy the user manual to a new top-level directory
1851 called X.Y.Z. This ensures that help links from the CGI pages, which
1852 have the version as a prefix, will go into the right version of the
1853 manual. If this is a development branch release, also symlink
1854 X.Y.(Z-1) to X.Y.Z and X.Y.(Z+1) to . (i.e. dot).
1856 --------------------------------------------------------------------------
1858 6.3. Building and Releasing the Packages
1860 Now the individual packages can be built and released. Note that for GPL
1861 reasons the first package to be released is always the source tarball.
1863 For all types of packages, including the source tarball, you must make
1864 sure that you build from clean sources by exporting the right version from
1865 CVS into an empty directory (just press return when asked for a password):
1867 mkdir dist # delete or choose different name if it already exists
1869 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
1870 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1872 Do NOT change a single bit, including, but not limited to version
1873 information after export from CVS. This is to make sure that all release
1874 packages, and with them, all future bug reports, are based on exactly the
1877 +------------------------------------------------------------------------+
1879 |------------------------------------------------------------------------|
1880 | Every significant release of Privoxy has included at least one package |
1881 | that either had incorrect versions of files, missing files, or |
1882 | incidental leftovers from a previous build process that gave unknown |
1883 | numbers of users headaches to try to figure out what was wrong. |
1884 | PLEASE, make sure you are using pristene sources, and are following |
1885 | the prescribed process! |
1886 +------------------------------------------------------------------------+
1888 Please find additional instructions for the source tarball and the
1889 individual platform dependent binary packages below. And details on the
1890 Sourceforge release process below that.
1892 --------------------------------------------------------------------------
1894 6.3.1. Note on Privoxy Packaging
1896 Please keep these general guidelines in mind when putting together your
1897 package. These apply to all platforms!
1899 * Privoxy requires write access to: all *.action files, all logfiles,
1900 and the trust file. You will need to determine the best way to do this
1903 * Please include up to date documentation. At a bare minimum:
1905 LICENSE (top-level directory)
1907 README (top-level directory)
1909 AUTHORS (top-level directory)
1911 man page (top-level directory, Unix-like platforms only)
1913 The User Manual (doc/webserver/user-manual/)
1915 FAQ (doc/webserver/faq/)
1917 Also suggested: Developer Manual (doc/webserver/developer-manual) and
1918 ChangeLog (top-level directory). FAQ and the manuals are HTML docs.
1919 There are also text versions in doc/text/ which could conceivably also
1922 The documentation has been designed such that the manuals are linked
1923 to each other from parallel directories, and should be packaged that
1924 way. privoxy-index.html can also be included and can serve as a focal
1925 point for docs and other links of interest (and possibly renamed to
1926 index.html). This should be one level up from the manuals. There is a
1927 link also on this page to an HTMLized version of the man page. To
1928 avoid 404 for this, it is in CVS as
1929 doc/webserver/man-page/privoxy-man-page.html, and should be included
1930 along with the manuals. There is also a css stylesheets that can be
1931 included for better presentation: p_doc.css. This should be in the
1932 same directory with privoxy-index.html, (i.e. one level up from the
1933 manual directories).
1935 * user.action and user.filter are designed for local preferences. Make
1936 sure these do not get overwritten! config should not be overwritten
1937 either. This has especially important configuration data in it. trust
1938 should be left in tact as well.
1940 * Other configuration files (default.action, default.filter and
1941 standard.action) should be installed as the new defaults, but all
1942 previously installed configuration files should be preserved as
1943 backups. This is just good manners :-) These files are likely to
1944 change between releases and contain important new features and bug
1947 * Please check platform specific notes in this doc, if you haven't done
1948 "Privoxy" packaging before for other platform specific issues.
1949 Conversely, please add any notes that you know are important for your
1950 platform (or contact one of the doc maintainers to do this if you
1953 * Packagers should do a "clean" install of their package after building
1954 it. So any previous installs should be removed first to ensure the
1955 integrity of the newly built package. Then run the package for a while
1956 to make sure there are no obvious problems, before uploading.
1958 --------------------------------------------------------------------------
1960 6.3.2. Source Tarball
1962 First, make sure that you have freshly exported the right version into an
1963 empty directory. (See "Building and releasing packages" above). Then run:
1966 autoheader && autoconf && ./configure
1972 To upload the package to Sourceforge, simply issue
1976 Go to the displayed URL and release the file publicly on Sourceforge. For
1977 the change log field, use the relevant section of the ChangeLog file.
1979 --------------------------------------------------------------------------
1981 6.3.3. SuSE, Conectiva or Red Hat RPM
1983 In following text, replace dist with either "rh" for Red Hat or "suse" for
1986 First, make sure that you have freshly exported the right version into an
1987 empty directory. (See "Building and releasing packages" above).
1989 As the only exception to not changing anything after export from CVS, now
1990 examine the file privoxy-dist.spec and make sure that the version
1991 information and the RPM release number are correct. The RPM release
1992 numbers for each version start at one. Hence it must be reset to one if
1993 this is the first RPM for dist which is built from version X.Y.Z. Check
1994 the file list if unsure. Else, it must be set to the highest already
1995 available RPM release number for that version plus one.
2000 autoheader && autoconf && ./configure
2006 To upload the package to Sourceforge, simply issue
2008 make dist-upload rpm_packagerev
2010 where rpm_packagerev is the RPM release number as determined above. Go to
2011 the displayed URL and release the file publicly on Sourceforge. Use the
2012 release notes and change log from the source tarball package.
2014 --------------------------------------------------------------------------
2018 First, make sure that you have freshly exported the right version into an
2019 empty directory. (See "Building and releasing packages" above). Then get
2020 the OS/2 Setup module:
2022 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
2024 You will need a mix of development tools. The main compilation takes place
2025 with IBM Visual Age C++. Some ancillary work takes place with GNU tools,
2026 available from various sources like hobbes.nmsu.edu. Specificially, you
2027 will need autoheader, autoconf and sh tools. The packaging takes place
2028 with WarpIN, available from various sources, including its home page:
2031 Change directory to the os2setup directory. Edit the os2build.cmd file to
2032 set the final executable filename. For example,
2034 installExeName='privoxyos2_setup_X.Y.Z.exe'
2036 Next, edit the IJB.wis file so the release number matches in the PACKAGEID
2039 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2041 You're now ready to build. Run:
2045 You will find the WarpIN-installable executable in the ./files directory.
2046 Upload this anonymously to uploads.sourceforge.net/incoming, create a
2047 release for it, and you're done. Use the release notes and Change Log from
2048 the source tarball package.
2050 --------------------------------------------------------------------------
2054 Login to Sourceforge's compilefarm via ssh:
2056 ssh cf.sourceforge.net
2058 Choose the right operating system (not the Debian one). When logged in,
2059 make sure that you have freshly exported the right version into an empty
2060 directory. (See "Building and releasing packages" above). Then run:
2063 autoheader && autoconf && ./configure
2069 which creates a gzip'ed tar archive. Sadly, you cannot use make
2070 solaris-upload on the Sourceforge machine (no ncftpput). You now have to
2071 manually upload the archive to Sourceforge's ftp server and release the
2072 file publicly. Use the release notes and Change Log from the source
2075 --------------------------------------------------------------------------
2079 You should ensure you have the latest version of Cygwin (from
2080 http://www.cygwin.com/). Run the following commands from within a Cygwin
2083 First, make sure that you have freshly exported the right version into an
2084 empty directory. (See "Building and releasing packages" above). Then get
2085 the Windows setup module:
2087 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
2089 Then you can build the package. This is fully automated, and is controlled
2090 by winsetup/GNUmakefile. All you need to do is:
2095 Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe,
2096 and upload it to SourceForge. When releasing the package on SourceForge,
2097 use the release notes and Change Log from the source tarball package.
2099 --------------------------------------------------------------------------
2103 First, make sure that you have freshly exported the right version into an
2104 empty directory. (See "Building and releasing packages" above). Then add a
2105 log entry to debian/changelog, if it is not already there, for example by
2108 debchange -v 3.0.8-stable-1 "New upstream version"
2112 dpkg-buildpackage -rfakeroot -us -uc -b
2114 This will create ../privoxy_3.0.8-stable-1_i386.deb which can be uploaded.
2115 To upload the package to Sourceforge, simply issue
2119 --------------------------------------------------------------------------
2123 First, make sure that you have freshly exported the right version into an
2124 empty directory. (See "Building and releasing packages" above). Then get
2125 the Mac OSX setup module:
2127 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
2134 This will run autoheader, autoconf and configure as well as make. Finally,
2135 it will copy over the necessary files to the ./osxsetup/files directory
2136 for further processing by PackageMaker.
2138 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify
2139 the package name to match the release, and hit the "Create package"
2140 button. If you specify ./Privoxy.pkg as the output package name, you can
2141 then create the distributable zip file with the command:
2143 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2145 You can then upload privoxyosx_setup_x.y.z.zip anonymously to
2146 uploads.sourceforge.net/incoming, create a release for it, and you're
2147 done. Use the release notes and Change Log from the source tarball
2150 --------------------------------------------------------------------------
2154 Login to Sourceforge's compile-farm via ssh:
2156 ssh cf.sourceforge.net
2158 Choose the right operating system. When logged in, make sure that you have
2159 freshly exported the right version into an empty directory. (See "Building
2160 and releasing packages" above). Then run:
2163 autoheader && autoconf && ./configure
2169 which creates a gzip'ed tar archive. Sadly, you cannot use make
2170 freebsd-upload on the Sourceforge machine (no ncftpput). You now have to
2171 manually upload the archive to Sourceforge's ftp server and release the
2172 file publicly. Use the release notes and Change Log from the source
2175 --------------------------------------------------------------------------
2179 First, make sure that you have freshly exported the right version into an
2180 empty directory. (See "Building and releasing packages" above). Then run:
2183 autoheader && autoconf && ./configure
2187 --------------------------------------------------------------------------
2191 First, make sure that you have freshly exported the right version into an
2192 empty directory. (See "Building and releasing packages" above). Then run:
2195 autoheader && autoconf && ./configure
2199 --------------------------------------------------------------------------
2203 Login to Sourceforge's compilefarm via ssh:
2205 ssh cf.sourceforge.net
2207 Choose the right operating system. When logged in, make sure that you have
2208 freshly exported the right version into an empty directory. (See "Building
2209 and releasing packages" above). Then run:
2212 autoheader && autoconf && ./configure
2218 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload
2219 on the Sourceforge machine (no ncftpput). You now have to manually upload
2220 the archive to Sourceforge's ftp server and release the file publicly. Use
2221 the release notes and Change Log from the source tarball package.
2223 --------------------------------------------------------------------------
2225 6.4. Uploading and Releasing Your Package
2227 After the package is ready, it is time to upload it to SourceForge, and go
2228 through the release steps. The upload is done via FTP:
2230 * Upload to: ftp://upload.sourceforge.net/incoming
2234 * password: ijbswa-developers@lists.sourceforge.net
2236 Or use the make targets as described above.
2238 Once this done go to
2239 http://sourceforge.net/project/admin/editpackages.php?group_id=11118,
2240 making sure you are logged in. Find your target platform in the second
2241 column, and click Add Release. You will then need to create a new release
2242 for your package, using the format of $VERSION ($CODE_STATUS), e.g. 3.0.8
2245 Now just follow the prompts. Be sure to add any appropriate Release notes.
2246 You should see your freshly uploaded packages in "Step 2. Add Files To
2247 This Release". Check the appropriate box(es). Remember at each step to hit
2248 the "Refresh/Submit" buttons! You should now see your file(s) listed in
2249 Step 3. Fill out the forms with the appropriate information for your
2250 platform, being sure to hit "Update" for each file. If anyone is
2251 monitoring your platform, check the "email" box at the very bottom to
2252 notify them of the new package. This should do it!
2254 If you have made errors, or need to make changes, you can go through
2255 essentially the same steps, but select Edit Release, instead of Add
2258 --------------------------------------------------------------------------
2260 6.5. After the Release
2262 When all (or: most of the) packages have been uploaded and made available,
2263 send an email to the announce mailing list, Subject: "Version X.Y.Z
2264 available for download". Be sure to include the download location, the
2265 release notes and the Changelog. Also, post an updated News item on the
2266 project page Sourceforge, and update the Home page and docs linked from
2267 the Home page (see below). Other news sites and release oriented sites,
2268 such as Freshmeat, should also be notified.
2270 --------------------------------------------------------------------------
2272 7. Update the Webserver
2274 The webserver should be updated at least with each stable release. When
2275 updating, please follow these steps to make sure that no broken links,
2276 inconsistent contents or permission problems will occur (as it has many
2277 times in the past!):
2279 If you have changed anything in the stable-branch documentation source
2282 make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
2284 That will generate doc/webserver/user-manual,
2285 doc/webserver/developer-manual, doc/webserver/faq, doc/pdf/*.pdf and
2286 doc/webserver/index.html automatically.
2288 If you changed the manual page sources, generate
2289 doc/webserver/man-page/privoxy-man-page.html by running "make man". (This
2290 is a separate target due to dependencies on some obscure perl scripts [now
2291 in CVS, but not well tested]. See comments in GNUmakefile.)
2293 If you want to add new files to the webserver, create them locally in the
2294 doc/webserver/* directory (or create new directories under doc/webserver).
2296 Next, commit any changes from the above steps to CVS. All set? If these
2297 are docs in the stable branch, then do:
2301 This will do the upload to the webserver (www.privoxy.org) and ensure all
2302 files and directories there are group writable.
2304 Please do NOT use any other means of transferring files to the webserver
2305 to avoid permission problems. Also, please do not upload docs from
2306 development branches or versions. The publicly posted docs should be in
2307 sync with the last official release.
2309 --------------------------------------------------------------------------
2311 8. Contacting the developers, Bug Reporting and Feature Requests
2313 We value your feedback. In fact, we rely on it to improve Privoxy and its
2314 configuration. However, please note the following hints, so we can provide
2315 you with the best support:
2317 --------------------------------------------------------------------------
2321 For casual users, our support forum at SourceForge is probably best
2322 suited: http://sourceforge.net/tracker/?group_id=11118&atid=211118
2324 All users are of course welcome to discuss their issues on the users
2325 mailing list, where the developers also hang around.
2327 Note that the Privoxy mailing lists are moderated. Posts from unsubscribed
2328 addresses have to be accepted manually by a moderator. This may cause a
2329 delay of several days and if you use a subject that doesn't clearly
2330 mention Privoxy or one of its features, your message may be accidentally
2333 If you aren't subscribed, you should therefore spend a few seconds to come
2334 up with a proper subject. Additionally you should make it clear that you
2335 want to get CC'd. Otherwise some responses will be directed to the mailing
2336 list only, and you won't see them.
2338 --------------------------------------------------------------------------
2340 8.2. Reporting Problems
2342 "Problems" for our purposes, come in two forms:
2344 * Configuration issues, such as ads that slip through, or sites that
2345 don't function properly due to one Privoxy "action" or another being
2348 * "Bugs" in the programming code that makes up Privoxy, such as that
2349 might cause a crash.
2351 --------------------------------------------------------------------------
2353 8.2.1. Reporting Ads or Other Configuration Problems
2355 Please send feedback on ads that slipped through, innocent images that
2356 were blocked, sites that don't work properly, and other configuration
2357 related problem of default.action file, to
2358 http://sourceforge.net/tracker/?group_id=11118&atid=460288, the Actions
2361 New, improved default.action files may occasionally be made available
2362 based on your feedback. These will be announced on the ijbswa-announce
2363 list and available from our the files section of our project page.
2365 --------------------------------------------------------------------------
2367 8.2.2. Reporting Bugs
2369 Please report all bugs through our bug tracker:
2370 http://sourceforge.net/tracker/?group_id=11118&atid=111118.
2372 Before doing so, please make sure that the bug has not already been
2373 submitted and observe the additional hints at the top of the submit form.
2374 If already submitted, please feel free to add any info to the original
2375 report that might help to solve the issue.
2377 Please try to verify that it is a Privoxy bug, and not a browser or site
2378 bug or documented behaviour that just happens to be different than what
2379 you expected. If unsure, try toggling off Privoxy, and see if the problem
2382 If you are using your own custom configuration, please try the stock
2383 configs to see if the problem is configuration related. If you're having
2384 problems with a feature that is disabled by default, please ask around on
2385 the mailing list if others can reproduce the problem.
2387 If you aren't using the latest Privoxy version, the bug may have been
2388 found and fixed in the meantime. We would appreciate if you could take the
2389 time to upgrade to the latest version (or even the latest CVS snapshot)
2390 and verify that your bug still exists.
2392 Please be sure to provide the following information:
2394 * The exact Privoxy version you are using (if you got the source from
2395 CVS, please also provide the source code revisions as shown in
2396 http://config.privoxy.org/show-version).
2398 * The operating system and versions you run Privoxy on, (e.g. Windows XP
2399 SP2), if you are using a Unix flavor, sending the output of "uname -a"
2400 should do, in case of GNU/Linux, please also name the distribution.
2402 * The name, platform, and version of the browser you were using (e.g.
2403 Internet Explorer v5.5 for Mac).
2405 * The URL where the problem occurred, or some way for us to duplicate
2406 the problem (e.g. http://somesite.example.com/?somethingelse=123).
2408 * Whether your version of Privoxy is one supplied by the Privoxy
2409 developers via SourceForge, or if you got your copy somewhere else.
2411 * Whether you are using Privoxy in tandem with another proxy such as
2412 Tor. If so, please temporary disable the other proxy to see if the
2415 * Whether you are using a personal firewall product. If so, does Privoxy
2418 * Any other pertinent information to help identify the problem such as
2419 config or log file excerpts (yes, you should have log file entries for
2422 You don't have to tell us your actual name when filing a problem report,
2423 but please use a nickname so we can differentiate between your messages
2424 and the ones entered by other "anonymous" users that may respond to your
2425 request if they have the same problem or already found a solution.
2427 Please also check the status of your request a few days after submitting
2428 it, as we may request additional information. If you use a SF id, you
2429 should automatically get a mail when someone responds to your request.
2431 The appendix of the Privoxy User Manual also has helpful information on
2432 understanding actions, and action debugging.
2434 --------------------------------------------------------------------------
2436 8.3. Request New Features
2438 You are welcome to submit ideas on new features or other proposals for
2439 improvement through our feature request tracker at
2440 http://sourceforge.net/tracker/?atid=361118&group_id=11118.
2442 --------------------------------------------------------------------------
2446 For any other issues, feel free to use the mailing lists. Technically
2447 interested users and people who wish to contribute to the project are also
2448 welcome on the developers list! You can find an overview of all
2449 Privoxy-related mailing lists, including list archives, at:
2450 http://sourceforge.net/mail/?group_id=11118.
2452 --------------------------------------------------------------------------
2454 9. Privoxy Copyright, License and History
2456 Copyright (c) 2001-2008 by Privoxy Developers
2457 <ijbswa-developers@lists.sourceforge.net>
2459 Some source code is based on code Copyright (c) 1997 by Anonymous Coders
2460 and Junkbusters, Inc. and licensed under the GNU General Public License.
2462 --------------------------------------------------------------------------
2466 Privoxy is free software; you can redistribute it and/or modify it under
2467 the terms of the GNU General Public License, version 2, as published by
2468 the Free Software Foundation.
2470 This program is distributed in the hope that it will be useful, but
2471 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
2472 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
2473 for more details, which is available from the Free Software Foundation,
2474 Inc, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
2476 You should have received a copy of the GNU General Public License along
2477 with this program; if not, write to the
2480 Foundation, Inc. 51 Franklin Street, Fifth Floor
2481 Boston, MA 02110-1301
2484 --------------------------------------------------------------------------
2488 A long time ago, there was the Internet Junkbuster, by Anonymous Coders
2489 and Junkbusters Corporation. This saved many users a lot of pain in the
2490 early days of web advertising and user tracking.
2492 But the web, its protocols and standards, and with it, the techniques for
2493 forcing ads on users, give up autonomy over their browsing, and for
2494 tracking them, keeps evolving. Unfortunately, the Internet Junkbuster did
2495 not. Version 2.0.2, published in 1998, was (and is) the last official
2496 release available from Junkbusters Corporation. Fortunately, it had been
2497 released under the GNU GPL, which allowed further development by others.
2499 So Stefan Waldherr started maintaining an improved version of the
2500 software, to which eventually a number of people contributed patches. It
2501 could already replace banners with a transparent image, and had a first
2502 version of pop-up killing, but it was still very closely based on the
2503 original, with all its limitations, such as the lack of HTTP/1.1 support,
2504 flexible per-site configuration, or content modification. The last release
2505 from this effort was version 2.0.2-10, published in 2000.
2507 Then, some developers picked up the thread, and started turning the
2508 software inside out, upside down, and then reassembled it, adding many new
2509 features along the way.
2511 The result of this is Privoxy, whose first stable version, 3.0, was
2512 released August, 2002.
2514 --------------------------------------------------------------------------
2518 Other references and sites of interest to Privoxy users:
2520 http://www.privoxy.org/, the Privoxy Home page.
2522 http://www.privoxy.org/faq/, the Privoxy FAQ.
2524 http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on
2527 http://config.privoxy.org/, the web-based user interface. Privoxy must be
2528 running for this to work. Shortcut: http://p.p/
2530 http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit
2531 "misses" and other configuration related suggestions to the developers.
2533 http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies
2534 are used to track web users.
2536 http://www.junkbusters.com/ijb.html, the original Internet Junkbuster.
2538 http://privacy.net/, a useful site to check what information about you is
2539 leaked while you browse the web.
2541 http://www.squid-cache.org/, a popular caching proxy, which is often used
2542 together with Privoxy.
2544 http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy
2545 with advanced features like pipelining, multiplexing and caching of
2546 partial instances. In many setups it can be used as Squid replacement.
2548 http://tor.eff.org/, Tor can help anonymize web browsing, web publishing,
2549 instant messaging, IRC, SSH, and other applications.
2551 http://www.privoxy.org/developer-manual/, the Privoxy developer manual.
projects / privoxy.git / blob