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