1 Privoxy Developer Manual
3 [ Copyright 2001-2008 by Privoxy Developers ]
5 $Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $
7 The developer manual provides guidance on coding, testing, packaging,
8 documentation and other issues of importance to those involved with Privoxy
9 development. It is mandatory (and helpful!) reading for anyone who wants to
10 join the team. Note that it's currently out of date and may not be entirely
11 correct. As always, patches are welcome.
13 Please note that this document is constantly evolving. This copy represents the
14 state at the release of version 3.0.8. You can find the latest version of the
15 this manual at http://www.privoxy.org/developer-manual/. Please see the Contact
16 section on how to contact the developers.
18 -------------------------------------------------------------------------------
23 1.1. Quickstart to Privoxy Development
29 2.3. CVS Commit Guidelines
31 3. Documentation Guidelines
33 3.1. Quickstart to Docbook and SGML
34 3.2. Privoxy Documentation Style
35 3.3. Privoxy Custom Entities
42 4.2.1. Comment, Comment, Comment
43 4.2.2. Use blocks for comments
44 4.2.3. Keep Comments on their own line
45 4.2.4. Comment each logical step
46 4.2.5. Comment All Functions Thoroughly
47 4.2.6. Comment at the end of braces if the content is more than one
50 4.3. Naming Conventions
54 4.3.3. Header file prototypes
55 4.3.4. Enumerations, and #defines
60 4.4.1. Put braces on a line by themselves.
61 4.4.2. ALL control statements should have a block
62 4.4.3. Do not belabor/blow-up boolean expressions
63 4.4.4. Use white space freely because it is free
64 4.4.5. Don't use white space around structure operators
65 4.4.6. Make the last brace of a function stand out
66 4.4.7. Use 3 character indentions
70 4.5.1. Initialize all variables
74 4.6.1. Name functions that return a boolean as a question.
75 4.6.2. Always specify a return type for a function.
76 4.6.3. Minimize function calls when iterating by using variables
77 4.6.4. Pass and Return by Const Reference
78 4.6.5. Pass and Return by Value
79 4.6.6. Names of include files
80 4.6.7. Provide multiple inclusion protection
81 4.6.8. Use `extern "C"` when appropriate
82 4.6.9. Where Possible, Use Forward Struct Declaration Instead of
85 4.7. General Coding Practices
87 4.7.1. Turn on warnings
88 4.7.2. Provide a default case for all switch statements
89 4.7.3. Try to avoid falling through cases in a switch statement.
90 4.7.4. Use 'long' or 'short' Instead of 'int'
91 4.7.5. Don't mix size_t and other types
92 4.7.6. Declare each variable and struct on its own line.
93 4.7.7. Use malloc/zalloc sparingly
94 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
96 4.7.9. Add loaders to the `file_list' structure and in order
97 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
100 4.8. Addendum: Template for files and function comment blocks:
102 5. Testing Guidelines
104 5.1. Testplan for releases
107 6. Releasing a New Version
110 6.2. Before the Release: Freeze
111 6.3. Building and Releasing the Packages
113 6.3.1. Note on Privoxy Packaging
114 6.3.2. Source Tarball
115 6.3.3. SuSE, Conectiva or Red Hat RPM
126 6.4. Uploading and Releasing Your Package
127 6.5. After the Release
129 7. Update the Webserver
130 8. Contacting the developers, Bug Reporting and Feature Requests
133 8.2. Reporting Problems
135 8.2.1. Reporting Ads or Other Configuration Problems
136 8.2.2. Reporting Bugs
138 8.3. Request New Features
141 9. Privoxy Copyright, License and History
150 Privoxy, as an heir to Junkbuster, is a Free Software project and the code is
151 licensed under the GPL. As such, Privoxy development is potentially open to
152 anyone who has the time, knowledge, and desire to contribute in any capacity.
153 Our goals are simply to continue the mission, to improve Privoxy, and to make
154 it available to as wide an audience as possible.
156 One does not have to be a programmer to contribute. Packaging, testing,
157 documenting and porting, are all important jobs as well.
159 -------------------------------------------------------------------------------
161 1.1. Quickstart to Privoxy Development
163 The first step is to join the developer's mailing list. You can submit your
164 ideas, or even better patches. Patches are best submitted to the Sourceforge
165 tracker set up for this purpose, but can be sent to the list for review too.
167 You will also need to have a cvs package installed, which will entail having
168 ssh installed as well (which seems to be a requirement of SourceForge), in
169 order to access the cvs repository. Having the GNU build tools is also going to
170 be important (particularly, autoconf and gmake).
172 For the time being (read, this section is under construction), you can also
173 refer to the extensive comments in the source code. In fact, reading the code
174 is recommended in any case.
176 -------------------------------------------------------------------------------
178 2. The CVS Repository
180 If you become part of the active development team, you will eventually need
181 write access to our holy grail, the CVS repository. One of the team members
182 will need to set this up for you. Please read this chapter completely before
185 -------------------------------------------------------------------------------
189 The project's CVS repository is hosted on SourceForge. Please refer to the
190 chapters 6 and 7 in SF's site documentation for the technical access details
191 for your operating system. For historical reasons, the CVS server is called
192 ijbswa.cvs.sourceforge.net, the repository is called ijbswa, and the source
193 tree module is called current.
195 -------------------------------------------------------------------------------
199 Within the CVS repository, there are modules and branches. As mentioned, the
200 sources are in the current "module". Other modules are present for platform
201 specific issues. There is a webview of the CVS hierarchy at http://
202 ijbswa.cvs.sourceforge.net/ijbswa/, which might help with visualizing how these
205 Branches are used to fork a sub-development path from the main trunk. Within
206 the current module where the sources are, there is always at least one "branch"
207 from the main trunk devoted to a stable release series. The main trunk is where
208 active development takes place for the next stable series (e.g. 3.2.x). So just
209 prior to each stable series (e.g. 3.0.x), a branch is created just for stable
210 series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable
211 release of any stable branch has taken place, this branch is only used for
212 bugfixes, which have had prior testing before being committed to CVS. (See
213 Version Numbers below for details on versioning.)
215 At one time there were two distinct branches: stable and unstable. The more
216 drastic changes were to be in the unstable branch. These branches have now been
217 merged to minimize time and effort of maintaining two branches.
219 -------------------------------------------------------------------------------
221 2.3. CVS Commit Guidelines
223 The source tree is the heart of every software project. Every effort must be
224 made to ensure that it is readable, compilable and consistent at all times.
225 There are differing guidelines for the stable branch and the main development
226 trunk, and we ask anyone with CVS access to strictly adhere to the following
229 Basic Guidelines, for all branches:
231 * Please don't commit even a small change without testing it thoroughly
232 first. When we're close to a public release, ask a fellow developer to
235 * Your commit message should give a concise overview of what you changed (no
236 big details) and why you changed it Just check previous messages for good
239 * Don't use the same message on multiple files, unless it equally applies to
242 * If your changes span multiple files, and the code won't recompile unless
243 all changes are committed (e.g. when changing the signature of a function),
244 then commit all files one after another, without long delays in between. If
245 necessary, prepare the commit messages in advance.
247 * Before changing things on CVS, make sure that your changes are in line with
248 the team's general consensus on what should be done.
250 * Note that near a major public release, we get more cautious. There is
251 always the possibility to submit a patch to the patch tracker instead.
253 -------------------------------------------------------------------------------
255 3. Documentation Guidelines
257 All formal documents are maintained in Docbook SGML and located in the doc/
258 source/* directory. You will need Docbook, the Docbook DTD's and the Docbook
259 modular stylesheets (or comparable alternatives), and either jade or openjade
260 (recommended) installed in order to build docs from source. Currently there is
261 user-manual, FAQ, and, of course this, the developer-manual in this format. The
262 README, AUTHORS, INSTALL, privoxy.1 (man page), and config files are also now
263 maintained as Docbook SGML. These files, when built, in the top-level source
264 directory are generated files! Also, the Privoxy index.html (and a variation on
265 this file, privoxy-index.html, meant for inclusion with doc packages), are
266 maintained as SGML as well. DO NOT edit these directly. Edit the SGML source,
267 or contact someone involved in the documentation.
269 config requires some special handling. The reason it is maintained this way is
270 so that the extensive comments in the file mirror those in user-manual. But the
271 conversion process requires going from SGML to HTML to text to special
272 formatting required for the embedded comments. Some of this does not survive so
273 well. Especially some of the examples that are longer than 80 characters. The
274 build process for this file outputs to config.new, which should be reviewed for
275 errors and mis-formatting. Once satisfied that it is correct, then it should be
276 hand copied to config.
278 Other, less formal documents (e.g. LICENSE) are maintained as plain text files
279 in the top-level source directory.
281 Packagers are encouraged to include this documentation. For those without the
282 ability to build the docs locally, text versions of each are kept in CVS. HTML
283 versions are also being kept in CVS under doc/webserver/*. And PDF version are
286 Formal documents are built with the Makefile targets of make dok, or
287 alternately make redhat-dok. If you have problems, try both. The build process
288 uses the document SGML sources in doc/source/*/* to update all text files in
289 doc/text/ and to update all HTML documents in doc/webserver/.
291 Documentation writers should please make sure documents build successfully
292 before committing to CVS, if possible.
294 How do you update the webserver (i.e. the pages on privoxy.org)?
296 1. First, build the docs by running make dok (or alternately make redhat-dok).
297 For PDF docs, do make dok-pdf.
299 2. Run make webserver which copies all files from doc/webserver to the
300 sourceforge webserver via scp.
302 Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html)
303 so that those without the ability to build them locally, have access to them if
304 needed. This is especially important just prior to a new release! Please do
305 this after the $VERSION and other release specific data in configure.in has
306 been updated (this is done just prior to a new release).
308 -------------------------------------------------------------------------------
310 3.1. Quickstart to Docbook and SGML
312 If you are not familiar with SGML, it is a markup language similar to HTML.
313 Actually, not a mark up language per se, but a language used to define markup
314 languages. In fact, HTML is an SGML application. Both will use "tags" to format
315 text and other content. SGML tags can be much more varied, and flexible, but do
316 much of the same kinds of things. The tags, or "elements", are definable in
317 SGML. There is no set "standards". Since we are using Docbook, our tags are
318 those that are defined by Docbook. Much of how the finish document is rendered
319 is determined by the "stylesheets". The stylesheets determine how each tag gets
320 translated to HTML, or other formats.
322 Tags in Docbook SGML need to be always "closed". If not, you will likely
323 generate errors. Example: <title>My Title</title>. They are also
324 case-insensitive, but we strongly suggest using all lower case. This keeps
325 compatibility with [Docbook] XML.
327 Our documents use "sections" for the most part. Sections will be processed into
328 HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to
329 also generate the Table of Contents for each doc. Our TOC's are set to a depth
330 of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will
331 not. Each section requires a <title> element, and at least one <para>. There is
332 a limit of five section levels in Docbook, but generally three should be
333 sufficient for our purposes.
335 Some common elements that you likely will use:
337 <para></para>, paragraph delimiter. Most text needs to be within paragraph
338 elements (there are some exceptions).
339 <emphasis></emphasis>, the stylesheets make this italics.
340 <filename></filename>, files and directories.
341 <command></command>, command examples.
342 <literallayout></literallayout>, like <pre>, more or less.
343 <itemizedlist></itemizedlist>, list with bullets.
344 <listitem></listitem>, member of the above.
345 <screen></screen>, screen output, implies <literallayout>.
346 <ulink url="example.com"></ulink>, like HTML <a> tag.
347 <quote></quote>, for, doh, quoting text.
349 Look at any of the existing docs for examples of all these and more.
351 You might also find "Writing Documentation Using DocBook - A Crash Course"
354 -------------------------------------------------------------------------------
356 3.2. Privoxy Documentation Style
358 It will be easier if everyone follows a similar writing style. This just makes
359 it easier to read what someone else has written if it is all done in a similar
364 * All tags should be lower case.
366 * Tags delimiting a block of text (even small blocks) should be on their own
374 Tags marking individual words, or few words, should be in-line:
376 Just to <emphasis>emphasize</emphasis>, some text goes here.
379 * Tags should be nested and step indented for block text like: (except
386 Some text goes here in our list example.
393 This makes it easier to find the text amongst the tags ;-)
395 * Use white space to separate logical divisions within a document, like
396 between sections. Running everything together consistently makes it harder
399 * Do not hesitate to make comments. Comments can either use the <comment>
400 element, or the <!-- --> style comment familiar from HTML. (Note in Docbook
401 v4.x <comment> is replaced by <remark>.)
403 * We have an international audience. Refrain from slang, or English
404 idiosyncrasies (too many to list :). Humor also does not translate well
407 * Try to keep overall line lengths in source files to 80 characters or less
408 for obvious reasons. This is not always possible, with lengthy URLs for
411 * Our documents are available in differing formats. Right now, they are just
412 plain text, HTML, and PDF, but others are always a future possibility. Be
413 careful with URLs (<ulink>), and avoid this mistake:
415 My favorite site is <ulink url="http://example.com">here</ulink>.
417 This will render as "My favorite site is here", which is not real helpful
418 in a text doc. Better like this:
420 My favorite site is <ulink url="http://example.com">example.com</ulink>.
422 * All documents should be spell checked occasionally. aspell can check SGML
423 with the -H option. (ispell I think too.)
425 -------------------------------------------------------------------------------
427 3.3. Privoxy Custom Entities
429 Privoxy documentation is using a number of customized "entities" to facilitate
430 documentation maintenance.
432 We are using a set of "boilerplate" files with generic text, that is used by
433 multiple docs. This way we can write something once, and use it repeatedly
434 without having to re-write the same content over and over again. If editing
435 such a file, keep in mind that it should be generic. That is the purpose; so it
436 can be used in varying contexts without additional modifications.
438 We are also using what Docbook calls "internal entities". These are like
439 variables in programming. Well, sort of. For instance, we have the p-version
440 entity that contains the current Privoxy version string. You are strongly
441 encouraged to use these where possible. Some of these obviously require
442 re-setting with each release (done by the Makefile). A sampling of custom
443 entities are listed below. See any of the main docs for examples.
445 * Re- "boilerplate" text entities are defined like:
447 <!entity supported SYSTEM "supported.sgml">
449 In this example, the contents of the file, supported.sgml is available for
450 inclusion anywhere in the doc. To make this happen, just reference the now
451 defined entity: &supported; (starts with an ampersand and ends with a
452 semi-colon), and the contents will be dumped into the finished doc at that
455 * Commonly used "internal entities":
457 p-version: the Privoxy version string, e.g. "3.0.8".
458 p-status: the project status, either "alpha", "beta", or "stable".
459 p-not-stable: use to conditionally include text in "not stable" releases
461 p-stable: just the opposite.
462 p-text: this doc is only generated as text.
464 There are others in various places that are defined for a specific purpose.
467 -------------------------------------------------------------------------------
473 This set of standards is designed to make our lives easier. It is developed
474 with the simple goal of helping us keep the "new and improved Privoxy"
475 consistent and reliable. Thus making maintenance easier and increasing chances
476 of success of the project.
478 And that of course comes back to us as individuals. If we can increase our
479 development and product efficiencies then we can solve more of the request for
480 changes/improvements and in general feel good about ourselves. ;->
482 -------------------------------------------------------------------------------
486 4.2.1. Comment, Comment, Comment
490 Comment as much as possible without commenting the obvious. For example do not
491 comment "variable_a is equal to variable_b". Instead explain why variable_a
492 should be equal to the variable_b. Just because a person can read code does not
493 mean they will understand why or what is being done. A reader may spend a lot
494 more time figuring out what is going on when a simple comment or explanation
495 would have prevented the extra research. Please help your brother IJB'ers out!
497 The comments will also help justify the intent of the code. If the comment
498 describes something different than what the code is doing then maybe a
499 programming error is occurring.
503 /* if page size greater than 1k ... */
504 if ( page_length() > 1024 )
506 ... "block" the page up ...
509 /* if page size is small, send it in blocks */
510 if ( page_length() > 1024 )
512 ... "block" the page up ...
515 This demonstrates 2 cases of "what not to do". The first is a
516 "syntax comment". The second is a comment that does not fit what
517 is actually being done.
520 -------------------------------------------------------------------------------
522 4.2.2. Use blocks for comments
526 Comments can help or they can clutter. They help when they are differentiated
527 from the code they describe. One line comments do not offer effective
528 separation between the comment and the code. Block identifiers do, by
529 surrounding the code with a clear, definable pattern.
533 /*********************************************************************
534 * This will stand out clearly in your code!
535 *********************************************************************/
536 if ( this_variable == that_variable )
538 do_something_very_important();
542 /* unfortunately, this may not */
543 if ( this_variable == that_variable )
545 do_something_very_important();
549 if ( this_variable == that_variable ) /* this may not either */
551 do_something_very_important();
557 If you are trying to add a small logic comment and do not wish to "disrupt" the
558 flow of the code, feel free to use a 1 line comment which is NOT on the same
561 -------------------------------------------------------------------------------
563 4.2.3. Keep Comments on their own line
567 It goes back to the question of readability. If the comment is on the same line
568 as the code it will be harder to read than the comment that is on its own line.
570 There are three exceptions to this rule, which should be violated freely and
571 often: during the definition of variables, at the end of closing braces, when
572 used to comment parameters.
576 /*********************************************************************
577 * This will stand out clearly in your code,
578 * But the second example won't.
579 *********************************************************************/
580 if ( this_variable == this_variable )
582 do_something_very_important();
585 if ( this_variable == this_variable ) /*can you see me?*/
587 do_something_very_important(); /*not easily*/
591 /*********************************************************************
592 * But, the encouraged exceptions:
593 *********************************************************************/
594 int urls_read = 0; /* # of urls read + rejected */
595 int urls_rejected = 0; /* # of urls rejected */
599 do_something_very_important();
603 short do_something_very_important(
604 short firstparam, /* represents something */
605 short nextparam /* represents something else */ )
609 } /* -END- do_something_very_important */
612 -------------------------------------------------------------------------------
614 4.2.4. Comment each logical step
618 Logical steps should be commented to help others follow the intent of the
619 written code and comments will make the code more readable.
621 If you have 25 lines of code without a comment, you should probably go back
622 into it to see where you forgot to put one.
624 Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
625 these are usually major logic containers.
627 -------------------------------------------------------------------------------
629 4.2.5. Comment All Functions Thoroughly
633 A reader of the code should be able to look at the comments just prior to the
634 beginning of a function and discern the reason for its existence and the
635 consequences of using it. The reader should not have to read through the code
636 to determine if a given function is safe for a desired use. The proper
637 information thoroughly presented at the introduction of a function not only
638 saves time for subsequent maintenance or debugging, it more importantly aids in
639 code reuse by allowing a user to determine the safety and applicability of any
640 function for the problem at hand. As a result of such benefits, all functions
641 should contain the information presented in the addendum section of this
644 -------------------------------------------------------------------------------
646 4.2.6. Comment at the end of braces if the content is more than one screen
651 Each closing brace should be followed on the same line by a comment that
652 describes the origination of the brace if the original brace is off of the
653 screen, or otherwise far away from the closing brace. This will simplify the
654 debugging, maintenance, and readability of the code.
656 As a suggestion , use the following flags to make the comment and its brace
659 use following a closing brace: } /* -END- if() or while () or etc... */
665 do_something_very_important();
666 ...some long list of commands...
667 } /* -END- if x is 1 */
673 do_something_very_important();
674 ...some long list of commands...
675 } /* -END- if ( 1 == X ) */
678 -------------------------------------------------------------------------------
680 4.3. Naming Conventions
682 4.3.1. Variable Names
686 Use all lowercase, and separate words via an underscore ('_'). Do not start an
687 identifier with an underscore. (ANSI C reserves these for use by the compiler
688 and system headers.) Do not use identifiers which are reserved in ANSI C++.
689 (E.g. template, class, true, false, ...). This is in case we ever decide to
694 int ms_iis5_hack = 0;
699 int msiis5hack = 0; int msIis5Hack = 0;
702 -------------------------------------------------------------------------------
704 4.3.2. Function Names
708 Use all lowercase, and separate words via an underscore ('_'). Do not start an
709 identifier with an underscore. (ANSI C reserves these for use by the compiler
710 and system headers.) Do not use identifiers which are reserved in ANSI C++.
711 (E.g. template, class, true, false, ...). This is in case we ever decide to
716 int load_some_file( struct client_state *csp )
721 int loadsomefile( struct client_state *csp )
722 int loadSomeFile( struct client_state *csp )
725 -------------------------------------------------------------------------------
727 4.3.3. Header file prototypes
731 Use a descriptive parameter name in the function prototype in header files. Use
732 the same parameter name in the header file that you use in the c file.
736 (.h) extern int load_aclfile( struct client_state *csp );
737 (.c) int load_aclfile( struct client_state *csp )
742 (.h) extern int load_aclfile( struct client_state * ); or
743 (.h) extern int load_aclfile();
744 (.c) int load_aclfile( struct client_state *csp )
747 -------------------------------------------------------------------------------
749 4.3.4. Enumerations, and #defines
753 Use all capital letters, with underscores between words. Do not start an
754 identifier with an underscore. (ANSI C reserves these for use by the compiler
759 (enumeration) : enum Boolean { FALSE, TRUE };
760 (#define) : #define DEFAULT_SIZE 100;
763 Note: We have a standard naming scheme for #defines that toggle a feature in
764 the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word)
769 #define FEATURE_FORCE 1
772 #define FORCE_PREFIX blah
773 #endif /* def FEATURE_FORCE */
776 -------------------------------------------------------------------------------
782 Spell common words out entirely (do not remove vowels).
784 Use only widely-known domain acronyms and abbreviations. Capitalize all letters
787 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
788 terminate a name with an underscore.
792 #define USE_IMAGE_LIST 1
797 #define USE_IMG_LST 1 or
798 #define _USE_IMAGE_LIST 1 or
799 #define USE_IMAGE_LIST_ 1 or
800 #define use_image_list 1 or
801 #define UseImageList 1
804 -------------------------------------------------------------------------------
808 4.4.1. Put braces on a line by themselves.
812 The brace needs to be on a line all by itself, not at the end of the statement.
813 Curly braces should line up with the construct that they're associated with.
814 This practice makes it easier to identify the opening and closing braces for a
827 if ( this == that ) { ... }
831 if ( this == that ) { ... }
833 Note: In the special case that the if-statement is inside a loop, and it is
834 trivial, i.e. it tests for a condition that is obvious from the purpose of the
835 block, one-liners as above may optically preserve the loop structure and make
838 Status: developer-discretion.
842 while ( more lines are read )
844 /* Please document what is/is not a comment line here */
845 if ( it's a comment ) continue;
847 do_something( line );
851 -------------------------------------------------------------------------------
853 4.4.2. ALL control statements should have a block
857 Using braces to make a block will make your code more readable and less prone
858 to error. All control statements should have a block defined.
871 if ( this == that ) do_something(); do_something_else();
875 if ( this == that ) do_something();
877 Note: The first example in "Instead of" will execute in a manner other than
878 that which the developer desired (per indentation). Using code braces would
879 have prevented this "feature". The "explanation" and "exception" from the point
882 -------------------------------------------------------------------------------
884 4.4.3. Do not belabor/blow-up boolean expressions
888 structure->flag = ( condition );
893 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
895 Note: The former is readable and concise. The later is wordy and inefficient.
896 Please assume that any developer new to the project has at least a "good"
897 knowledge of C/C++. (Hope I do not offend by that last comment ... 8-)
899 -------------------------------------------------------------------------------
901 4.4.4. Use white space freely because it is free
905 Make it readable. The notable exception to using white space freely is listed
906 in the next guideline.
912 int another_value = 0;
913 int this_variable = 0;
915 if ( this_variable == this_variable )
917 first_value = old_value + ( ( some_value - another_value ) - whatever )
920 -------------------------------------------------------------------------------
922 4.4.5. Don't use white space around structure operators
926 - structure pointer operator ( "->" ) - member operator ( "." ) - functions and
929 It is a general coding practice to put pointers, references, and function
930 parentheses next to names. With spaces, the connection between the object and
931 variable/function name is not as clear.
940 Instead of: a_struct -> a_member; a_struct . a_member; function_name ();
942 -------------------------------------------------------------------------------
944 4.4.6. Make the last brace of a function stand out
953 } /* -END- function1 */
958 } /* -END- function2 */
963 int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) {
966 Note: Use 1 blank line before the closing brace and 2 lines afterward. This
967 makes the end of function standout to the most casual viewer. Although function
968 comments help separate functions, this is still a good coding practice. In
969 fact, I follow these rules when using blocks in "for", "while", "do" loops, and
970 long if {} statements too. After all whitespace is free!
972 Status: developer-discretion on the number of blank lines. Enforced is the end
973 of function comments.
975 -------------------------------------------------------------------------------
977 4.4.7. Use 3 character indentions
981 If some use 8 character TABs and some use 3 character TABs, the code can look
982 *very* ragged. So use 3 character indentions only. If you like to use TABs,
983 pass your code through a filter such as "expand -t3" before checking in your
988 static const char * const url_code_map[256] =
998 return( ALWAYS_TRUE );
1002 return( HOW_DID_YOU_GET_HERE );
1005 return( NEVER_GETS_HERE );
1010 -------------------------------------------------------------------------------
1014 4.5.1. Initialize all variables
1018 Do not assume that the variables declared will not be used until after they
1019 have been assigned a value somewhere else in the code. Remove the chance of
1020 accidentally using an unassigned variable.
1029 Note: It is much easier to debug a SIGSEGV if the message says you are trying
1030 to access memory address 00000000 and not 129FA012; or array_ptr[20] causes a
1031 SIGSEV vs. array_ptr[0].
1033 Status: developer-discretion if and only if the variable is assigned a value
1034 "shortly after" declaration.
1036 -------------------------------------------------------------------------------
1040 4.6.1. Name functions that return a boolean as a question.
1044 Value should be phrased as a question that would logically be answered as a
1045 true or false statement
1049 should_we_block_this();
1050 contains_an_image();
1051 is_web_page_blank();
1054 -------------------------------------------------------------------------------
1056 4.6.2. Always specify a return type for a function.
1060 The default return for a function is an int. To avoid ambiguity, create a
1061 return for a function when the return has a purpose, and create a void return
1062 type if the function does not need to return anything.
1064 -------------------------------------------------------------------------------
1066 4.6.3. Minimize function calls when iterating by using variables
1070 It is easy to write the following code, and a clear argument can be made that
1071 the code is easy to understand:
1075 for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
1081 Note: Unfortunately, this makes a function call for each and every iteration.
1082 This increases the overhead in the program, because the compiler has to look up
1083 the function each time, call it, and return a value. Depending on what occurs
1084 in the block_list_length() call, it might even be creating and destroying
1085 structures with each iteration, even though in each case it is comparing "cnt"
1086 to the same value, over and over. Remember too - even a call to
1087 block_list_length() is a function call, with the same overhead.
1089 Instead of using a function call during the iterations, assign the value to a
1090 variable, and evaluate using the variable.
1094 size_t len = block_list_length();
1096 for ( size_t cnt = 0; cnt < len; cnt++ )
1102 Exceptions: if the value of block_list_length() *may* change or could
1103 *potentially* change, then you must code the function call in the for/while
1106 -------------------------------------------------------------------------------
1108 4.6.4. Pass and Return by Const Reference
1112 This allows a developer to define a const pointer and call your function. If
1113 your function does not have the const keyword, we may not be able to use your
1114 function. Consider strcmp, if it were defined as: extern int strcmp( char *s1,
1117 I could then not use it to compare argv's in main: int main( int argc, const
1118 char *argv[] ) { strcmp( argv[0], "privoxy" ); }
1120 Both these pointers are *const*! If the c runtime library maintainers do it, we
1123 -------------------------------------------------------------------------------
1125 4.6.5. Pass and Return by Value
1129 Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes
1130 or less). Aka, a function declaration like: int load_aclfile( struct
1133 would not work. So, to be consistent, we should declare all prototypes with
1134 "pass by value": int load_aclfile( struct client_state *csp )
1136 -------------------------------------------------------------------------------
1138 4.6.6. Names of include files
1142 Your include statements should contain the file name without a path. The path
1143 should be listed in the Makefile, using -I as processor directive to search the
1144 indicated paths. An exception to this would be for some proprietary software
1145 that utilizes a partial path to distinguish their header files from system or
1150 #include <iostream.h> /* This is not a local include */
1151 #include "config.h" /* This IS a local include */
1156 /* This is not a local include, but requires a path element. */
1157 #include <sys/fileName.h>
1160 Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
1161 This duplicates the #include "file.h" behavior.
1163 -------------------------------------------------------------------------------
1165 4.6.7. Provide multiple inclusion protection
1169 Prevents compiler and linker errors resulting from redefinition of items.
1171 Wrap each header file with the following syntax to prevent multiple inclusions
1172 of the file. Of course, replace PROJECT_H with your file name, with "." Changed
1173 to "_", and make it uppercase.
1177 #ifndef PROJECT_H_INCLUDED
1178 #define PROJECT_H_INCLUDED
1180 #endif /* ndef PROJECT_H_INCLUDED */
1183 -------------------------------------------------------------------------------
1185 4.6.8. Use `extern "C"` when appropriate
1189 If our headers are included from C++, they must declare our functions as
1190 `extern "C"`. This has no cost in C, but increases the potential re-usability
1198 #endif /* def __cplusplus */
1200 ... function definitions here ...
1204 #endif /* def __cplusplus */
1207 -------------------------------------------------------------------------------
1209 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
1213 Useful in headers that include pointers to other struct's. Modifications to
1214 excess header files may cause needless compiles.
1218 /*********************************************************************
1219 * We're avoiding an include statement here!
1220 *********************************************************************/
1222 extern file_list *xyz;
1225 Note: If you declare "file_list xyz;" (without the pointer), then including the
1226 proper header file is necessary. If you only want to prototype a pointer,
1227 however, the header file is unnecessary.
1229 Status: Use with discretion.
1231 -------------------------------------------------------------------------------
1233 4.7. General Coding Practices
1235 4.7.1. Turn on warnings
1239 Compiler warnings are meant to help you find bugs. You should turn on as many
1240 as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as
1243 -------------------------------------------------------------------------------
1245 4.7.2. Provide a default case for all switch statements
1249 What you think is guaranteed is never really guaranteed. The value that you
1250 don't think you need to check is the one that someday will be passed. So, to
1251 protect yourself from the unknown, always have a default step in a switch
1256 switch( hash_string( cmd ) )
1258 case hash_actions_file :
1268 ... anomaly code goes here ...
1269 continue; / break; / exit( 1 ); / etc ...
1271 } /* end switch( hash_string( cmd ) ) */
1274 Note: If you already have a default condition, you are obviously exempt from
1275 this point. Of note, most of the WIN32 code calls `DefWindowProc' after the
1276 switch statement. This API call *should* be included in a default statement.
1278 Another Note: This is not so much a readability issue as a robust programming
1279 issue. The "anomaly code goes here" may be no more than a print to the STDERR
1280 stream (as in load_config). Or it may really be an abort condition.
1282 Status: Programmer discretion is advised.
1284 -------------------------------------------------------------------------------
1286 4.7.3. Try to avoid falling through cases in a switch statement.
1290 In general, you will want to have a 'break' statement within each 'case' of a
1291 switch statement. This allows for the code to be more readable and
1292 understandable, and furthermore can prevent unwanted surprises if someone else
1293 later gets creative and moves the code around.
1295 The language allows you to plan the fall through from one case statement to
1296 another simply by omitting the break statement within the case statement. This
1297 feature does have benefits, but should only be used in rare cases. In general,
1298 use a break statement for each case statement.
1300 If you choose to allow fall through, you should comment both the fact of the
1301 fall through and reason why you felt it was necessary.
1303 -------------------------------------------------------------------------------
1305 4.7.4. Use 'long' or 'short' Instead of 'int'
1309 On 32-bit platforms, int usually has the range of long. On 16-bit platforms,
1310 int has the range of short.
1312 Status: open-to-debate. In the case of most FSF projects (including X/
1313 GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I
1314 forget the exact typedefs now). Should we add these to IJB now that we have a
1317 -------------------------------------------------------------------------------
1319 4.7.5. Don't mix size_t and other types
1323 The type of size_t varies across platforms. Do not make assumptions about
1324 whether it is signed or unsigned, or about how long it is. Do not compare a
1325 size_t against another variable of a different type (or even against a
1326 constant) without casting one of the values.
1328 -------------------------------------------------------------------------------
1330 4.7.6. Declare each variable and struct on its own line.
1334 It can be tempting to declare a series of variables all on one line. Don't.
1347 Explanation: - there is more room for comments on the individual variables -
1348 easier to add new variables without messing up the original ones - when
1349 searching on a variable to find its type, there is less clutter to "visually"
1352 Exceptions: when you want to declare a bunch of loop variables or other trivial
1353 variables; feel free to declare them on one line. You should, although, provide
1354 a good comment on their functions.
1356 Status: developer-discretion.
1358 -------------------------------------------------------------------------------
1360 4.7.7. Use malloc/zalloc sparingly
1364 Create a local struct (on the stack) if the variable will live and die within
1365 the context of one function call.
1367 Only "malloc" a struct (on the heap) if the variable's life will extend beyond
1368 the context of one function call.
1372 If a function creates a struct and stores a pointer to it in a
1373 list, then it should definitely be allocated via `malloc'.
1376 -------------------------------------------------------------------------------
1378 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1382 If you have to "malloc" an instance, you are responsible for insuring that the
1383 instance is `free'd, even if the deallocation event falls within some other
1384 programmer's code. You are also responsible for ensuring that deletion is
1385 timely (i.e. not too soon, not too late). This is known as "low-coupling" and
1386 is a "good thing (tm)". You may need to offer a free/unload/destructor type
1387 function to accommodate this.
1391 int load_re_filterfile( struct client_state *csp ) { ... }
1392 static void unload_re_filterfile( void *f ) { ... }
1397 The developer cannot be expected to provide `free'ing functions for C run-time
1398 library functions ... such as `strdup'.
1400 Status: developer-discretion. The "main" use of this standard is for allocating
1401 and freeing data structures (complex or nested).
1403 -------------------------------------------------------------------------------
1405 4.7.9. Add loaders to the `file_list' structure and in order
1409 I have ordered all of the "blocker" file code to be in alpha order. It is
1410 easier to add/read new blockers when you expect a certain order.
1412 Note: It may appear that the alpha order is broken in places by POPUP tests
1413 coming before PCRS tests. But since POPUPs can also be referred to as
1414 KILLPOPUPs, it is clear that it should come first.
1416 -------------------------------------------------------------------------------
1418 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME or XXX
1422 If you have enough confidence in new code or confidence in your changes, but
1423 are not *quite* sure of the repercussions, add this:
1425 /* FIXME: this code has a logic error on platform XYZ, * attempting to fix */ #
1426 ifdef PLATFORM ...changed code here... #endif
1430 /* FIXME: I think the original author really meant this... */ ...changed code
1435 /* FIXME: new code that *may* break something else... */ ...new code here...
1437 Note: If you make it clear that this may or may not be a "good thing (tm)", it
1438 will be easier to identify and include in the project (or conversely exclude
1441 -------------------------------------------------------------------------------
1443 4.8. Addendum: Template for files and function comment blocks:
1445 Example for file comments:
1447 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $";
1448 /*********************************************************************
1452 * Purpose : (Fill me in with a good description!)
1454 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
1455 * Privoxy team. http://www.privoxy.org/
1457 * Based on the Internet Junkbuster originally written
1458 * by and Copyright (C) 1997 Anonymous Coders and
1459 * Junkbusters Corporation. http://www.junkbusters.com
1461 * This program is free software; you can redistribute it
1462 * and/or modify it under the terms of the GNU General
1463 * Public License as published by the Free Software
1464 * Foundation; either version 2 of the License, or (at
1465 * your option) any later version.
1467 * This program is distributed in the hope that it will
1468 * be useful, but WITHOUT ANY WARRANTY; without even the
1469 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1470 * PARTICULAR PURPOSE. See the GNU General Public
1471 * License for more details.
1473 * The GNU General Public License should be included with
1474 * this file. If not, you can view it at
1475 * http://www.gnu.org/copyleft/gpl.html
1476 * or write to the Free Software Foundation, Inc.,
1477 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1483 *********************************************************************/
1488 ...necessary include files for us to do our work...
1490 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1493 Note: This declares the rcs variables that should be added to the
1494 "show-proxy-args" page. If this is a brand new creation by you, you are free to
1495 change the "Copyright" section to represent the rights you wish to maintain.
1497 Note: The formfeed character that is present right after the comment flower box
1498 is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of
1499 the code (via `forward-page' and `backward-page'). Please include it if you
1502 Example for file header comments:
1506 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $"
1507 /*********************************************************************
1511 * Purpose : (Fill me in with a good description!)
1513 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
1514 * Privoxy team. http://www.privoxy.org/
1516 * Based on the Internet Junkbuster originally written
1517 * by and Copyright (C) 1997 Anonymous Coders and
1518 * Junkbusters Corporation. http://www.junkbusters.com
1520 * This program is free software; you can redistribute it
1521 * and/or modify it under the terms of the GNU General
1522 * Public License as published by the Free Software
1523 * Foundation; either version 2 of the License, or (at
1524 * your option) any later version.
1526 * This program is distributed in the hope that it will
1527 * be useful, but WITHOUT ANY WARRANTY; without even the
1528 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1529 * PARTICULAR PURPOSE. See the GNU General Public
1530 * License for more details.
1532 * The GNU General Public License should be included with
1533 * this file. If not, you can view it at
1534 * http://www.gnu.org/copyleft/gpl.html
1535 * or write to the Free Software Foundation, Inc.,
1536 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1542 *********************************************************************/
1545 #include "project.h"
1551 ... function headers here ...
1554 /* Revision control strings from this header and associated .c file */
1555 extern const char FILENAME_rcs[];
1556 extern const char FILENAME_h_rcs[];
1563 #endif /* ndef _FILENAME_H */
1572 Example for function comments:
1574 /*********************************************************************
1576 * Function : FUNCTION_NAME
1578 * Description : (Fill me in with a good description!)
1581 * 1 : param1 = pointer to an important thing
1582 * 2 : x = pointer to something else
1584 * Returns : 0 => Ok, everything else is an error.
1586 *********************************************************************/
1587 int FUNCTION_NAME( void *param1, const char *x )
1595 Note: If we all follow this practice, we should be able to parse our code to
1596 create a "self-documenting" web page.
1598 -------------------------------------------------------------------------------
1600 5. Testing Guidelines
1604 -------------------------------------------------------------------------------
1606 5.1. Testplan for releases
1608 Explain release numbers. major, minor. developer releases. etc.
1610 1. Remove any existing rpm with rpm -e
1612 2. Remove any file that was left over. This includes (but is not limited to)
1620 + /etc/init.d/privoxy
1624 3. Install the rpm. Any error messages?
1626 4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
1627 privoxy stop). Reboot your machine. Does autostart work?
1629 5. Start browsing. Does Privoxy work? Logfile written?
1631 6. Remove the rpm. Any error messages? All files removed?
1633 -------------------------------------------------------------------------------
1637 Please submit test reports only with the test form at sourceforge. Three simple
1640 * Select category: the distribution you test on.
1642 * Select group: the version of Privoxy that we are about to release.
1644 * Fill the Summary and Detailed Description with something intelligent (keep
1645 it short and precise).
1647 Do not mail to the mailing list (we cannot keep track on issues there).
1649 -------------------------------------------------------------------------------
1651 6. Releasing a New Version
1653 When we release versions of Privoxy, our work leaves our cozy secret lab and
1654 has to work in the cold RealWorld[tm]. Once it is released, there is no way to
1655 call it back, so it is very important that great care is taken to ensure that
1656 everything runs fine, and not to introduce problems in the very last minute.
1658 So when releasing a new version, please adhere exactly to the procedure
1659 outlined in this chapter.
1661 The following programs are required to follow this process: ncftpput (ncftp),
1662 scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
1664 -------------------------------------------------------------------------------
1666 6.1. Version numbers
1668 First you need to determine which version number the release will have. Privoxy
1669 version numbers consist of three numbers, separated by dots, like in X.Y.Z
1670 (e.g. 3.0.0), where:
1672 * X, the version major, is rarely ever changed. It is increased by one if
1673 turning a development branch into stable substantially changes the
1674 functionality, user interface or configuration syntax. Majors 1 and 2 were
1675 Junkbuster, and 3 will be the first stable Privoxy release.
1677 * Y, the version minor, represents the branch within the major version. At
1678 any point in time, there are two branches being maintained: The stable
1679 branch, with an even minor, say, 2N, in which no functionality is being
1680 added and only bug-fixes are made, and 2N+1, the development branch, in
1681 which the further development of Privoxy takes place. This enables us to
1682 turn the code upside down and inside out, while at the same time providing
1683 and maintaining a stable version. The minor is reset to zero (and one) when
1684 the major is incremented. When a development branch has matured to the
1685 point where it can be turned into stable, the old stable branch 2N is given
1686 up (i.e. no longer maintained), the former development branch 2N+1 becomes
1687 the new stable branch 2N+2, and a new development branch 2N+3 is opened.
1689 * Z, the point or sub version, represents a release of the software within a
1690 branch. It is therefore incremented immediately before each code freeze. In
1691 development branches, only the even point versions correspond to actual
1692 releases, while the odd ones denote the evolving state of the sources on
1693 CVS in between. It follows that Z is odd on CVS in development branches
1694 most of the time. There, it gets increased to an even number immediately
1695 before a code freeze, and is increased to an odd number again immediately
1696 thereafter. This ensures that builds from CVS snapshots are easily
1697 distinguished from released versions. The point version is reset to zero
1698 when the minor changes.
1700 Stable branches work a little differently, since there should be little to
1701 no development happening in such branches. Remember, only bugfixes, which
1702 presumably should have had some testing before being committed. Stable
1703 branches will then have their version reported as 0.0.0, during that period
1704 between releases when changes are being added. This is to denote that this
1705 code is not for release. Then as the release nears, the version is bumped
1706 according: e.g. 3.0.1 -> 0.0.0 -> 3.0.2.
1708 In summary, the main CVS trunk is the development branch where new features are
1709 being worked on for the next stable series. This should almost always be where
1710 the most activity takes place. There is always at least one stable branch from
1711 the trunk, e.g now it is 3.0, which is only used to release stable versions.
1712 Once the initial *.0 release of the stable branch has been done, then as a
1713 rule, only bugfixes that have had prior testing should be committed to the
1714 stable branch. Once there are enough bugfixes to justify a new release, the
1715 version of this branch is again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2,
1716 etc are all stable releases from within the stable branch. 3.1.x is currently
1717 the main trunk, and where work on 3.2.x is taking place. If any questions,
1718 please post to the devel list before committing to a stable branch!
1720 Developers should remember too that if they commit a bugfix to the stable
1721 branch, this will more than likely require a separate submission to the main
1722 trunk, since these are separate development trees within CVS. If you are
1723 working on both, then this would require at least two separate check outs (i.e
1724 main trunk, and the stable release branch, which is v_3_0_branch at the
1727 -------------------------------------------------------------------------------
1729 6.2. Before the Release: Freeze
1731 The following must be done by one of the developers prior to each new release.
1733 * Make sure that everybody who has worked on the code in the last couple of
1734 days has had a chance to yell "no!" in case they have pending changes/fixes
1735 in their pipelines. Announce the freeze so that nobody will interfere with
1736 last minute changes.
1738 * Increment the version number (point from odd to even in development
1739 branches!) in configure.in. (RPM spec files will need to be incremented as
1742 * If default.action has changed since last release (i.e. software release or
1743 standalone actions file release), bump up its version info to A.B in this
1746 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1749 Then change the version info in doc/webserver/actions/index.php, line:
1750 '$required_actions_file_version = "A.B";'
1752 * All documentation should be rebuild after the version bump. Finished docs
1753 should be then be committed to CVS (for those without the ability to build
1754 these). Some docs may require rather obscure processing tools. config, the
1755 man page (and the html version of the man page), and the PDF docs fall in
1756 this category. REAMDE, the man page, AUTHORS, and config should all also be
1757 committed to CVS for other packagers. The formal docs should be uploaded to
1758 the webserver. See the Section "Updating the webserver" in this manual for
1761 * The User Manual is also used for context sensitive help for the CGI editor.
1762 This is version sensitive, so that the user will get appropriate help for
1763 his/her release. So with each release a fresh version should be uploaded to
1764 the webserver (this is in addition to the main User Manual link from the
1765 main page since we need to keep manuals for various versions available).
1766 The CGI pages will link to something like http://privoxy.org/$(VERSION)/
1767 user-manual/. This will need to be updated for each new release. There is
1768 no Makefile target for this at this time!!! It needs to be done manually.
1770 * All developers should look at the ChangeLog and make sure noteworthy
1771 changes are referenced.
1773 * Commit all files that were changed in the above steps!
1775 * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't
1776 use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1778 * If the release was in a development branch, increase the point version from
1779 even to odd (X.Y.(Z+1)) again in configure.in and commit your change.
1781 * On the webserver, copy the user manual to a new top-level directory called
1782 X.Y.Z. This ensures that help links from the CGI pages, which have the
1783 version as a prefix, will go into the right version of the manual. If this
1784 is a development branch release, also symlink X.Y.(Z-1) to X.Y.Z and X.Y.
1785 (Z+1) to . (i.e. dot).
1787 -------------------------------------------------------------------------------
1789 6.3. Building and Releasing the Packages
1791 Now the individual packages can be built and released. Note that for GPL
1792 reasons the first package to be released is always the source tarball.
1794 For all types of packages, including the source tarball, you must make sure
1795 that you build from clean sources by exporting the right version from CVS into
1796 an empty directory (just press return when asked for a password):
1798 mkdir dist # delete or choose different name if it already exists
1800 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
1801 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1804 Do NOT change a single bit, including, but not limited to version information
1805 after export from CVS. This is to make sure that all release packages, and with
1806 them, all future bug reports, are based on exactly the same code.
1808 +-----------------------------------------------------------------------------+
1810 |-----------------------------------------------------------------------------|
1811 |Every significant release of Privoxy has included at least one package that |
1812 |either had incorrect versions of files, missing files, or incidental |
1813 |leftovers from a previous build process that gave unknown numbers of users |
1814 |headaches to try to figure out what was wrong. PLEASE, make sure you are |
1815 |using pristene sources, and are following the prescribed process! |
1816 +-----------------------------------------------------------------------------+
1818 Please find additional instructions for the source tarball and the individual
1819 platform dependent binary packages below. And details on the Sourceforge
1820 release process below that.
1822 -------------------------------------------------------------------------------
1824 6.3.1. Note on Privoxy Packaging
1826 Please keep these general guidelines in mind when putting together your
1827 package. These apply to all platforms!
1829 * Privoxy requires write access to: all *.action files, all logfiles, and the
1830 trust file. You will need to determine the best way to do this for your
1833 * Please include up to date documentation. At a bare minimum:
1835 LICENSE (top-level directory)
1837 README (top-level directory)
1839 AUTHORS (top-level directory)
1841 man page (top-level directory, Unix-like platforms only)
1843 The User Manual (doc/webserver/user-manual/)
1845 FAQ (doc/webserver/faq/)
1847 Also suggested: Developer Manual (doc/webserver/developer-manual) and
1848 ChangeLog (top-level directory). FAQ and the manuals are HTML docs. There
1849 are also text versions in doc/text/ which could conceivably also be
1852 The documentation has been designed such that the manuals are linked to
1853 each other from parallel directories, and should be packaged that way.
1854 privoxy-index.html can also be included and can serve as a focal point for
1855 docs and other links of interest (and possibly renamed to index.html). This
1856 should be one level up from the manuals. There is a link also on this page
1857 to an HTMLized version of the man page. To avoid 404 for this, it is in CVS
1858 as doc/webserver/man-page/privoxy-man-page.html, and should be included
1859 along with the manuals. There is also a css stylesheets that can be
1860 included for better presentation: p_doc.css. This should be in the same
1861 directory with privoxy-index.html, (i.e. one level up from the manual
1864 * user.action and user.filter are designed for local preferences. Make sure
1865 these do not get overwritten! config should not be overwritten either. This
1866 has especially important configuration data in it. trust should be left in
1869 * Other configuration files (default.action, default.filter and
1870 standard.action) should be installed as the new defaults, but all
1871 previously installed configuration files should be preserved as backups.
1872 This is just good manners :-) These files are likely to change between
1873 releases and contain important new features and bug fixes.
1875 * Please check platform specific notes in this doc, if you haven't done
1876 "Privoxy" packaging before for other platform specific issues. Conversely,
1877 please add any notes that you know are important for your platform (or
1878 contact one of the doc maintainers to do this if you can't).
1880 * Packagers should do a "clean" install of their package after building it.
1881 So any previous installs should be removed first to ensure the integrity of
1882 the newly built package. Then run the package for a while to make sure
1883 there are no obvious problems, before uploading.
1885 -------------------------------------------------------------------------------
1887 6.3.2. Source Tarball
1889 First, make sure that you have freshly exported the right version into an empty
1890 directory. (See "Building and releasing packages" above). Then run:
1893 autoheader && autoconf && ./configure
1901 To upload the package to Sourceforge, simply issue
1906 Go to the displayed URL and release the file publicly on Sourceforge. For the
1907 change log field, use the relevant section of the ChangeLog file.
1909 -------------------------------------------------------------------------------
1911 6.3.3. SuSE, Conectiva or Red Hat RPM
1913 In following text, replace dist with either "rh" for Red Hat or "suse" for
1916 First, make sure that you have freshly exported the right version into an empty
1917 directory. (See "Building and releasing packages" above).
1919 As the only exception to not changing anything after export from CVS, now
1920 examine the file privoxy-dist.spec and make sure that the version information
1921 and the RPM release number are correct. The RPM release numbers for each
1922 version start at one. Hence it must be reset to one if this is the first RPM
1923 for dist which is built from version X.Y.Z. Check the file list if unsure.
1924 Else, it must be set to the highest already available RPM release number for
1925 that version plus one.
1930 autoheader && autoconf && ./configure
1938 To upload the package to Sourceforge, simply issue
1940 make dist-upload rpm_packagerev
1943 where rpm_packagerev is the RPM release number as determined above. Go to the
1944 displayed URL and release the file publicly on Sourceforge. Use the release
1945 notes and change log from the source tarball package.
1947 -------------------------------------------------------------------------------
1951 First, make sure that you have freshly exported the right version into an empty
1952 directory. (See "Building and releasing packages" above). Then get the OS/2
1955 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
1958 You will need a mix of development tools. The main compilation takes place with
1959 IBM Visual Age C++. Some ancillary work takes place with GNU tools, available
1960 from various sources like hobbes.nmsu.edu. Specificially, you will need
1961 autoheader, autoconf and sh tools. The packaging takes place with WarpIN,
1962 available from various sources, including its home page: xworkplace.
1964 Change directory to the os2setup directory. Edit the os2build.cmd file to set
1965 the final executable filename. For example,
1967 installExeName='privoxyos2_setup_X.Y.Z.exe'
1970 Next, edit the IJB.wis file so the release number matches in the PACKAGEID
1973 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
1976 You're now ready to build. Run:
1981 You will find the WarpIN-installable executable in the ./files directory.
1982 Upload this anonymously to uploads.sourceforge.net/incoming, create a release
1983 for it, and you're done. Use the release notes and Change Log from the source
1986 -------------------------------------------------------------------------------
1990 Login to Sourceforge's compilefarm via ssh:
1992 ssh cf.sourceforge.net
1995 Choose the right operating system (not the Debian one). When logged in, make
1996 sure that you have freshly exported the right version into an empty directory.
1997 (See "Building and releasing packages" above). Then run:
2000 autoheader && autoconf && ./configure
2008 which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
2009 on the Sourceforge machine (no ncftpput). You now have to manually upload the
2010 archive to Sourceforge's ftp server and release the file publicly. Use the
2011 release notes and Change Log from the source tarball package.
2013 -------------------------------------------------------------------------------
2017 You should ensure you have the latest version of Cygwin (from http://
2018 www.cygwin.com/). Run the following commands from within a Cygwin bash shell.
2020 First, make sure that you have freshly exported the right version into an empty
2021 directory. (See "Building and releasing packages" above). Then get the Windows
2024 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
2027 Then you can build the package. This is fully automated, and is controlled by
2028 winsetup/GNUmakefile. All you need to do is:
2034 Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and
2035 upload it to SourceForge. When releasing the package on SourceForge, use the
2036 release notes and Change Log from the source tarball package.
2038 -------------------------------------------------------------------------------
2042 First, make sure that you have freshly exported the right version into an empty
2043 directory. (See "Building and releasing packages" above). Then add a log entry
2044 to debian/changelog, if it is not already there, for example by running:
2046 debchange -v 3.0.8-stable-1 "New upstream version"
2051 dpkg-buildpackage -rfakeroot -us -uc -b
2054 This will create ../privoxy_3.0.8-stable-1_i386.deb which can be uploaded. To
2055 upload the package to Sourceforge, simply issue
2060 -------------------------------------------------------------------------------
2064 First, make sure that you have freshly exported the right version into an empty
2065 directory. (See "Building and releasing packages" above). Then get the Mac OSX
2068 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
2077 This will run autoheader, autoconf and configure as well as make. Finally, it
2078 will copy over the necessary files to the ./osxsetup/files directory for
2079 further processing by PackageMaker.
2081 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the
2082 package name to match the release, and hit the "Create package" button. If you
2083 specify ./Privoxy.pkg as the output package name, you can then create the
2084 distributable zip file with the command:
2086 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2089 You can then upload privoxyosx_setup_x.y.z.zip anonymously to
2090 uploads.sourceforge.net/incoming, create a release for it, and you're done. Use
2091 the release notes and Change Log from the source tarball package.
2093 -------------------------------------------------------------------------------
2097 Login to Sourceforge's compile-farm via ssh:
2099 ssh cf.sourceforge.net
2102 Choose the right operating system. When logged in, make sure that you have
2103 freshly exported the right version into an empty directory. (See "Building and
2104 releasing packages" above). Then run:
2107 autoheader && autoconf && ./configure
2115 which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
2116 on the Sourceforge machine (no ncftpput). You now have to manually upload the
2117 archive to Sourceforge's ftp server and release the file publicly. Use the
2118 release notes and Change Log from the source tarball package.
2120 -------------------------------------------------------------------------------
2124 First, make sure that you have freshly exported the right version into an empty
2125 directory. (See "Building and releasing packages" above). Then run:
2128 autoheader && autoconf && ./configure
2133 -------------------------------------------------------------------------------
2137 First, make sure that you have freshly exported the right version into an empty
2138 directory. (See "Building and releasing packages" above). Then run:
2141 autoheader && autoconf && ./configure
2146 -------------------------------------------------------------------------------
2150 Login to Sourceforge's compilefarm via ssh:
2152 ssh cf.sourceforge.net
2155 Choose the right operating system. When logged in, make sure that you have
2156 freshly exported the right version into an empty directory. (See "Building and
2157 releasing packages" above). Then run:
2160 autoheader && autoconf && ./configure
2168 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
2169 the Sourceforge machine (no ncftpput). You now have to manually upload the
2170 archive to Sourceforge's ftp server and release the file publicly. Use the
2171 release notes and Change Log from the source tarball package.
2173 -------------------------------------------------------------------------------
2175 6.4. Uploading and Releasing Your Package
2177 After the package is ready, it is time to upload it to SourceForge, and go
2178 through the release steps. The upload is done via FTP:
2180 * Upload to: ftp://upload.sourceforge.net/incoming
2184 * password: ijbswa-developers@lists.sourceforge.net
2186 Or use the make targets as described above.
2188 Once this done go to http://sourceforge.net/project/admin/editpackages.php?
2189 group_id=11118, making sure you are logged in. Find your target platform in the
2190 second column, and click Add Release. You will then need to create a new
2191 release for your package, using the format of $VERSION ($CODE_STATUS), e.g.
2194 Now just follow the prompts. Be sure to add any appropriate Release notes. You
2195 should see your freshly uploaded packages in "Step 2. Add Files To This
2196 Release". Check the appropriate box(es). Remember at each step to hit the
2197 "Refresh/Submit" buttons! You should now see your file(s) listed in Step 3.
2198 Fill out the forms with the appropriate information for your platform, being
2199 sure to hit "Update" for each file. If anyone is monitoring your platform,
2200 check the "email" box at the very bottom to notify them of the new package.
2203 If you have made errors, or need to make changes, you can go through
2204 essentially the same steps, but select Edit Release, instead of Add Release.
2206 -------------------------------------------------------------------------------
2208 6.5. After the Release
2210 When all (or: most of the) packages have been uploaded and made available, send
2211 an email to the announce mailing list, Subject: "Version X.Y.Z available for
2212 download". Be sure to include the download location, the release notes and the
2213 Changelog. Also, post an updated News item on the project page Sourceforge, and
2214 update the Home page and docs linked from the Home page (see below). Other news
2215 sites and release oriented sites, such as Freshmeat, should also be notified.
2217 -------------------------------------------------------------------------------
2219 7. Update the Webserver
2221 The webserver should be updated at least with each stable release. When
2222 updating, please follow these steps to make sure that no broken links,
2223 inconsistent contents or permission problems will occur (as it has many times
2226 If you have changed anything in the stable-branch documentation source SGML
2229 make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
2232 That will generate doc/webserver/user-manual, doc/webserver/developer-manual,
2233 doc/webserver/faq, doc/pdf/*.pdf and doc/webserver/index.html automatically.
2235 If you changed the manual page sources, generate doc/webserver/man-page/
2236 privoxy-man-page.html by running "make man". (This is a separate target due to
2237 dependencies on some obscure perl scripts [now in CVS, but not well tested].
2238 See comments in GNUmakefile.)
2240 If you want to add new files to the webserver, create them locally in the doc/
2241 webserver/* directory (or create new directories under doc/webserver).
2243 Next, commit any changes from the above steps to CVS. All set? If these are
2244 docs in the stable branch, then do:
2249 This will do the upload to the webserver (www.privoxy.org) and ensure all files
2250 and directories there are group writable.
2252 Please do NOT use any other means of transferring files to the webserver to
2253 avoid permission problems. Also, please do not upload docs from development
2254 branches or versions. The publicly posted docs should be in sync with the last
2257 -------------------------------------------------------------------------------
2259 8. Contacting the developers, Bug Reporting and Feature Requests
2261 We value your feedback. In fact, we rely on it to improve Privoxy and its
2262 configuration. However, please note the following hints, so we can provide you
2263 with the best support:
2265 -------------------------------------------------------------------------------
2269 For casual users, our support forum at SourceForge is probably best suited:
2270 http://sourceforge.net/tracker/?group_id=11118&atid=211118
2272 All users are of course welcome to discuss their issues on the users mailing
2273 list, where the developers also hang around.
2275 Note that the Privoxy mailing lists are moderated. Posts from unsubscribed
2276 addresses have to be accepted manually by a moderator. This may cause a delay
2277 of several days and if you use a subject that doesn't clearly mention Privoxy
2278 or one of its features, your message may be accidentally discarded as spam.
2280 If you aren't subscribed, you should therefore spend a few seconds to come up
2281 with a proper subject. Additionally you should make it clear that you want to
2282 get CC'd. Otherwise some responses will be directed to the mailing list only,
2283 and you won't see them.
2285 -------------------------------------------------------------------------------
2287 8.2. Reporting Problems
2289 "Problems" for our purposes, come in two forms:
2291 * Configuration issues, such as ads that slip through, or sites that don't
2292 function properly due to one Privoxy "action" or another being turned "on".
2294 * "Bugs" in the programming code that makes up Privoxy, such as that might
2297 -------------------------------------------------------------------------------
2299 8.2.1. Reporting Ads or Other Configuration Problems
2301 Please send feedback on ads that slipped through, innocent images that were
2302 blocked, sites that don't work properly, and other configuration related
2303 problem of default.action file, to http://sourceforge.net/tracker/?group_id=
2304 11118&atid=460288, the Actions File Tracker.
2306 New, improved default.action files may occasionally be made available based on
2307 your feedback. These will be announced on the ijbswa-announce list and
2308 available from our the files section of our project page.
2310 -------------------------------------------------------------------------------
2312 8.2.2. Reporting Bugs
2314 Please report all bugs through our bug tracker: http://sourceforge.net/tracker
2315 /?group_id=11118&atid=111118.
2317 Before doing so, please make sure that the bug has not already been submitted
2318 and observe the additional hints at the top of the submit form. If already
2319 submitted, please feel free to add any info to the original report that might
2320 help to solve the issue.
2322 Please try to verify that it is a Privoxy bug, and not a browser or site bug or
2323 documented behaviour that just happens to be different than what you expected.
2324 If unsure, try toggling off Privoxy, and see if the problem persists.
2326 If you are using your own custom configuration, please try the stock configs to
2327 see if the problem is configuration related. If you're having problems with a
2328 feature that is disabled by default, please ask around on the mailing list if
2329 others can reproduce the problem.
2331 If you aren't using the latest Privoxy version, the bug may have been found and
2332 fixed in the meantime. We would appreciate if you could take the time to
2333 upgrade to the latest version (or even the latest CVS snapshot) and verify that
2334 your bug still exists.
2336 Please be sure to provide the following information:
2338 * The exact Privoxy version you are using (if you got the source from CVS,
2339 please also provide the source code revisions as shown in http://
2340 config.privoxy.org/show-version).
2342 * The operating system and versions you run Privoxy on, (e.g. Windows XP
2343 SP2), if you are using a Unix flavor, sending the output of "uname -a"
2344 should do, in case of GNU/Linux, please also name the distribution.
2346 * The name, platform, and version of the browser you were using (e.g.
2347 Internet Explorer v5.5 for Mac).
2349 * The URL where the problem occurred, or some way for us to duplicate the
2350 problem (e.g. http://somesite.example.com/?somethingelse=123).
2352 * Whether your version of Privoxy is one supplied by the Privoxy developers
2353 via SourceForge, or if you got your copy somewhere else.
2355 * Whether you are using Privoxy in tandem with another proxy such as Tor. If
2356 so, please temporary disable the other proxy to see if the symptoms change.
2358 * Whether you are using a personal firewall product. If so, does Privoxy work
2361 * Any other pertinent information to help identify the problem such as config
2362 or log file excerpts (yes, you should have log file entries for each action
2365 You don't have to tell us your actual name when filing a problem report, but
2366 please use a nickname so we can differentiate between your messages and the
2367 ones entered by other "anonymous" users that may respond to your request if
2368 they have the same problem or already found a solution.
2370 Please also check the status of your request a few days after submitting it, as
2371 we may request additional information. If you use a SF id, you should
2372 automatically get a mail when someone responds to your request.
2374 The appendix of the Privoxy User Manual also has helpful information on
2375 understanding actions, and action debugging.
2377 -------------------------------------------------------------------------------
2379 8.3. Request New Features
2381 You are welcome to submit ideas on new features or other proposals for
2382 improvement through our feature request tracker at http://sourceforge.net/
2383 tracker/?atid=361118&group_id=11118.
2385 -------------------------------------------------------------------------------
2389 For any other issues, feel free to use the mailing lists. Technically
2390 interested users and people who wish to contribute to the project are also
2391 welcome on the developers list! You can find an overview of all Privoxy-related
2392 mailing lists, including list archives, at: http://sourceforge.net/mail/?
2395 -------------------------------------------------------------------------------
2397 9. Privoxy Copyright, License and History
2399 Copyright 2001-2008 by Privoxy Developers <
2400 ijbswa-developers@lists.sourceforge.net>
2402 Some source code is based on code Copyright 1997 by Anonymous Coders and
2403 Junkbusters, Inc. and licensed under the GNU General Public License.
2405 -------------------------------------------------------------------------------
2409 Privoxy is free software; you can redistribute it and/or modify it under the
2410 terms of the GNU General Public License, version 2, as published by the Free
2411 Software Foundation.
2413 This program is distributed in the hope that it will be useful, but WITHOUT ANY
2414 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
2415 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
2416 is available from the Free Software Foundation, Inc, 51 Franklin Street, Fifth
2417 Floor, Boston, MA 02110-1301, USA
2419 You should have received a copy of the GNU General Public License along with
2420 this program; if not, write to the
2423 Foundation, Inc. 51 Franklin Street, Fifth Floor
2424 Boston, MA 02110-1301
2427 -------------------------------------------------------------------------------
2431 A long time ago, there was the Internet Junkbuster, by Anonymous Coders and
2432 Junkbusters Corporation. This saved many users a lot of pain in the early days
2433 of web advertising and user tracking.
2435 But the web, its protocols and standards, and with it, the techniques for
2436 forcing ads on users, give up autonomy over their browsing, and for tracking
2437 them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version
2438 2.0.2, published in 1998, was (and is) the last official release available from
2439 Junkbusters Corporation. Fortunately, it had been released under the GNU GPL,
2440 which allowed further development by others.
2442 So Stefan Waldherr started maintaining an improved version of the software, to
2443 which eventually a number of people contributed patches. It could already
2444 replace banners with a transparent image, and had a first version of pop-up
2445 killing, but it was still very closely based on the original, with all its
2446 limitations, such as the lack of HTTP/1.1 support, flexible per-site
2447 configuration, or content modification. The last release from this effort was
2448 version 2.0.2-10, published in 2000.
2450 Then, some developers picked up the thread, and started turning the software
2451 inside out, upside down, and then reassembled it, adding many new features
2454 The result of this is Privoxy, whose first stable version, 3.0, was released
2457 -------------------------------------------------------------------------------
2461 Other references and sites of interest to Privoxy users:
2463 http://www.privoxy.org/, the Privoxy Home page.
2465 http://www.privoxy.org/faq/, the Privoxy FAQ.
2467 http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on
2470 http://config.privoxy.org/, the web-based user interface. Privoxy must be
2471 running for this to work. Shortcut: http://p.p/
2473 http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit "misses"
2474 and other configuration related suggestions to the developers.
2476 http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are
2477 used to track web users.
2479 http://www.junkbusters.com/ijb.html, the original Internet Junkbuster.
2481 http://privacy.net/, a useful site to check what information about you is
2482 leaked while you browse the web.
2484 http://www.squid-cache.org/, a popular caching proxy, which is often used
2485 together with Privoxy.
2487 http://www.pps.jussieu.fr/~jch/software/polipo/, Polipo is a caching proxy with
2488 advanced features like pipelining, multiplexing and caching of partial
2489 instances. In many setups it can be used as Squid replacement.
2491 http://tor.eff.org/, Tor can help anonymize web browsing, web publishing,
2492 instant messaging, IRC, SSH, and other applications.
2494 http://www.privoxy.org/developer-manual/, the Privoxy developer manual.