1 Privoxy Developer Manual
3 Copyright © 2001-2006 by Privoxy Developers
5 $Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 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
12 Please note that this document is constantly evolving. This copy represents the
13 state at the release of version 3.0.6. You can find the latest version of the
14 this manual at http://www.privoxy.org/developer-manual/. Please see the Contact
15 section on how to contact the developers.
17 -------------------------------------------------------------------------------
22 1.1. Quickstart to Privoxy Development
28 2.3. CVS Commit Guidelines
30 3. Documentation Guidelines
32 3.1. Quickstart to Docbook and SGML
33 3.2. Privoxy Documentation Style
34 3.3. Privoxy Custom Entities
41 4.2.1. Comment, Comment, Comment
42 4.2.2. Use blocks for comments
43 4.2.3. Keep Comments on their own line
44 4.2.4. Comment each logical step
45 4.2.5. Comment All Functions Thoroughly
46 4.2.6. Comment at the end of braces if the content is more than one
49 4.3. Naming Conventions
53 4.3.3. Header file prototypes
54 4.3.4. Enumerations, and #defines
59 4.4.1. Put braces on a line by themselves.
60 4.4.2. ALL control statements should have a block
61 4.4.3. Do not belabor/blow-up boolean expressions
62 4.4.4. Use white space freely because it is free
63 4.4.5. Don't use white space around structure operators
64 4.4.6. Make the last brace of a function stand out
65 4.4.7. Use 3 character indentions
69 4.5.1. Initialize all variables
73 4.6.1. Name functions that return a boolean as a question.
74 4.6.2. Always specify a return type for a function.
75 4.6.3. Minimize function calls when iterating by using variables
76 4.6.4. Pass and Return by Const Reference
77 4.6.5. Pass and Return by Value
78 4.6.6. Names of include files
79 4.6.7. Provide multiple inclusion protection
80 4.6.8. Use `extern "C"` when appropriate
81 4.6.9. Where Possible, Use Forward Struct Declaration Instead of
84 4.7. General Coding Practices
86 4.7.1. Turn on warnings
87 4.7.2. Provide a default case for all switch statements
88 4.7.3. Try to avoid falling through cases in a switch statement.
89 4.7.4. Use 'long' or 'short' Instead of 'int'
90 4.7.5. Don't mix size_t and other types
91 4.7.6. Declare each variable and struct on its own line.
92 4.7.7. Use malloc/zalloc sparingly
93 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
95 4.7.9. Add loaders to the `file_list' structure and in order
96 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
98 4.8. Addendum: Template for files and function comment blocks:
100 5. Testing Guidelines
102 5.1. Testplan for releases
105 6. Releasing a New Version
108 6.2. Before the Release: Freeze
109 6.3. Building and Releasing the Packages
111 6.3.1. Note on Privoxy Packaging
112 6.3.2. Source Tarball
113 6.3.3. SuSE, Conectiva or Red Hat RPM
124 6.4. Uploading and Releasing Your Package
125 6.5. After the Release
127 7. Update the Webserver
128 8. Contacting the developers, Bug Reporting and Feature Requests
131 8.2. Reporting Problems
133 8.2.1. Reporting Ads or Other Configuration Problems
134 8.2.2. Reporting Bugs
136 8.3. Request New Features
139 9. Privoxy Copyright, License and History
148 Privoxy, as an heir to Junkbuster, is an Open Source project and licensed under
149 the GPL. As such, Privoxy development is potentially open to anyone who has the
150 time, knowledge, and desire to contribute in any capacity. Our goals are simply
151 to continue the mission, to improve Privoxy, and to make it available to as
152 wide an audience as possible.
154 One does not have to be a programmer to contribute. Packaging, testing, and
155 porting, are all important jobs as well.
157 -------------------------------------------------------------------------------
159 1.1. Quickstart to Privoxy Development
161 The first step is to join the developer's mailing list. You can submit your
162 ideas, or even better patches. Patches are best submitted to the Sourceforge
163 tracker set up for this purpose, but can be sent to the list for review too.
165 You will also need to have a cvs package installed, which will entail having
166 ssh installed as well (which seems to be a requirement of SourceForge), in
167 order to access the cvs repository. Having the GNU build tools is also going to
168 be important (particularly, autoconf and gmake).
170 For the time being (read, this section is under construction), you can also
171 refer to the extensive comments in the source code. In fact, reading the code
172 is recommended in any case.
174 -------------------------------------------------------------------------------
176 2. The CVS Repository
178 If you become part of the active development team, you will eventually need
179 write access to our holy grail, the CVS repository. One of the team members
180 will need to set this up for you. Please read this chapter completely before
183 -------------------------------------------------------------------------------
187 The project's CVS repository is hosted on SourceForge. Please refer to the
188 chapters 6 and 7 in SF's site documentation for the technical access details
189 for your operating system. For historical reasons, the CVS server is called
190 ijbswa.cvs.sourceforge.net, the repository is called ijbswa, and the source
191 tree module is called current.
193 -------------------------------------------------------------------------------
197 Within the CVS repository, there are modules and branches. As mentioned, the
198 sources are in the current "module". Other modules are present for platform
199 specific issues. There is a webview of the CVS hierarchy at http://
200 ijbswa.cvs.sourceforge.net/ijbswa/, which might help with visualizing how these
203 Branches are used to fork a sub-development path from the main trunk. Within
204 the current module where the sources are, there is always at least one "branch"
205 from the main trunk devoted to a stable release series. The main trunk is where
206 active development takes place for the next stable series (e.g. 3.2.x). So just
207 prior to each stable series (e.g. 3.0.x), a branch is created just for stable
208 series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable
209 release of any stable branch has taken place, this branch is only used for
210 bugfixes, which have had prior testing before being committed to CVS. (See
211 Version Numbers below for details on versioning.)
213 At one time there were two distinct branches: stable and unstable. The more
214 drastic changes were to be in the unstable branch. These branches have now been
215 merged to minimize time and effort of maintaining two branches.
217 -------------------------------------------------------------------------------
219 2.3. CVS Commit Guidelines
221 The source tree is the heart of every software project. Every effort must be
222 made to ensure that it is readable, compilable and consistent at all times.
223 There are differing guidelines for the stable branch and the main development
224 trunk, and we ask anyone with CVS access to strictly adhere to the following
227 Basic Guidelines, for all branches:
229 * Please don't commit even a small change without testing it thoroughly
230 first. When we're close to a public release, ask a fellow developer to
233 * Your commit message should give a concise overview of what you changed (no
234 big details) and why you changed it Just check previous messages for good
237 * Don't use the same message on multiple files, unless it equally applies to
240 * If your changes span multiple files, and the code won't recompile unless
241 all changes are committed (e.g. when changing the signature of a function),
242 then commit all files one after another, without long delays in between. If
243 necessary, prepare the commit messages in advance.
245 * Before changing things on CVS, make sure that your changes are in line with
246 the team's general consensus on what should be done.
248 * Note that near a major public release, we get more cautious. There is
249 always the possibility to submit a patch to the patch tracker instead.
251 -------------------------------------------------------------------------------
253 3. Documentation Guidelines
255 All formal documents are maintained in Docbook SGML and located in the doc/
256 source/* directory. You will need Docbook, the Docbook DTD's and the Docbook
257 modular stylesheets (or comparable alternatives), and either jade or openjade
258 (recommended) installed in order to build docs from source. Currently there is
259 user-manual, FAQ, and, of course this, the developer-manual in this format. The
260 README, AUTHORS, INSTALL, privoxy.1 (man page), and config files are also now
261 maintained as Docbook SGML. These files, when built, in the top-level source
262 directory are generated files! Also, the Privoxy index.html (and a variation on
263 this file, privoxy-index.html, meant for inclusion with doc packages), are
264 maintained as SGML as well. DO NOT edit these directly. Edit the SGML source,
265 or contact someone involved in the documentation.
267 config requires some special handling. The reason it is maintained this way is
268 so that the extensive comments in the file mirror those in user-manual. But the
269 conversion process requires going from SGML to HTML to text to special
270 formatting required for the embedded comments. Some of this does not survive so
271 well. Especially some of the examples that are longer than 80 characters. The
272 build process for this file outputs to config.new, which should be reviewed for
273 errors and mis-formatting. Once satisfied that it is correct, then it should be
274 hand copied to config.
276 Other, less formal documents (e.g. LICENSE) are maintained as plain text files
277 in the top-level source directory.
279 Packagers are encouraged to include this documentation. For those without the
280 ability to build the docs locally, text versions of each are kept in CVS. HTML
281 versions are also being kept in CVS under doc/webserver/*. And PDF version are
284 Formal documents are built with the Makefile targets of make dok, or
285 alternately make redhat-dok. If you have problems, try both. The build process
286 uses the document SGML sources in doc/source/*/* to update all text files in
287 doc/text/ and to update all HTML documents in doc/webserver/.
289 Documentation writers should please make sure documents build successfully
290 before committing to CVS, if possible.
292 How do you update the webserver (i.e. the pages on privoxy.org)?
294 1. First, build the docs by running make dok (or alternately make redhat-dok).
295 For PDF docs, do make dok-pdf.
297 2. Run make webserver which copies all files from doc/webserver to the
298 sourceforge webserver via scp.
300 Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html)
301 so that those without the ability to build them locally, have access to them if
302 needed. This is especially important just prior to a new release! Please do
303 this after the $VERSION and other release specific data in configure.in has
304 been updated (this is done just prior to a new release).
306 -------------------------------------------------------------------------------
308 3.1. Quickstart to Docbook and SGML
310 If you are not familiar with SGML, it is a markup language similar to HTML.
311 Actually, not a mark up language per se, but a language used to define markup
312 languages. In fact, HTML is an SGML application. Both will use "tags" to format
313 text and other content. SGML tags can be much more varied, and flexible, but do
314 much of the same kinds of things. The tags, or "elements", are definable in
315 SGML. There is no set "standards". Since we are using Docbook, our tags are
316 those that are defined by Docbook. Much of how the finish document is rendered
317 is determined by the "stylesheets". The stylesheets determine how each tag gets
318 translated to HTML, or other formats.
320 Tags in Docbook SGML need to be always "closed". If not, you will likely
321 generate errors. Example: <title>My Title</title>. They are also
322 case-insensitive, but we strongly suggest using all lower case. This keeps
323 compatibility with [Docbook] XML.
325 Our documents use "sections" for the most part. Sections will be processed into
326 HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to
327 also generate the Table of Contents for each doc. Our TOC's are set to a depth
328 of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will
329 not. Each section requires a <title> element, and at least one <para>. There is
330 a limit of five section levels in Docbook, but generally three should be
331 sufficient for our purposes.
333 Some common elements that you likely will use:
335 <para></para>, paragraph delimiter. Most text needs to be within paragraph
336 elements (there are some exceptions).
337 <emphasis></emphasis>, the stylesheets make this italics.
338 <filename></filename>, files and directories.
339 <command></command>, command examples.
340 <literallayout></literallayout>, like <pre>, more or less.
341 <itemizedlist></itemizedlist>, list with bullets.
342 <listitem></listitem>, member of the above.
343 <screen></screen>, screen output, implies <literallayout>.
344 <ulink url="example.com"></ulink>, like HTML <a> tag.
345 <quote></quote>, for, doh, quoting text.
347 Look at any of the existing docs for examples of all these and more.
349 You might also find "Writing Documentation Using DocBook - A Crash Course"
352 -------------------------------------------------------------------------------
354 3.2. Privoxy Documentation Style
356 It will be easier if everyone follows a similar writing style. This just makes
357 it easier to read what someone else has written if it is all done in a similar
362 * All tags should be lower case.
364 * Tags delimiting a block of text (even small blocks) should be on their own
372 Tags marking individual words, or few words, should be in-line:
374 Just to <emphasis>emphasize</emphasis>, some text goes here.
377 * Tags should be nested and step indented for block text like: (except
384 Some text goes here in our list example.
391 This makes it easier to find the text amongst the tags ;-)
393 * Use white space to separate logical divisions within a document, like
394 between sections. Running everything together consistently makes it harder
397 * Do not hesitate to make comments. Comments can either use the <comment>
398 element, or the <!-- --> style comment familiar from HTML. (Note in Docbook
399 v4.x <comment> is replaced by <remark>.)
401 * We have an international audience. Refrain from slang, or English
402 idiosyncrasies (too many to list :). Humor also does not translate well
405 * Try to keep overall line lengths in source files to 80 characters or less
406 for obvious reasons. This is not always possible, with lengthy URLs for
409 * Our documents are available in differing formats. Right now, they are just
410 plain text, HTML, and PDF, but others are always a future possibility. Be
411 careful with URLs (<ulink>), and avoid this mistake:
413 My favorite site is <ulink url="http://example.com">here</ulink>.
415 This will render as "My favorite site is here", which is not real helpful
416 in a text doc. Better like this:
418 My favorite site is <ulink url="http://example.com">example.com</ulink>.
420 * All documents should be spell checked occasionally. aspell can check SGML
421 with the -H option. (ispell I think too.)
423 -------------------------------------------------------------------------------
425 3.3. Privoxy Custom Entities
427 Privoxy documentation is using a number of customized "entities" to facilitate
428 documentation maintenance.
430 We are using a set of "boilerplate" files with generic text, that is used by
431 multiple docs. This way we can write something once, and use it repeatedly
432 without having to re-write the same content over and over again. If editing
433 such a file, keep in mind that it should be generic. That is the purpose; so it
434 can be used in varying contexts without additional modifications.
436 We are also using what Docbook calls "internal entities". These are like
437 variables in programming. Well, sort of. For instance, we have the p-version
438 entity that contains the current Privoxy version string. You are strongly
439 encouraged to use these where possible. Some of these obviously require
440 re-setting with each release (done by the Makefile). A sampling of custom
441 entities are listed below. See any of the main docs for examples.
443 * Re- "boilerplate" text entities are defined like:
445 <!entity supported SYSTEM "supported.sgml">
447 In this example, the contents of the file, supported.sgml is available for
448 inclusion anywhere in the doc. To make this happen, just reference the now
449 defined entity: &supported; (starts with an ampersand and ends with a
450 semi-colon), and the contents will be dumped into the finished doc at that
453 * Commonly used "internal entities":
455 p-version: the Privoxy version string, e.g. "3.0.6".
456 p-status: the project status, either "alpha", "beta", or "stable".
457 p-not-stable: use to conditionally include text in "not stable" releases
459 p-stable: just the opposite.
460 p-text: this doc is only generated as text.
462 There are others in various places that are defined for a specific purpose.
465 -------------------------------------------------------------------------------
471 This set of standards is designed to make our lives easier. It is developed
472 with the simple goal of helping us keep the "new and improved Privoxy"
473 consistent and reliable. Thus making maintenance easier and increasing chances
474 of success of the project.
476 And that of course comes back to us as individuals. If we can increase our
477 development and product efficiencies then we can solve more of the request for
478 changes/improvements and in general feel good about ourselves. ;->
480 -------------------------------------------------------------------------------
484 4.2.1. Comment, Comment, Comment
488 Comment as much as possible without commenting the obvious. For example do not
489 comment "aVariable is equal to bVariable". Instead explain why aVariable should
490 be equal to the bVariable. Just because a person can read code does not mean
491 they will understand why or what is being done. A reader may spend a lot more
492 time figuring out what is going on when a simple comment or explanation would
493 have prevented the extra research. Please help your brother IJB'ers out!
495 The comments will also help justify the intent of the code. If the comment
496 describes something different than what the code is doing then maybe a
497 programming error is occurring.
501 /* if page size greater than 1k ... */
502 if ( PageLength() > 1024 )
504 ... "block" the page up ...
507 /* if page size is small, send it in blocks */
508 if ( PageLength() > 1024 )
510 ... "block" the page up ...
513 This demonstrates 2 cases of "what not to do". The first is a
514 "syntax comment". The second is a comment that does not fit what
515 is actually being done.
517 -------------------------------------------------------------------------------
519 4.2.2. Use blocks for comments
523 Comments can help or they can clutter. They help when they are differentiated
524 from the code they describe. One line comments do not offer effective
525 separation between the comment and the code. Block identifiers do, by
526 surrounding the code with a clear, definable pattern.
530 /*********************************************************************
531 * This will stand out clearly in your code!
532 *********************************************************************/
533 if ( thisVariable == thatVariable )
535 DoSomethingVeryImportant();
539 /* unfortunately, this may not */
540 if ( thisVariable == thatVariable )
542 DoSomethingVeryImportant();
546 if ( thisVariable == thatVariable ) /* this may not either */
548 DoSomethingVeryImportant();
553 If you are trying to add a small logic comment and do not wish to "disrupt" the
554 flow of the code, feel free to use a 1 line comment which is NOT on the same
557 -------------------------------------------------------------------------------
559 4.2.3. Keep Comments on their own line
563 It goes back to the question of readability. If the comment is on the same line
564 as the code it will be harder to read than the comment that is on its own line.
566 There are three exceptions to this rule, which should be violated freely and
567 often: during the definition of variables, at the end of closing braces, when
568 used to comment parameters.
572 /*********************************************************************
573 * This will stand out clearly in your code,
574 * But the second example won't.
575 *********************************************************************/
576 if ( thisVariable == thatVariable )
578 DoSomethingVeryImportant();
581 if ( thisVariable == thatVariable ) /*can you see me?*/
583 DoSomethingVeryImportant(); /*not easily*/
587 /*********************************************************************
588 * But, the encouraged exceptions:
589 *********************************************************************/
590 int urls_read = 0; /* # of urls read + rejected */
591 int urls_rejected = 0; /* # of urls rejected */
595 DoSomethingVeryImportant();
599 short DoSomethingVeryImportant(
600 short firstparam, /* represents something */
601 short nextparam /* represents something else */ )
605 } /* -END- DoSomethingVeryImportant */
607 -------------------------------------------------------------------------------
609 4.2.4. Comment each logical step
613 Logical steps should be commented to help others follow the intent of the
614 written code and comments will make the code more readable.
616 If you have 25 lines of code without a comment, you should probably go back
617 into it to see where you forgot to put one.
619 Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
620 these are usually major logic containers.
622 -------------------------------------------------------------------------------
624 4.2.5. Comment All Functions Thoroughly
628 A reader of the code should be able to look at the comments just prior to the
629 beginning of a function and discern the reason for its existence and the
630 consequences of using it. The reader should not have to read through the code
631 to determine if a given function is safe for a desired use. The proper
632 information thoroughly presented at the introduction of a function not only
633 saves time for subsequent maintenance or debugging, it more importantly aids in
634 code reuse by allowing a user to determine the safety and applicability of any
635 function for the problem at hand. As a result of such benefits, all functions
636 should contain the information presented in the addendum section of this
639 -------------------------------------------------------------------------------
641 4.2.6. Comment at the end of braces if the content is more than one screen
646 Each closing brace should be followed on the same line by a comment that
647 describes the origination of the brace if the original brace is off of the
648 screen, or otherwise far away from the closing brace. This will simplify the
649 debugging, maintenance, and readability of the code.
651 As a suggestion , use the following flags to make the comment and its brace
654 use following a closing brace: } /* -END- if() or while () or etc... */
660 DoSomethingVeryImportant();
661 ...some long list of commands...
662 } /* -END- if x is 1 */
668 DoSomethingVeryImportant();
669 ...some long list of commands...
670 } /* -END- if ( 1 == X ) */
672 -------------------------------------------------------------------------------
674 4.3. Naming Conventions
676 4.3.1. Variable Names
680 Use all lowercase, and separate words via an underscore ('_'). Do not start an
681 identifier with an underscore. (ANSI C reserves these for use by the compiler
682 and system headers.) Do not use identifiers which are reserved in ANSI C++.
683 (E.g. template, class, true, false, ...). This is in case we ever decide to
688 int ms_iis5_hack = 0;
692 int msiis5hack = 0; int msIis5Hack = 0;
694 -------------------------------------------------------------------------------
696 4.3.2. Function Names
700 Use all lowercase, and separate words via an underscore ('_'). Do not start an
701 identifier with an underscore. (ANSI C reserves these for use by the compiler
702 and system headers.) Do not use identifiers which are reserved in ANSI C++.
703 (E.g. template, class, true, false, ...). This is in case we ever decide to
708 int load_some_file( struct client_state *csp )
712 int loadsomefile( struct client_state *csp )
713 int loadSomeFile( struct client_state *csp )
715 -------------------------------------------------------------------------------
717 4.3.3. Header file prototypes
721 Use a descriptive parameter name in the function prototype in header files. Use
722 the same parameter name in the header file that you use in the c file.
726 (.h) extern int load_aclfile( struct client_state *csp );
727 (.c) int load_aclfile( struct client_state *csp )
731 (.h) extern int load_aclfile( struct client_state * ); or
732 (.h) extern int load_aclfile();
733 (.c) int load_aclfile( struct client_state *csp )
735 -------------------------------------------------------------------------------
737 4.3.4. Enumerations, and #defines
741 Use all capital letters, with underscores between words. Do not start an
742 identifier with an underscore. (ANSI C reserves these for use by the compiler
747 (enumeration) : enum Boolean { FALSE, TRUE };
748 (#define) : #define DEFAULT_SIZE 100;
750 Note: We have a standard naming scheme for #defines that toggle a feature in
751 the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word)
756 #define FEATURE_FORCE 1
759 #define FORCE_PREFIX blah
760 #endif /* def FEATURE_FORCE */
762 -------------------------------------------------------------------------------
768 Spell common words out entirely (do not remove vowels).
770 Use only widely-known domain acronyms and abbreviations. Capitalize all letters
773 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
774 terminate a name with an underscore.
778 #define USE_IMAGE_LIST 1
782 #define USE_IMG_LST 1 or
783 #define _USE_IMAGE_LIST 1 or
784 #define USE_IMAGE_LIST_ 1 or
785 #define use_image_list 1 or
786 #define UseImageList 1
788 -------------------------------------------------------------------------------
792 4.4.1. Put braces on a line by themselves.
796 The brace needs to be on a line all by itself, not at the end of the statement.
797 Curly braces should line up with the construct that they're associated with.
798 This practice makes it easier to identify the opening and closing braces for a
810 if ( this == that ) { ... }
814 if ( this == that ) { ... }
816 Note: In the special case that the if-statement is inside a loop, and it is
817 trivial, i.e. it tests for a condition that is obvious from the purpose of the
818 block, one-liners as above may optically preserve the loop structure and make
821 Status: developer-discretion.
825 while ( more lines are read )
827 /* Please document what is/is not a comment line here */
828 if ( it's a comment ) continue;
830 do_something( line );
833 -------------------------------------------------------------------------------
835 4.4.2. ALL control statements should have a block
839 Using braces to make a block will make your code more readable and less prone
840 to error. All control statements should have a block defined.
852 if ( this == that ) DoSomething(); DoSomethingElse();
856 if ( this == that ) DoSomething();
858 Note: The first example in "Instead of" will execute in a manner other than
859 that which the developer desired (per indentation). Using code braces would
860 have prevented this "feature". The "explanation" and "exception" from the point
863 -------------------------------------------------------------------------------
865 4.4.3. Do not belabor/blow-up boolean expressions
869 structure->flag = ( condition );
873 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
875 Note: The former is readable and concise. The later is wordy and inefficient.
876 Please assume that any developer new to the project has at least a "good"
877 knowledge of C/C++. (Hope I do not offend by that last comment ... 8-)
879 -------------------------------------------------------------------------------
881 4.4.4. Use white space freely because it is free
885 Make it readable. The notable exception to using white space freely is listed
886 in the next guideline.
892 int anotherValue = 0;
893 int thisVariable = 0;
895 if ( thisVariable == thatVariable )
897 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
899 -------------------------------------------------------------------------------
901 4.4.5. Don't use white space around structure operators
905 - structure pointer operator ( "->" ) - member operator ( "." ) - functions and
908 It is a general coding practice to put pointers, references, and function
909 parentheses next to names. With spaces, the connection between the object and
910 variable/function name is not as clear.
918 Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
920 -------------------------------------------------------------------------------
922 4.4.6. Make the last brace of a function stand out
931 } /* -END- function1 */
936 } /* -END- function2 */
940 int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { }
942 Note: Use 1 blank line before the closing brace and 2 lines afterward. This
943 makes the end of function standout to the most casual viewer. Although function
944 comments help separate functions, this is still a good coding practice. In
945 fact, I follow these rules when using blocks in "for", "while", "do" loops, and
946 long if {} statements too. After all whitespace is free!
948 Status: developer-discretion on the number of blank lines. Enforced is the end
949 of function comments.
951 -------------------------------------------------------------------------------
953 4.4.7. Use 3 character indentions
957 If some use 8 character TABs and some use 3 character TABs, the code can look *
958 very* ragged. So use 3 character indentions only. If you like to use TABs, pass
959 your code through a filter such as "expand -t3" before checking in your code.
963 static const char * const url_code_map[256] =
973 return( ALWAYS_TRUE );
977 return( HOW_DID_YOU_GET_HERE );
980 return( NEVER_GETS_HERE );
984 -------------------------------------------------------------------------------
988 4.5.1. Initialize all variables
992 Do not assume that the variables declared will not be used until after they
993 have been assigned a value somewhere else in the code. Remove the chance of
994 accidentally using an unassigned variable.
1002 Note: It is much easier to debug a SIGSEGV if the message says you are trying
1003 to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a
1004 SIGSEV vs. arrayPtr[0].
1006 Status: developer-discretion if and only if the variable is assigned a value
1007 "shortly after" declaration.
1009 -------------------------------------------------------------------------------
1013 4.6.1. Name functions that return a boolean as a question.
1017 Value should be phrased as a question that would logically be answered as a
1018 true or false statement
1022 ShouldWeBlockThis();
1026 -------------------------------------------------------------------------------
1028 4.6.2. Always specify a return type for a function.
1032 The default return for a function is an int. To avoid ambiguity, create a
1033 return for a function when the return has a purpose, and create a void return
1034 type if the function does not need to return anything.
1036 -------------------------------------------------------------------------------
1038 4.6.3. Minimize function calls when iterating by using variables
1042 It is easy to write the following code, and a clear argument can be made that
1043 the code is easy to understand:
1047 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1052 Note: Unfortunately, this makes a function call for each and every iteration.
1053 This increases the overhead in the program, because the compiler has to look up
1054 the function each time, call it, and return a value. Depending on what occurs
1055 in the blockListLength() call, it might even be creating and destroying
1056 structures with each iteration, even though in each case it is comparing "cnt"
1057 to the same value, over and over. Remember too - even a call to blockListLength
1058 () is a function call, with the same overhead.
1060 Instead of using a function call during the iterations, assign the value to a
1061 variable, and evaluate using the variable.
1065 size_t len = blockListLength();
1067 for ( size_t cnt = 0; cnt < len; cnt ++ )
1072 Exceptions: if the value of blockListLength() *may* change or could *
1073 potentially* change, then you must code the function call in the for/while
1076 -------------------------------------------------------------------------------
1078 4.6.4. Pass and Return by Const Reference
1082 This allows a developer to define a const pointer and call your function. If
1083 your function does not have the const keyword, we may not be able to use your
1084 function. Consider strcmp, if it were defined as: extern int strcmp( char *s1,
1087 I could then not use it to compare argv's in main: int main( int argc, const
1088 char *argv[] ) { strcmp( argv[0], "privoxy" ); }
1090 Both these pointers are *const*! If the c runtime library maintainers do it, we
1093 -------------------------------------------------------------------------------
1095 4.6.5. Pass and Return by Value
1099 Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes
1100 or less). Aka, a function declaration like: int load_aclfile( struct
1103 would not work. So, to be consistent, we should declare all prototypes with
1104 "pass by value": int load_aclfile( struct client_state *csp )
1106 -------------------------------------------------------------------------------
1108 4.6.6. Names of include files
1112 Your include statements should contain the file name without a path. The path
1113 should be listed in the Makefile, using -I as processor directive to search the
1114 indicated paths. An exception to this would be for some proprietary software
1115 that utilizes a partial path to distinguish their header files from system or
1120 #include <iostream.h> /* This is not a local include */
1121 #include "config.h" /* This IS a local include */
1125 /* This is not a local include, but requires a path element. */
1126 #include <sys/fileName.h>
1128 Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
1129 This duplicates the #include "file.h" behavior.
1131 -------------------------------------------------------------------------------
1133 4.6.7. Provide multiple inclusion protection
1137 Prevents compiler and linker errors resulting from redefinition of items.
1139 Wrap each header file with the following syntax to prevent multiple inclusions
1140 of the file. Of course, replace PROJECT_H with your file name, with "." Changed
1141 to "_", and make it uppercase.
1145 #ifndef PROJECT_H_INCLUDED
1146 #define PROJECT_H_INCLUDED
1148 #endif /* ndef PROJECT_H_INCLUDED */
1150 -------------------------------------------------------------------------------
1152 4.6.8. Use `extern "C"` when appropriate
1156 If our headers are included from C++, they must declare our functions as
1157 `extern "C"`. This has no cost in C, but increases the potential re-usability
1165 #endif /* def __cplusplus */
1167 ... function definitions here ...
1171 #endif /* def __cplusplus */
1173 -------------------------------------------------------------------------------
1175 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
1179 Useful in headers that include pointers to other struct's. Modifications to
1180 excess header files may cause needless compiles.
1184 /*********************************************************************
1185 * We're avoiding an include statement here!
1186 *********************************************************************/
1188 extern file_list *xyz;
1190 Note: If you declare "file_list xyz;" (without the pointer), then including the
1191 proper header file is necessary. If you only want to prototype a pointer,
1192 however, the header file is unnecessary.
1194 Status: Use with discretion.
1196 -------------------------------------------------------------------------------
1198 4.7. General Coding Practices
1200 4.7.1. Turn on warnings
1204 Compiler warnings are meant to help you find bugs. You should turn on as many
1205 as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as
1208 -------------------------------------------------------------------------------
1210 4.7.2. Provide a default case for all switch statements
1214 What you think is guaranteed is never really guaranteed. The value that you
1215 don't think you need to check is the one that someday will be passed. So, to
1216 protect yourself from the unknown, always have a default step in a switch
1221 switch( hash_string( cmd ) )
1223 case hash_actions_file :
1233 ... anomaly code goes here ...
1234 continue; / break; / exit( 1 ); / etc ...
1236 } /* end switch( hash_string( cmd ) ) */
1238 Note: If you already have a default condition, you are obviously exempt from
1239 this point. Of note, most of the WIN32 code calls `DefWindowProc' after the
1240 switch statement. This API call *should* be included in a default statement.
1242 Another Note: This is not so much a readability issue as a robust programming
1243 issue. The "anomaly code goes here" may be no more than a print to the STDERR
1244 stream (as in load_config). Or it may really be an ABEND condition.
1246 Status: Programmer discretion is advised.
1248 -------------------------------------------------------------------------------
1250 4.7.3. Try to avoid falling through cases in a switch statement.
1254 In general, you will want to have a 'break' statement within each 'case' of a
1255 switch statement. This allows for the code to be more readable and
1256 understandable, and furthermore can prevent unwanted surprises if someone else
1257 later gets creative and moves the code around.
1259 The language allows you to plan the fall through from one case statement to
1260 another simply by omitting the break statement within the case statement. This
1261 feature does have benefits, but should only be used in rare cases. In general,
1262 use a break statement for each case statement.
1264 If you choose to allow fall through, you should comment both the fact of the
1265 fall through and reason why you felt it was necessary.
1267 -------------------------------------------------------------------------------
1269 4.7.4. Use 'long' or 'short' Instead of 'int'
1273 On 32-bit platforms, int usually has the range of long. On 16-bit platforms,
1274 int has the range of short.
1276 Status: open-to-debate. In the case of most FSF projects (including X/
1277 GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I
1278 forget the exact typedefs now). Should we add these to IJB now that we have a
1281 -------------------------------------------------------------------------------
1283 4.7.5. Don't mix size_t and other types
1287 The type of size_t varies across platforms. Do not make assumptions about
1288 whether it is signed or unsigned, or about how long it is. Do not compare a
1289 size_t against another variable of a different type (or even against a
1290 constant) without casting one of the values. Try to avoid using size_t if you
1293 -------------------------------------------------------------------------------
1295 4.7.6. Declare each variable and struct on its own line.
1299 It can be tempting to declare a series of variables all on one line. Don't.
1311 Explanation: - there is more room for comments on the individual variables -
1312 easier to add new variables without messing up the original ones - when
1313 searching on a variable to find its type, there is less clutter to "visually"
1316 Exceptions: when you want to declare a bunch of loop variables or other trivial
1317 variables; feel free to declare them on 1 line. You should, although, provide a
1318 good comment on their functions.
1320 Status: developer-discretion.
1322 -------------------------------------------------------------------------------
1324 4.7.7. Use malloc/zalloc sparingly
1328 Create a local struct (on the stack) if the variable will live and die within
1329 the context of one function call.
1331 Only "malloc" a struct (on the heap) if the variable's life will extend beyond
1332 the context of one function call.
1336 If a function creates a struct and stores a pointer to it in a
1337 list, then it should definitely be allocated via `malloc'.
1339 -------------------------------------------------------------------------------
1341 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1345 If you have to "malloc" an instance, you are responsible for insuring that the
1346 instance is `free'd, even if the deallocation event falls within some other
1347 programmer's code. You are also responsible for ensuring that deletion is
1348 timely (i.e. not too soon, not too late). This is known as "low-coupling" and
1349 is a "good thing (tm)". You may need to offer a free/unload/destructor type
1350 function to accommodate this.
1354 int load_re_filterfile( struct client_state *csp ) { ... }
1355 static void unload_re_filterfile( void *f ) { ... }
1359 The developer cannot be expected to provide `free'ing functions for C run-time
1360 library functions ... such as `strdup'.
1362 Status: developer-discretion. The "main" use of this standard is for allocating
1363 and freeing data structures (complex or nested).
1365 -------------------------------------------------------------------------------
1367 4.7.9. Add loaders to the `file_list' structure and in order
1371 I have ordered all of the "blocker" file code to be in alpha order. It is
1372 easier to add/read new blockers when you expect a certain order.
1374 Note: It may appear that the alpha order is broken in places by POPUP tests
1375 coming before PCRS tests. But since POPUPs can also be referred to as
1376 KILLPOPUPs, it is clear that it should come first.
1378 -------------------------------------------------------------------------------
1380 4.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
1384 If you have enough confidence in new code or confidence in your changes, but
1385 are not *quite* sure of the repercussions, add this:
1387 /* FIXME: this code has a logic error on platform XYZ, * attempting to fix */ #
1388 ifdef PLATFORM ...changed code here... #endif
1392 /* FIXME: I think the original author really meant this... */ ...changed code
1397 /* FIXME: new code that *may* break something else... */ ...new code here...
1399 Note: If you make it clear that this may or may not be a "good thing (tm)", it
1400 will be easier to identify and include in the project (or conversely exclude
1403 -------------------------------------------------------------------------------
1405 4.8. Addendum: Template for files and function comment blocks:
1407 Example for file comments:
1409 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $";
1410 /*********************************************************************
1414 * Purpose : (Fill me in with a good description!)
1416 * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge
1417 * Privoxy team. http://www.privoxy.org/
1419 * Based on the Internet Junkbuster originally written
1420 * by and Copyright (C) 1997 Anonymous Coders and
1421 * Junkbusters Corporation. http://www.junkbusters.com
1423 * This program is free software; you can redistribute it
1424 * and/or modify it under the terms of the GNU General
1425 * Public License as published by the Free Software
1426 * Foundation; either version 2 of the License, or (at
1427 * your option) any later version.
1429 * This program is distributed in the hope that it will
1430 * be useful, but WITHOUT ANY WARRANTY; without even the
1431 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1432 * PARTICULAR PURPOSE. See the GNU General Public
1433 * License for more details.
1435 * The GNU General Public License should be included with
1436 * this file. If not, you can view it at
1437 * http://www.gnu.org/copyleft/gpl.html
1438 * or write to the Free Software Foundation, Inc.,
1439 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1445 *********************************************************************/
1450 ...necessary include files for us to do our work...
1452 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1454 Note: This declares the rcs variables that should be added to the
1455 "show-proxy-args" page. If this is a brand new creation by you, you are free to
1456 change the "Copyright" section to represent the rights you wish to maintain.
1458 Note: The formfeed character that is present right after the comment flower box
1459 is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of
1460 the code (via `forward-page' and `backward-page'). Please include it if you
1463 Example for file header comments:
1467 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $"
1468 /*********************************************************************
1472 * Purpose : (Fill me in with a good description!)
1474 * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge
1475 * Privoxy team. http://www.privoxy.org/
1477 * Based on the Internet Junkbuster originally written
1478 * by and Copyright (C) 1997 Anonymous Coders and
1479 * Junkbusters Corporation. http://www.junkbusters.com
1481 * This program is free software; you can redistribute it
1482 * and/or modify it under the terms of the GNU General
1483 * Public License as published by the Free Software
1484 * Foundation; either version 2 of the License, or (at
1485 * your option) any later version.
1487 * This program is distributed in the hope that it will
1488 * be useful, but WITHOUT ANY WARRANTY; without even the
1489 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1490 * PARTICULAR PURPOSE. See the GNU General Public
1491 * License for more details.
1493 * The GNU General Public License should be included with
1494 * this file. If not, you can view it at
1495 * http://www.gnu.org/copyleft/gpl.html
1496 * or write to the Free Software Foundation, Inc.,
1497 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1503 *********************************************************************/
1506 #include "project.h"
1512 ... function headers here ...
1515 /* Revision control strings from this header and associated .c file */
1516 extern const char FILENAME_rcs[];
1517 extern const char FILENAME_h_rcs[];
1524 #endif /* ndef _FILENAME_H */
1532 Example for function comments:
1534 /*********************************************************************
1536 * Function : FUNCTION_NAME
1538 * Description : (Fill me in with a good description!)
1541 * 1 : param1 = pointer to an important thing
1542 * 2 : x = pointer to something else
1544 * Returns : 0 => Ok, everything else is an error.
1546 *********************************************************************/
1547 int FUNCTION_NAME( void *param1, const char *x )
1554 Note: If we all follow this practice, we should be able to parse our code to
1555 create a "self-documenting" web page.
1557 -------------------------------------------------------------------------------
1559 5. Testing Guidelines
1563 -------------------------------------------------------------------------------
1565 5.1. Testplan for releases
1567 Explain release numbers. major, minor. developer releases. etc.
1569 1. Remove any existing rpm with rpm -e
1571 2. Remove any file that was left over. This includes (but is not limited to)
1579 + /etc/init.d/privoxy
1583 3. Install the rpm. Any error messages?
1585 4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
1586 privoxy stop). Reboot your machine. Does autostart work?
1588 5. Start browsing. Does Privoxy work? Logfile written?
1590 6. Remove the rpm. Any error messages? All files removed?
1592 -------------------------------------------------------------------------------
1596 Please submit test reports only with the test form at sourceforge. Three simple
1599 * Select category: the distribution you test on.
1601 * Select group: the version of Privoxy that we are about to release.
1603 * Fill the Summary and Detailed Description with something intelligent (keep
1604 it short and precise).
1606 Do not mail to the mailing list (we cannot keep track on issues there).
1608 -------------------------------------------------------------------------------
1610 6. Releasing a New Version
1612 When we release versions of Privoxy, our work leaves our cozy secret lab and
1613 has to work in the cold RealWorld[tm]. Once it is released, there is no way to
1614 call it back, so it is very important that great care is taken to ensure that
1615 everything runs fine, and not to introduce problems in the very last minute.
1617 So when releasing a new version, please adhere exactly to the procedure
1618 outlined in this chapter.
1620 The following programs are required to follow this process: ncftpput (ncftp),
1621 scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
1623 -------------------------------------------------------------------------------
1625 6.1. Version numbers
1627 First you need to determine which version number the release will have. Privoxy
1628 version numbers consist of three numbers, separated by dots, like in X.Y.Z
1629 (e.g. 3.0.0), where:
1631 * X, the version major, is rarely ever changed. It is increased by one if
1632 turning a development branch into stable substantially changes the
1633 functionality, user interface or configuration syntax. Majors 1 and 2 were
1634 Junkbuster, and 3 will be the first stable Privoxy release.
1636 * Y, the version minor, represents the branch within the major version. At
1637 any point in time, there are two branches being maintained: The stable
1638 branch, with an even minor, say, 2N, in which no functionality is being
1639 added and only bug-fixes are made, and 2N+1, the development branch, in
1640 which the further development of Privoxy takes place. This enables us to
1641 turn the code upside down and inside out, while at the same time providing
1642 and maintaining a stable version. The minor is reset to zero (and one) when
1643 the major is incremented. When a development branch has matured to the
1644 point where it can be turned into stable, the old stable branch 2N is given
1645 up (i.e. no longer maintained), the former development branch 2N+1 becomes
1646 the new stable branch 2N+2, and a new development branch 2N+3 is opened.
1648 * Z, the point or sub version, represents a release of the software within a
1649 branch. It is therefore incremented immediately before each code freeze. In
1650 development branches, only the even point versions correspond to actual
1651 releases, while the odd ones denote the evolving state of the sources on
1652 CVS in between. It follows that Z is odd on CVS in development branches
1653 most of the time. There, it gets increased to an even number immediately
1654 before a code freeze, and is increased to an odd number again immediately
1655 thereafter. This ensures that builds from CVS snapshots are easily
1656 distinguished from released versions. The point version is reset to zero
1657 when the minor changes.
1659 Stable branches work a little differently, since there should be little to
1660 no development happening in such branches. Remember, only bugfixes, which
1661 presumably should have had some testing before being committed. Stable
1662 branches will then have their version reported as 0.0.0, during that period
1663 between releases when changes are being added. This is to denote that this
1664 code is not for release. Then as the release nears, the version is bumped
1665 according: e.g. 3.0.1 -> 0.0.0 -> 3.0.2.
1667 In summary, the main CVS trunk is the development branch where new features are
1668 being worked on for the next stable series. This should almost always be where
1669 the most activity takes place. There is always at least one stable branch from
1670 the trunk, e.g now it is 3.0, which is only used to release stable versions.
1671 Once the initial *.0 release of the stable branch has been done, then as a
1672 rule, only bugfixes that have had prior testing should be committed to the
1673 stable branch. Once there are enough bugfixes to justify a new release, the
1674 version of this branch is again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2,
1675 etc are all stable releases from within the stable branch. 3.1.x is currently
1676 the main trunk, and where work on 3.2.x is taking place. If any questions,
1677 please post to the devel list before committing to a stable branch!
1679 Developers should remember too that if they commit a bugfix to the stable
1680 branch, this will more than likely require a separate submission to the main
1681 trunk, since these are separate development trees within CVS. If you are
1682 working on both, then this would require at least two separate check outs (i.e
1683 main trunk, and the stable release branch, which is v_3_0_branch at the
1686 -------------------------------------------------------------------------------
1688 6.2. Before the Release: Freeze
1690 The following must be done by one of the developers prior to each new release.
1692 * Make sure that everybody who has worked on the code in the last couple of
1693 days has had a chance to yell "no!" in case they have pending changes/fixes
1694 in their pipelines. Announce the freeze so that nobody will interfere with
1695 last minute changes.
1697 * Increment the version number (point from odd to even in development
1698 branches!) in configure.in. (RPM spec files will need to be incremented as
1701 * If default.action has changed since last release (i.e. software release or
1702 standalone actions file release), bump up its version info to A.B in this
1705 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1707 Then change the version info in doc/webserver/actions/index.php, line:
1708 '$required_actions_file_version = "A.B";'
1710 * All documentation should be rebuild after the version bump. Finished docs
1711 should be then be committed to CVS (for those without the ability to build
1712 these). Some docs may require rather obscure processing tools. config, the
1713 man page (and the html version of the man page), and the PDF docs fall in
1714 this category. REAMDE, the man page, AUTHORS, and config should all also be
1715 committed to CVS for other packagers. The formal docs should be uploaded to
1716 the webserver. See the Section "Updating the webserver" in this manual for
1719 * The User Manual is also used for context sensitive help for the CGI editor.
1720 This is version sensitive, so that the user will get appropriate help for
1721 his/her release. So with each release a fresh version should be uploaded to
1722 the webserver (this is in addition to the main User Manual link from the
1723 main page since we need to keep manuals for various versions available).
1724 The CGI pages will link to something like http://privoxy.org/$(VERSION)/
1725 user-manual/. This will need to be updated for each new release. There is
1726 no Makefile target for this at this time!!! It needs to be done manually.
1728 * All developers should look at the ChangeLog and make sure noteworthy
1729 changes are referenced.
1731 * Commit all files that were changed in the above steps!
1733 * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't
1734 use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1736 * If the release was in a development branch, increase the point version from
1737 even to odd (X.Y.(Z+1)) again in configure.in and commit your change.
1739 * On the webserver, copy the user manual to a new top-level directory called
1740 X.Y.Z. This ensures that help links from the CGI pages, which have the
1741 version as a prefix, will go into the right version of the manual. If this
1742 is a development branch release, also symlink X.Y.(Z-1) to X.Y.Z and X.Y.
1743 (Z+1) to . (i.e. dot).
1745 -------------------------------------------------------------------------------
1747 6.3. Building and Releasing the Packages
1749 Now the individual packages can be built and released. Note that for GPL
1750 reasons the first package to be released is always the source tarball.
1752 For all types of packages, including the source tarball, you must make sure
1753 that you build from clean sources by exporting the right version from CVS into
1754 an empty directory (just press return when asked for a password):
1756 mkdir dist # delete or choose different name if it already exists
1758 cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
1759 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1761 Do NOT change a single bit, including, but not limited to version information
1762 after export from CVS. This is to make sure that all release packages, and with
1763 them, all future bug reports, are based on exactly the same code.
1765 +-----------------------------------------------------------------------------+
1767 |-----------------------------------------------------------------------------|
1768 |Every significant release of Privoxy has included at least one package that |
1769 |either had incorrect versions of files, missing files, or incidental |
1770 |leftovers from a previous build process that gave unknown numbers of users |
1771 |headaches to try to figure out what was wrong. PLEASE, make sure you are |
1772 |using pristene sources, and are following the prescribed process! |
1773 +-----------------------------------------------------------------------------+
1775 Please find additional instructions for the source tarball and the individual
1776 platform dependent binary packages below. And details on the Sourceforge
1777 release process below that.
1779 -------------------------------------------------------------------------------
1781 6.3.1. Note on Privoxy Packaging
1783 Please keep these general guidelines in mind when putting together your
1784 package. These apply to all platforms!
1786 * Privoxy requires write access to: all *.action files, all logfiles, and the
1787 trust file. You will need to determine the best way to do this for your
1790 * Please include up to date documentation. At a bare minimum:
1792 LICENSE (top-level directory)
1794 README (top-level directory)
1796 AUTHORS (top-level directory)
1798 man page (top-level directory, Unix-like platforms only)
1800 The User Manual (doc/webserver/user-manual/)
1802 FAQ (doc/webserver/faq/)
1804 Also suggested: Developer Manual (doc/webserver/developer-manual) and
1805 ChangeLog (top-level directory). FAQ and the manuals are HTML docs. There
1806 are also text versions in doc/text/ which could conceivably also be
1809 The documentation has been designed such that the manuals are linked to
1810 each other from parallel directories, and should be packaged that way.
1811 privoxy-index.html can also be included and can serve as a focal point for
1812 docs and other links of interest (and possibly renamed to index.html). This
1813 should be one level up from the manuals. There is a link also on this page
1814 to an HTMLized version of the man page. To avoid 404 for this, it is in CVS
1815 as doc/webserver/man-page/privoxy-man-page.html, and should be included
1816 along with the manuals. There is also a css stylesheets that can be
1817 included for better presentation: p_doc.css. This should be in the same
1818 directory with privoxy-index.html, (i.e. one level up from the manual
1821 * user.action and user.filter are designed for local preferences. Make sure
1822 these do not get overwritten! config should not be overwritten either. This
1823 has especially important configuration data in it. trust should be left in
1826 * Other configuration files (default.action, default.filter and
1827 standard.action) should be installed as the new defaults, but all
1828 previously installed configuration files should be preserved as backups.
1829 This is just good manners :-) These files are likely to change between
1830 releases and contain important new features and bug fixes.
1832 * Please check platform specific notes in this doc, if you haven't done
1833 "Privoxy" packaging before for other platform specific issues. Conversely,
1834 please add any notes that you know are important for your platform (or
1835 contact one of the doc maintainers to do this if you can't).
1837 * Packagers should do a "clean" install of their package after building it.
1838 So any previous installs should be removed first to ensure the integrity of
1839 the newly built package. Then run the package for a while to make sure
1840 there are no obvious problems, before uploading.
1842 -------------------------------------------------------------------------------
1844 6.3.2. Source Tarball
1846 First, make sure that you have freshly exported the right version into an empty
1847 directory. (See "Building and releasing packages" above). Then run:
1850 autoheader && autoconf && ./configure
1856 To upload the package to Sourceforge, simply issue
1860 Go to the displayed URL and release the file publicly on Sourceforge. For the
1861 change log field, use the relevant section of the ChangeLog file.
1863 -------------------------------------------------------------------------------
1865 6.3.3. SuSE, Conectiva or Red Hat RPM
1867 In following text, replace dist with either "rh" for Red Hat or "suse" for
1870 First, make sure that you have freshly exported the right version into an empty
1871 directory. (See "Building and releasing packages" above).
1873 As the only exception to not changing anything after export from CVS, now
1874 examine the file privoxy-dist.spec and make sure that the version information
1875 and the RPM release number are correct. The RPM release numbers for each
1876 version start at one. Hence it must be reset to one if this is the first RPM
1877 for dist which is built from version X.Y.Z. Check the file list if unsure.
1878 Else, it must be set to the highest already available RPM release number for
1879 that version plus one.
1884 autoheader && autoconf && ./configure
1890 To upload the package to Sourceforge, simply issue
1892 make dist-upload rpm_packagerev
1894 where rpm_packagerev is the RPM release number as determined above. Go to the
1895 displayed URL and release the file publicly on Sourceforge. Use the release
1896 notes and change log from the source tarball package.
1898 -------------------------------------------------------------------------------
1902 First, make sure that you have freshly exported the right version into an empty
1903 directory. (See "Building and releasing packages" above). Then get the OS/2
1906 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
1908 You will need a mix of development tools. The main compilation takes place with
1909 IBM Visual Age C++. Some ancillary work takes place with GNU tools, available
1910 from various sources like hobbes.nmsu.edu. Specificially, you will need
1911 autoheader, autoconf and sh tools. The packaging takes place with WarpIN,
1912 available from various sources, including its home page: xworkplace.
1914 Change directory to the os2setup directory. Edit the os2build.cmd file to set
1915 the final executable filename. For example,
1917 installExeName='privoxyos2_setup_X.Y.Z.exe'
1919 Next, edit the IJB.wis file so the release number matches in the PACKAGEID
1922 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
1924 You're now ready to build. Run:
1928 You will find the WarpIN-installable executable in the ./files directory.
1929 Upload this anonymously to uploads.sourceforge.net/incoming, create a release
1930 for it, and you're done. Use the release notes and Change Log from the source
1933 -------------------------------------------------------------------------------
1937 Login to Sourceforge's compilefarm via ssh:
1939 ssh cf.sourceforge.net
1941 Choose the right operating system (not the Debian one). When logged in, make
1942 sure that you have freshly exported the right version into an empty directory.
1943 (See "Building and releasing packages" above). Then run:
1946 autoheader && autoconf && ./configure
1952 which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
1953 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1954 archive to Sourceforge's ftp server and release the file publicly. Use the
1955 release notes and Change Log from the source tarball package.
1957 -------------------------------------------------------------------------------
1961 You should ensure you have the latest version of Cygwin (from http://
1962 www.cygwin.com/). Run the following commands from within a Cygwin bash shell.
1964 First, make sure that you have freshly exported the right version into an empty
1965 directory. (See "Building and releasing packages" above). Then get the Windows
1968 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
1970 Then you can build the package. This is fully automated, and is controlled by
1971 winsetup/GNUmakefile. All you need to do is:
1976 Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and
1977 upload it to SourceForge. When releasing the package on SourceForge, use the
1978 release notes and Change Log from the source tarball package.
1980 -------------------------------------------------------------------------------
1984 First, make sure that you have freshly exported the right version into an empty
1985 directory. (See "Building and releasing packages" above). Then add a log entry
1986 to debian/changelog, if it is not already there, for example by running:
1988 debchange -v 3.0.6-stable-1 "New upstream version"
1992 dpkg-buildpackage -rfakeroot -us -uc -b
1994 This will create ../privoxy_3.0.6-stable-1_i386.deb which can be uploaded. To
1995 upload the package to Sourceforge, simply issue
1999 -------------------------------------------------------------------------------
2003 First, make sure that you have freshly exported the right version into an empty
2004 directory. (See "Building and releasing packages" above). Then get the Mac OSX
2007 cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
2014 This will run autoheader, autoconf and configure as well as make. Finally, it
2015 will copy over the necessary files to the ./osxsetup/files directory for
2016 further processing by PackageMaker.
2018 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the
2019 package name to match the release, and hit the "Create package" button. If you
2020 specify ./Privoxy.pkg as the output package name, you can then create the
2021 distributable zip file with the command:
2023 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2025 You can then upload privoxyosx_setup_x.y.z.zip anonymously to
2026 uploads.sourceforge.net/incoming, create a release for it, and you're done. Use
2027 the release notes and Change Log from the source tarball package.
2029 -------------------------------------------------------------------------------
2033 Login to Sourceforge's compile-farm via ssh:
2035 ssh cf.sourceforge.net
2037 Choose the right operating system. When logged in, make sure that you have
2038 freshly exported the right version into an empty directory. (See "Building and
2039 releasing packages" above). Then run:
2042 autoheader && autoconf && ./configure
2048 which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
2049 on the Sourceforge machine (no ncftpput). You now have to manually upload the
2050 archive to Sourceforge's ftp server and release the file publicly. Use the
2051 release notes and Change Log from the source tarball package.
2053 -------------------------------------------------------------------------------
2057 First, make sure that you have freshly exported the right version into an empty
2058 directory. (See "Building and releasing packages" above). Then run:
2061 autoheader && autoconf && ./configure
2065 -------------------------------------------------------------------------------
2069 First, make sure that you have freshly exported the right version into an empty
2070 directory. (See "Building and releasing packages" above). Then run:
2073 autoheader && autoconf && ./configure
2077 -------------------------------------------------------------------------------
2081 Login to Sourceforge's compilefarm via ssh:
2083 ssh cf.sourceforge.net
2085 Choose the right operating system. When logged in, make sure that you have
2086 freshly exported the right version into an empty directory. (See "Building and
2087 releasing packages" above). Then run:
2090 autoheader && autoconf && ./configure
2096 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
2097 the Sourceforge machine (no ncftpput). You now have to manually upload the
2098 archive to Sourceforge's ftp server and release the file publicly. Use the
2099 release notes and Change Log from the source tarball package.
2101 -------------------------------------------------------------------------------
2103 6.4. Uploading and Releasing Your Package
2105 After the package is ready, it is time to upload it to SourceForge, and go
2106 through the release steps. The upload is done via FTP:
2108 * Upload to: ftp://upload.sourceforge.net/incoming
2112 * password: ijbswa-developers@lists.sourceforge.net
2114 Or use the make targets as described above.
2116 Once this done go to http://sourceforge.net/project/admin/editpackages.php?
2117 group_id=11118, making sure you are logged in. Find your target platform in the
2118 second column, and click Add Release. You will then need to create a new
2119 release for your package, using the format of $VERSION ($CODE_STATUS), e.g.
2122 Now just follow the prompts. Be sure to add any appropriate Release notes. You
2123 should see your freshly uploaded packages in "Step 2. Add Files To This
2124 Release". Check the appropriate box(es). Remember at each step to hit the
2125 "Refresh/Submit" buttons! You should now see your file(s) listed in Step 3.
2126 Fill out the forms with the appropriate information for your platform, being
2127 sure to hit "Update" for each file. If anyone is monitoring your platform,
2128 check the "email" box at the very bottom to notify them of the new package.
2131 If you have made errors, or need to make changes, you can go through
2132 essentially the same steps, but select Edit Release, instead of Add Release.
2134 -------------------------------------------------------------------------------
2136 6.5. After the Release
2138 When all (or: most of the) packages have been uploaded and made available, send
2139 an email to the announce mailing list, Subject: "Version X.Y.Z available for
2140 download". Be sure to include the download location, the release notes and the
2141 Changelog. Also, post an updated News item on the project page Sourceforge, and
2142 update the Home page and docs linked from the Home page (see below). Other news
2143 sites and release oriented sites, such as Freshmeat, should also be notified.
2145 -------------------------------------------------------------------------------
2147 7. Update the Webserver
2149 The webserver should be updated at least with each stable release. When
2150 updating, please follow these steps to make sure that no broken links,
2151 inconsistent contents or permission problems will occur (as it has many times
2154 If you have changed anything in the stable-branch documentation source SGML
2157 make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you)
2159 That will generate doc/webserver/user-manual, doc/webserver/developer-manual,
2160 doc/webserver/faq, doc/pdf/*.pdf and doc/webserver/index.html automatically.
2162 If you changed the manual page sources, generate doc/webserver/man-page/
2163 privoxy-man-page.html by running "make man". (This is a separate target due to
2164 dependencies on some obscure perl scripts [now in CVS, but not well tested].
2165 See comments in GNUmakefile.)
2167 If you want to add new files to the webserver, create them locally in the doc/
2168 webserver/* directory (or create new directories under doc/webserver).
2170 Next, commit any changes from the above steps to CVS. All set? If these are
2171 docs in the stable branch, then do:
2175 This will do the upload to the webserver (www.privoxy.org) and ensure all files
2176 and directories there are group writable.
2178 Please do NOT use any other means of transferring files to the webserver to
2179 avoid permission problems. Also, please do not upload docs from development
2180 branches or versions. The publicly posted docs should be in sync with the last
2183 -------------------------------------------------------------------------------
2185 8. Contacting the developers, Bug Reporting and Feature Requests
2187 We value your feedback. In fact, we rely on it to improve Privoxy and its
2188 configuration. However, please note the following hints, so we can provide you
2189 with the best support:
2191 -------------------------------------------------------------------------------
2195 For casual users, our support forum at SourceForge is probably best suited:
2196 http://sourceforge.net/tracker/?group_id=11118&atid=211118
2198 All users are of course welcome to discuss their issues on the users mailing
2199 list, where the developers also hang around.
2201 -------------------------------------------------------------------------------
2203 8.2. Reporting Problems
2205 "Problems" for our purposes, come in two forms:
2207 * Configuration issues, such as ads that slip through, or sites that don't
2208 function properly due to one Privoxy "action" or another being turned "on".
2210 * "Bugs" in the programming code that makes up Privoxy, such as that might
2213 -------------------------------------------------------------------------------
2215 8.2.1. Reporting Ads or Other Configuration Problems
2217 Please send feedback on ads that slipped through, innocent images that were
2218 blocked, sites that don't work properly, and other configuration related
2219 problem of default.action file, to http://sourceforge.net/tracker/?group_id=
2220 11118&atid=460288, the Actions File Tracker.
2222 New, improved default.action files may occasionally be made available based on
2223 your feedback. These will be announced on the ijbswa-announce list and
2224 available from our the files section of our project page.
2226 -------------------------------------------------------------------------------
2228 8.2.2. Reporting Bugs
2230 Please report all bugs only through our bug tracker: http://sourceforge.net/
2231 tracker/?group_id=11118&atid=111118.
2233 Before doing so, please make sure that the bug has not already been submitted
2234 and observe the additional hints at the top of the submit form. If already
2235 submitted, please feel free to add any info to the original report that might
2236 help to solve the issue.
2238 Please try to verify that it is a Privoxy bug, and not a browser or site bug
2239 first. If unsure, try toggling off Privoxy, and see if the problem persists. If
2240 you are using your own custom configuration, please try the stock configs to
2241 see if the problem is configuration related.
2243 If not using the latest version, the bug may have been found and fixed in the
2244 meantime. We would appreciate if you could take the time to upgrade to the
2245 latest version (or even the latest CVS snapshot) and verify your bug.
2247 Please be sure to provide the following information:
2249 * The exact Privoxy version of the proxy software (if you got the source from
2250 CVS, please also provide the source code revisions as shown in http://
2251 config.privoxy.org/show-version).
2253 * The operating system and versions you run Privoxy on, (e.g. Windows XP
2254 SP2), if you are using a Unix flavor, sending the output of "uname -a"
2257 * The name, platform, and version of the browser you were using (e.g.
2258 Internet Explorer v5.5 for Mac).
2260 * The URL where the problem occurred, or some way for us to duplicate the
2261 problem (e.g. http://somesite.example.com/?somethingelse=123).
2263 * Whether your version of Privoxy is one supplied by the developers of
2264 Privoxy via SourceForge, or somewhere else.
2266 * Whether you are using Privoxy in tandem with another proxy such as Tor. If
2267 so, please try disabling the other proxy.
2269 * Whether you are using a personal firewall product. If so, does Privoxy work
2272 * Any other pertinent information to help identify the problem such as config
2273 or log file excerpts (yes, you should have log file entries for each action
2276 * Please provide your SF login, or email address, in case we need to contact
2279 The appendix of the Privoxy User Manual also has helpful information on
2280 understanding actions, and action debugging.
2282 -------------------------------------------------------------------------------
2284 8.3. Request New Features
2286 You are welcome to submit ideas on new features or other proposals for
2287 improvement through our feature request tracker at http://sourceforge.net/
2288 tracker/?atid=361118&group_id=11118.
2290 -------------------------------------------------------------------------------
2294 For any other issues, feel free to use the mailing lists. Technically
2295 interested users and people who wish to contribute to the project are also
2296 welcome on the developers list! You can find an overview of all Privoxy-related
2297 mailing lists, including list archives, at: http://sourceforge.net/mail/?
2300 -------------------------------------------------------------------------------
2302 9. Privoxy Copyright, License and History
2304 Copyright © 2001 - 2006 by Privoxy Developers <
2305 ijbswa-developers@lists.sourceforge.net>
2307 Some source code is based on code Copyright © 1997 by Anonymous Coders and
2308 Junkbusters, Inc. and licensed under the GNU General Public License.
2310 -------------------------------------------------------------------------------
2314 Privoxy is free software; you can redistribute it and/or modify it under the
2315 terms of the GNU General Public License, version 2, as published by the Free
2316 Software Foundation.
2318 This program is distributed in the hope that it will be useful, but WITHOUT ANY
2319 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
2320 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
2321 is available from the Free Software Foundation, Inc, 51 Franklin Street, Fifth
2322 Floor, Boston, MA 02110-1301, USA
2324 You should have received a copy of the GNU General Public License along with
2325 this program; if not, write to the
2328 Foundation, Inc. 51 Franklin Street, Fifth Floor
2329 Boston, MA 02110-1301
2332 -------------------------------------------------------------------------------
2336 A long time ago, there was the Internet Junkbuster, by Anonymous Coders and
2337 Junkbusters Corporation. This saved many users a lot of pain in the early days
2338 of web advertising and user tracking.
2340 But the web, its protocols and standards, and with it, the techniques for
2341 forcing ads on users, give up autonomy over their browsing, and for tracking
2342 them, keeps evolving. Unfortunately, the Internet Junkbuster did not. Version
2343 2.0.2, published in 1998, was (and is) the last official release available from
2344 Junkbusters Corporation. Fortunately, it had been released under the GNU GPL,
2345 which allowed further development by others.
2347 So Stefan Waldherr started maintaining an improved version of the software, to
2348 which eventually a number of people contributed patches. It could already
2349 replace banners with a transparent image, and had a first version of pop-up
2350 killing, but it was still very closely based on the original, with all its
2351 limitations, such as the lack of HTTP/1.1 support, flexible per-site
2352 configuration, or content modification. The last release from this effort was
2353 version 2.0.2-10, published in 2000.
2355 Then, some developers picked up the thread, and started turning the software
2356 inside out, upside down, and then reassembled it, adding many new features
2359 The result of this is Privoxy, whose first stable version, 3.0, was released
2362 -------------------------------------------------------------------------------
2366 Other references and sites of interest to Privoxy users:
2368 http://www.privoxy.org/, the Privoxy Home page.
2370 http://www.privoxy.org/faq/, the Privoxy FAQ.
2372 http://sourceforge.net/projects/ijbswa/, the Project Page for Privoxy on
2375 http://config.privoxy.org/, the web-based user interface. Privoxy must be
2376 running for this to work. Shortcut: http://p.p/
2378 http://sourceforge.net/tracker/?group_id=11118&atid=460288, to submit "misses"
2379 and other configuration related suggestions to the developers.
2381 http://www.junkbusters.com/ht/en/cookies.html, an explanation how cookies are
2382 used to track web users.
2384 http://www.junkbusters.com/ijb.html, the original Internet Junkbuster.
2386 http://privacy.net/, a useful site to check what information about you is
2387 leaked while you browse the web.
2389 http://www.squid-cache.org/, a very popular caching proxy, which is often used
2390 together with Privoxy.
2392 http://tor.eff.org/, Tor can help anonymize web browsing, web publishing,
2393 instant messaging, IRC, SSH, and other applications.
2395 http://www.privoxy.org/developer-manual/, the Privoxy developer manual.
projects / privoxy.git / blob