1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
2 <!entity % dummy "INCLUDE">
3 <!entity supported SYSTEM "supported.sgml">
4 <!entity newfeatures SYSTEM "newfeatures.sgml">
5 <!entity p-intro SYSTEM "privoxy.sgml">
6 <!entity history SYSTEM "history.sgml">
7 <!entity seealso SYSTEM "seealso.sgml">
8 <!entity contacting SYSTEM "contacting.sgml">
9 <!entity copyright SYSTEM "copyright.sgml">
10 <!entity p-version "2.9.13">
11 <!entity p-status "BETA">
12 <!entity % p-not-stable "INCLUDE"> <!-- set to IGNORE for stable release -->
13 <!entity % p-stable "IGNORE"> <!-- set INCLUDE for stable release -->
14 <!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
15 <!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
18 File : $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
20 Purpose : developer manual
21 This file belongs into
22 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
24 $Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $
26 Written by and Copyright (C) 2001 the SourceForge
27 Privoxy team. http://www.privoxy.org/
29 Based on the Internet Junkbuster originally written
30 by and Copyright (C) 1997 Anonymous Coders and
31 Junkbusters Corporation. http://www.junkbusters.com
34 ========================================================================
35 NOTE: Please read developer-manual/documentation.html before touching
36 anything in this, or other Privoxy documentation. You have been warned!
37 Failure to abide by this rule will result in the revocation of your license
38 to live a peaceful existence!
39 ========================================================================
45 <title>Privoxy Developer Manual</title>
47 <pubdate>$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $</pubdate>
52 <orgname>By: Privoxy Developers</orgname>
61 This is here to keep vim syntax file from breaking :/
62 If I knew enough to fix it, I would.
63 PLEASE DO NOT REMOVE! HB: hal@foobox.net
68 The developer manual gives the users information on how to help the developer
69 team. It provides guidance on coding, testing, documentation and other
73 <!-- Include privoxy.sgml boilerplate text: -->
77 <!-- end boilerplate -->
80 You can find the latest version of the this manual at <ulink
81 url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
82 Please see the Contact section on how to contact the developers.
86 <!-- Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
92 <!-- ~~~~~ New section ~~~~~ -->
93 <sect1 id="intro" label=""><title></title>
94 <!-- dummy section to force TOC on page by itself -->
95 <!-- DO NOT REMOVE! please ;) -->
99 <!-- ~~~~~ New section ~~~~~ -->
102 <!-- ~~~~~ New section ~~~~~ -->
103 <sect1 label="1" id="introduction"><title>Introduction</title>
106 I don't like seeing blank space :) So added *something* here.
110 <application>Privoxy</application>, as an heir to
111 <application>Junkbuster</application>, is an Open Source project
112 and licensed under the GPL. As such, <application>Privoxy</application>
113 development is potentially open to anyone who has the time, knowledge,
114 and desire to contribute in any capacity. Our goals are simply to
115 continue the mission, to improve <application>Privoxy</application>, and
116 to make it available to as wide an audience as possible.
119 One does not have to be a programmer to contribute. Packaging, testing,
120 and porting, are all important jobs as well.
124 <!-- ~~~~~ New section ~~~~~ -->
125 <sect1 id="quickstart"><title>Quickstart to Privoxy Development</title>
127 You'll need an account on <ulink
128 url="http://sourceforge.net">Sourceforge</ulink> to support our development.
129 Mail your ID to the list and wait until a project manager has added you.
133 For the time being (read, this section is under construction), please note the
134 following guidelines for changing stuff in the code. If it is
135 <orderedlist numeration="arabic">
137 A bugfix / clean-up / cosmetic thing: shoot
140 A new feature that can be turned off: shoot
143 A clear improvement w/o side effects on other parts of the code: shoot
146 A matter of taste: ask the list
149 A major redesign of some part of the code: ask the list
155 <!-- ~~~~~ New section ~~~~~ -->
156 <sect1 id="documentation"><title>Documentation Guidelines</title>
158 All formal documents are maintained in docbook SGML and located in the
159 <computeroutput>doc/source</computeroutput> directory. You will need
160 <ulink url="http://www.docbook.org">docbook</ulink> and the docbook
161 stylesheets (or comparable alternatives), and either
162 <application>jade</application> or <application>openjade</application>
163 (recommended) installed in order to build docs from source. Currently
165 url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
166 <ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and,
167 of course this, the <citetitle>developer-manual</citetitle> in this
168 format. The <citetitle>README</citetitle>, is also now maintained
169 as SGML. The <citetitle>README</citetitle> in the top-level source
170 directory is a generated file. <emphasis>DO NOT edit this
171 directly</emphasis>. Edit the SGML source!
174 Other, less formal documents (e.g. AUTHORS, LICENSE) are maintained as
175 plain text files in the toplevel source directory. At least for the
179 Packagers are encouraged to include this documentation. For those without
180 the ability to build the docs locally, text versions of each are kept in
181 CVS. Or HTML versions can be downloaded from the <ulink
182 url="http://www.privoxy.org">www.privoxy.org</ulink> website, which
183 should be fairly current. (This is only a temporary solution.)
186 Formal documents are built with the Makefile targets of
187 <computeroutput>make dok</computeroutput>, or alternately
188 <computeroutput>make redhat-dok</computeroutput>. If you have problems,
189 try both. The build process uses the document SGML sources in
190 <computeroutput>doc/source</computeroutput> to update all text files in
191 <computeroutput>doc/text</computeroutput> and to update all HTML
192 documents in <computeroutput>doc/webserver</computeroutput>.
195 Documentation writers should please make sure documents build
196 successfully before committing to CVS.
199 How do you update the webserver (i.e. the pages on privoxy.org)?
201 <orderedlist numeration="arabic">
203 First, build the docs by running <computeroutput>make
204 dok</computeroutput> (or alternately <computeroutput>make
205 redhat-dok</computeroutput>).
208 Run <computeroutput>make webserver</computeroutput> which copies all
209 files from <computeroutput>doc/webserver</computeroutput> to the
210 sourceforge webserver via scp.
216 <!-- ~~~~~ New section ~~~~~ -->
218 <title>Quickstart to Docbook and SGML</title>
220 If you are not familiar with SGML, it is a markup language similar to HTML.
221 In fact, HTML is an SGML application. Both use <quote>tags</quote>
222 to format text and other content. SGML tags are much more varied,
223 and flexible, but do much of the same kinds of things. The tags,
224 or <quote>elements</quote>, are definable in SGML. There is no
225 set <quote>standards</quote>. Since we are using
226 <application>Docbook</application>, our tags are those that are
227 defined by <application>Docbook</application>. Much of how the
228 finish document is rendered is determined by the <quote>stylesheets</quote>.
229 The stylesheets determine how each tag gets translated to HTML, or
234 Tags in SGML need to be always <quote>closed</quote>. If not, you
235 will likely generate errors. Example:
236 <literal><title>My Title</title></literal>. They are
237 also case-insensitive, but we strongly suggest using all lower
238 case. This keeps compatibility with [Docbook] <application>XML</application>.
242 Our documents use <quote>sections</quote> for the most part. Sections
243 will be processed into HTML headers (e.g. <literal>h1</literal> for
244 <literal>sect1</literal>). The <application>Docbook</application> stylesheets
245 will use these to also generate the Table of Contents for each doc. Our
246 TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
247 <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
248 entries, but <literal>sect4</literal> will not. Each section requires
249 a <literal><title></literal> element, and at least one
250 <literal><para></literal>. There is a limit of five section
251 levels in Docbook, but generally three should be sufficient for our
256 Some common elements that you likely will use:
261 <emphasis><para></para></emphasis>, paragraph delimiter. Most
262 text needs to be within paragraph elements.
265 <emphasis><emphasis></emphasis></emphasis>, stylesheets make this
269 <emphasis><filename></filename></emphasis>, files and directories.
272 <emphasis><command></command></emphasis>, command examples.
275 <emphasis><literallayout></literllayout></emphasis>, like
276 <literal><pre></literal>, more or less.
279 <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
282 <emphasis><listitem></listitem></emphasis>, member of the above.
285 <emphasis><screen></screen></emphasis>, screen output, implies
286 <literal><literallayout></literal>.
289 <emphasis><ulink url="example.com"></ulink></emphasis>, like
290 HTML <literal><a></literal> tag.
293 <emphasis><quote></quote></emphasis>, for, doh, quoting text.
298 Look at any of the existing docs for examples of all these and more.
304 <!-- ~~~~~ New section ~~~~~ -->
305 <sect2 id="docstyle">
306 <title><application>Privoxy</application> Documentation Style</title>
308 It will be easier if everyone follows a similar writing style. This
309 just makes it easier to read what someone else has written if it
310 is all done in a similar fashion.
319 All tags should be lower case.
324 Tags delimiting a block of text should be on their own line.
331 Tags marking individual words, or few words, should be in-line:
333 Just to <emphasis>emphasize</emphasis>, some text goes here.
339 Tags should be nested and step indented like:
345 Some text goes here in our list example.
348 </itemizedlist>
351 This makes it easier to find the text amongst the tags ;-)
356 Use white space to separate logical divisions within a document,
357 like between sections. Running everything together consistently
358 makes it harder to read and work on.
363 Do not hesitate to make comments. Comments can either use the
364 <comment> element, or the <!-- --> style comment
370 We have an international audience. Refrain from slang, or English
371 idiosyncrasies (too many to list :).
376 Try to keep overall line lengths in source files to 80 characters or less
377 for obvious reasons. This is not always possible, with lenghty URLs for
383 Our documents are available in differing formats. Right now, they
384 are just plain text, and HTML, but PDF, and others is always a
385 future possibility. Be careful with URLs (<ulink>), and avoid
389 My favorite site is <ulink url="http://example.com">here</ulink>.
392 This will render as <quote>My favorite site is here</quote>, which is
393 not real helpful in a text doc. Better like this:
396 My favorite site is <ulink url="http://example.com">example.com</ulink>.
401 All documents should be spell checked occasionally.
402 <application>aspell</application> can check SGML with the
403 <literal>-H</literal> option. (<application>ispell</application> I think
414 <!-- ~~~~~ New section ~~~~~ -->
416 <sect2><title>Privoxy Custom Entities</title>
418 <application>Privoxy</application> documentation is using
419 a number of customized <quote>entities</quote> to facilitate
420 documentation maintenance.
423 We are using a set of <quote>boilerplate</quote> files with generic text,
424 that is used by multiple docs. This way we can write something once, and use
425 it repeatedly without having to re-write the same content over and over again.
426 If editing such a file, keep in mind that it should be
427 <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
428 contexts without additional modifications.
431 We are also using what <application>Docbook</application> calls
432 <quote>internal entities</quote>. These are like variables in
433 programming. Well, sort of. For instance, we have the
434 <literal>p-version</literal> entity that contains the current
435 <application>Privoxy</application> version string. You are strongly
436 encouraged to use these where possible. Some of these obviously
437 require re-setting with each release. A sampling of custom entities are
438 listed below. See any of the main docs for examples.
445 Re-cyclable <quote>boilerplate</quote> text entities are defined like:
448 <literal><!entity supported SYSTEM "supported.sgml"></literal>
451 In this example, the contents of the file,
452 <filename>supported.sgml</filename> is available for inclusion anywhere
453 in the doc. To make this happen, just reference the now defined
454 entity: <literal>&supported;</literal> (starts with an ampersand
455 and ends with a semi-colon), and the contents will be dumped into
456 the finished doc at that point.
461 Commonly used <quote>internal entities</quote>:
465 <emphasis>p-version</emphasis>: the <application>Privoxy</application>
466 version string, e.g. <quote>2.9.13</quote>.
469 <emphasis>p-status</emphasis>: the project status, either
470 <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
473 <emphasis>p-not-stable</emphasis>: use to conditionally include
474 text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
477 <emphasis>p-stable</emphasis>: just the opposite.
480 <emphasis>p-text</emphasis>: this doc is only generated as text.
487 There are others in various places that are defined for a specific
488 purpose. Read the source!
495 <!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
496 <!-- points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
498 <!-- ~~~~~ New section ~~~~~ -->
499 <sect1 id="coding"><title>Coding Guidelines</title>
501 <sect2 id="s1"><title>Introduction</title>
503 <para>This set of standards is designed to make our lives easier. It is
504 developed with the simple goal of helping us keep the "new and improved
505 <application>Privoxy</application>" consistent and reliable. Thus making
506 maintenance easier and increasing chances of success of the
509 <para>And that of course comes back to us as individuals. If we can
510 increase our development and product efficiencies then we can solve more
511 of the request for changes/improvements and in general feel good about
512 ourselves. ;-></para>
516 <sect2 id="s2"><title>Using Comments</title>
519 <sect3 id="s3"><title>Comment, Comment, Comment</title>
521 <para><emphasis>Explanation:</emphasis></para>
523 <para>Comment as much as possible without commenting the obvious.
524 For example do not comment "aVariable is equal to bVariable".
525 Instead explain why aVariable should be equal to the bVariable.
526 Just because a person can read code does not mean they will
527 understand why or what is being done. A reader may spend a lot
528 more time figuring out what is going on when a simple comment
529 or explanation would have prevented the extra research. Please
530 help your brother IJB'ers out!</para>
532 <para>The comments will also help justify the intent of the code.
533 If the comment describes something different than what the code
534 is doing then maybe a programming error is occurring.</para>
536 <para><emphasis>Example:</emphasis></para>
538 /* if page size greater than 1k ... */
539 if ( PageLength() > 1024 )
541 ... "block" the page up ...
544 /* if page size is small, send it in blocks */
545 if ( PageLength() > 1024 )
547 ... "block" the page up ...
550 This demonstrates 2 cases of "what not to do". The first is a
551 "syntax comment". The second is a comment that does not fit what
552 is actually being done.
558 <sect3 id="s4"><title>Use blocks for comments</title>
560 <para><emphasis>Explanation:</emphasis></para>
562 <para>Comments can help or they can clutter. They help when they
563 are differentiated from the code they describe. One line
564 comments do not offer effective separation between the comment
565 and the code. Block identifiers do, by surrounding the code
566 with a clear, definable pattern.</para>
568 <para><emphasis>Example:</emphasis></para>
570 /*********************************************************************
571 * This will stand out clearly in your code!
572 *********************************************************************/
573 if ( thisVariable == thatVariable )
575 DoSomethingVeryImportant();
579 /* unfortunately, this may not */
580 if ( thisVariable == thatVariable )
582 DoSomethingVeryImportant();
586 if ( thisVariable == thatVariable ) /* this may not either */
588 DoSomethingVeryImportant();
591 <para><emphasis>Exception:</emphasis></para>
593 <para>If you are trying to add a small logic comment and do not
594 wish to "disrubt" the flow of the code, feel free to use a 1
595 line comment which is NOT on the same line as the code.</para>
601 <sect3 id="s5"><title>Keep Comments on their own line</title>
603 <para><emphasis>Explanation:</emphasis></para>
605 <para>It goes back to the question of readability. If the comment
606 is on the same line as the code it will be harder to read than
607 the comment that is on its own line.</para>
609 <para>There are three exceptions to this rule, which should be
610 violated freely and often: during the definition of variables,
611 at the end of closing braces, when used to comment
614 <para><emphasis>Example:</emphasis></para>
616 /*********************************************************************
617 * This will stand out clearly in your code,
618 * But the second example won't.
619 *********************************************************************/
620 if ( thisVariable == thatVariable )
622 DoSomethingVeryImportant();
625 if ( thisVariable == thatVariable ) /*can you see me?*/
627 DoSomethingVeryImportant(); /*not easily*/
631 /*********************************************************************
632 * But, the encouraged exceptions:
633 *********************************************************************/
634 int urls_read = 0; /* # of urls read + rejected */
635 int urls_rejected = 0; /* # of urls rejected */
639 DoSomethingVeryImportant();
643 short DoSomethingVeryImportant(
644 short firstparam, /* represents something */
645 short nextparam /* represents something else */ )
649 } /* -END- DoSomethingVeryImportant */
654 <sect3 id="s6"><title>Comment each logical step</title>
656 <para><emphasis>Explanation:</emphasis></para>
658 <para>Logical steps should be commented to help others follow the
659 intent of the written code and comments will make the code more
662 <para>If you have 25 lines of code without a comment, you should
663 probably go back into it to see where you forgot to put
666 <para>Most "for", "while", "do", etc... loops _probably_ need a
667 comment. After all, these are usually major logic
674 <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
676 <para><emphasis>Explanation:</emphasis></para>
678 <para>A reader of the code should be able to look at the comments
679 just prior to the beginning of a function and discern the
680 reason for its existence and the consequences of using it. The
681 reader should not have to read through the code to determine if
682 a given function is safe for a desired use. The proper
683 information thoroughly presented at the introduction of a
684 function not only saves time for subsequent maintenance or
685 debugging, it more importantly aids in code reuse by allowing a
686 user to determine the safety and applicability of any function
687 for the problem at hand. As a result of such benefits, all
688 functions should contain the information presented in the
689 addendum section of this document.</para>
695 <sect3 id="s8"><title>Comment at the end of braces if the
696 content is more than one screen length</title>
698 <para><emphasis>Explanation:</emphasis></para>
700 <para>Each closing brace should be followed on the same line by a
701 comment that describes the origination of the brace if the
702 original brace is off of the screen, or otherwise far away from
703 the closing brace. This will simplify the debugging,
704 maintenance, and readability of the code.</para>
706 <para>As a suggestion , use the following flags to make the
707 comment and its brace more readable:</para>
709 <para>use following a closing brace: } /* -END- if() or while ()
712 <para><emphasis>Example:</emphasis></para>
716 DoSomethingVeryImportant();
717 ...some long list of commands...
718 } /* -END- if x is 1 */
724 DoSomethingVeryImportant();
725 ...some long list of commands...
726 } /* -END- if ( 1 == X ) */
732 <sect2 id="s9"><title>Naming Conventions</title>
736 <sect3 id="s10"><title>Variable Names</title>
738 <para><emphasis>Explanation:</emphasis></para>
740 <para>Use all lowercase, and seperate words via an underscore
741 ('_'). Do not start an identifier with an underscore. (ANSI C
742 reserves these for use by the compiler and system headers.) Do
743 not use identifiers which are reserved in ANSI C++. (E.g.
744 template, class, true, false, ...). This is in case we ever
745 decide to port Privoxy to C++.</para>
747 <para><emphasis>Example:</emphasis></para>
749 int ms_iis5_hack = 0;</programlisting>
751 <para><emphasis>Instead of:</emphasis></para>
755 int msiis5hack = 0; int msIis5Hack = 0;
763 <sect3 id="s11"><title>Function Names</title>
765 <para><emphasis>Explanation:</emphasis></para>
767 <para>Use all lowercase, and seperate words via an underscore
768 ('_'). Do not start an identifier with an underscore. (ANSI C
769 reserves these for use by the compiler and system headers.) Do
770 not use identifiers which are reserved in ANSI C++. (E.g.
771 template, class, true, false, ...). This is in case we ever
772 decide to port Privoxy to C++.</para>
774 <para><emphasis>Example:</emphasis></para>
776 int load_some_file( struct client_state *csp )</programlisting>
778 <para><emphasis>Instead of:</emphasis></para>
782 int loadsomefile( struct client_state *csp )
783 int loadSomeFile( struct client_state *csp )
791 <sect3 id="s12"><title>Header file prototypes</title>
793 <para><emphasis>Explanation:</emphasis></para>
795 <para>Use a descriptive parameter name in the function prototype
796 in header files. Use the same parameter name in the header file
797 that you use in the c file.</para>
799 <para><emphasis>Example:</emphasis></para>
801 (.h) extern int load_aclfile( struct client_state *csp );
802 (.c) int load_aclfile( struct client_state *csp )</programlisting>
804 <para><emphasis>Instead of:</emphasis>
806 (.h) extern int load_aclfile( struct client_state * ); or
807 (.h) extern int load_aclfile();
808 (.c) int load_aclfile( struct client_state *csp )
816 <sect3 id="s13"><title>Enumerations, and #defines</title>
818 <para><emphasis>Explanation:</emphasis></para>
820 <para>Use all capital letters, with underscores between words. Do
821 not start an identifier with an underscore. (ANSI C reserves
822 these for use by the compiler and system headers.)</para>
824 <para><emphasis>Example:</emphasis></para>
826 (enumeration) : enum Boolean { FALSE, TRUE };
827 (#define) : #define DEFAULT_SIZE 100;</programlisting>
829 <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
830 that toggle a feature in the preprocessor: FEATURE_>, where
831 > is a short (preferably 1 or 2 word) description.</para>
833 <para><emphasis>Example:</emphasis></para>
835 #define FEATURE_FORCE 1
838 #define FORCE_PREFIX blah
839 #endif /* def FEATURE_FORCE */
844 <sect3 id="s14"><title>Constants</title>
846 <para><emphasis>Explanation:</emphasis></para>
848 <para>Spell common words out entirely (do not remove vowels).</para>
850 <para>Use only widely-known domain acronyms and abbreviations.
851 Capitalize all letters of an acronym.</para>
853 <para>Use underscore (_) to separate adjacent acronyms and
854 abbreviations. Never terminate a name with an underscore.</para>
856 <para><emphasis>Example:</emphasis></para>
858 #define USE_IMAGE_LIST 1</programlisting>
860 <para><emphasis>Instead of:</emphasis></para>
864 #define USE_IMG_LST 1 or
865 #define _USE_IMAGE_LIST 1 or
866 #define USE_IMAGE_LIST_ 1 or
867 #define use_image_list 1 or
868 #define UseImageList 1
878 <sect2 id="s15"><title>Using Space</title>
882 <sect3 id="s16"><title>Put braces on a line by themselves.</title>
884 <para><emphasis>Explanation:</emphasis></para>
886 <para>The brace needs to be on a line all by itself, not at the
887 end of the statement. Curly braces should line up with the
888 construct that they're associated with. This practice makes it
889 easier to identify the opening and closing braces for a
892 <para><emphasis>Example:</emphasis></para>
899 <para><emphasis>Instead of:</emphasis></para>
901 <para>if ( this == that ) { ... }</para>
905 <para>if ( this == that ) { ... }</para>
907 <para><emphasis>Note:</emphasis> In the special case that the if-statement is
908 inside a loop, and it is trivial, i.e. it tests for a
909 condidtion that is obvious from the purpose of the block,
910 one-liners as above may optically preserve the loop structure
911 and make it easier to read.</para>
913 <para><emphasis>Status:</emphasis> developer-discrection.</para>
915 <para><emphasis>Example exception:</emphasis></para>
917 while ( more lines are read )
919 /* Please document what is/is not a comment line here */
920 if ( it's a comment ) continue;
922 do_something( line );
928 <sect3 id="s17"><title>ALL control statements should have a
931 <para><emphasis>Explanation:</emphasis></para>
933 <para>Using braces to make a block will make your code more
934 readable and less prone to error. All control statements should
935 have a block defined.</para>
937 <para><emphasis>Example:</emphasis></para>
945 <para><emphasis>Instead of:</emphasis></para>
947 <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
951 <para>if ( this == that ) DoSomething();</para>
953 <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
954 in a manner other than that which the developer desired (per
955 indentation). Using code braces would have prevented this
956 "feature". The "explanation" and "exception" from the point
957 above also applies.</para>
963 <sect3 id="s18"><title>Do not belabor/blow-up boolean
966 <para><emphasis>Example:</emphasis></para>
968 structure->flag = ( condition );</programlisting>
970 <para><emphasis>Instead of:</emphasis></para>
972 <para>if ( condition ) { structure->flag = 1; } else {
973 structure->flag = 0; }</para>
975 <para><emphasis>Note:</emphasis> The former is readable and consice. The later
976 is wordy and inefficient. Please assume that any developer new
977 to the project has at least a "good" knowledge of C/C++. (Hope
978 I do not offend by that last comment ... 8-)</para>
984 <sect3 id="s19"><title>Use white space freely because it is
987 <para><emphasis>Explanation:</emphasis></para>
989 <para>Make it readable. The notable exception to using white space
990 freely is listed in the next guideline.</para>
992 <para><emphasis>Example:</emphasis></para>
996 int anotherValue = 0;
997 int thisVariable = 0;
999 if ( thisVariable == thatVariable )
1001 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
1006 <sect3 id="s20"><title>Don't use white space around structure
1009 <para><emphasis>Explanation:</emphasis></para>
1011 <para>- structure pointer operator ( "->" ) - member operator (
1012 "." ) - functions and parentheses</para>
1014 <para>It is a general coding practice to put pointers, references,
1015 and function parentheses next to names. With spaces, the
1016 connection between the object and variable/function name is not
1019 <para><emphasis>Example:</emphasis></para>
1023 FunctionName();</programlisting>
1025 <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
1026 FunctionName ();</para>
1032 <sect3 id="s21"><title>Make the last brace of a function stand
1035 <para><emphasis>Example:</emphasis></para>
1037 int function1( ... )
1042 } /* -END- function1 */
1045 int function2( ... )
1047 } /* -END- function2 */
1050 <para><emphasis>Instead of:</emphasis></para>
1052 <para>int function1( ... ) { ...code... return( retCode ); } int
1053 function2( ... ) { }</para>
1055 <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
1056 lines afterwards. This makes the end of function standout to
1057 the most casual viewer. Although function comments help
1058 seperate functions, this is still a good coding practice. In
1059 fact, I follow these rules when using blocks in "for", "while",
1060 "do" loops, and long if {} statements too. After all whitespace
1063 <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
1064 lines. Enforced is the end of function comments.</para>
1070 <sect3 id="s22"><title>Use 3 character indentions</title>
1072 <para><emphasis>Explanation:</emphasis></para>
1074 <para>If some use 8 character TABs and some use 3 character TABs,
1075 the code can look *very* ragged. So use 3 character indentions
1076 only. If you like to use TABs, pass your code through a filter
1077 such as "expand -t3" before checking in your code.</para>
1079 <para><emphasis>Example:</emphasis></para>
1081 static const char * const url_code_map[256] =
1087 int function1( ... )
1091 return( ALWAYS_TRUE );
1095 return( HOW_DID_YOU_GET_HERE );
1098 return( NEVER_GETS_HERE );
1107 <sect2 id="s23"><title>Initializing</title>
1111 <sect3 id="s24"><title>Initialize all variables</title>
1113 <para><emphasis>Explanation:</emphasis></para>
1115 <para>Do not assume that the variables declared will not be used
1116 until after they have been assigned a value somewhere else in
1117 the code. Remove the chance of accidentally using an unassigned
1120 <para><emphasis>Example:</emphasis></para>
1124 struct *ptr = NULL;</programlisting>
1126 <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
1127 message says you are trying to access memory address 00000000
1128 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
1131 <para><emphasis>Status:</emphasis> developer-discrection if and only if the
1132 variable is assigned a value "shortly after" declaration.</para>
1138 <sect2 id="s25"><title>Functions</title>
1142 <sect3 id="s26"><title>Name functions that return a boolean as a
1145 <para><emphasis>Explanation:</emphasis></para>
1147 <para>Value should be phrased as a question that would logically
1148 be answered as a true or false statement</para>
1150 <para><emphasis>Example:</emphasis></para>
1152 ShouldWeBlockThis();
1159 <sect3 id="s27"><title>Always specify a return type for a
1162 <para><emphasis>Explanation:</emphasis></para>
1164 <para>The default return for a function is an int. To avoid
1165 ambiguity, create a return for a function when the return has a
1166 purpose, and create a void return type if the function does not
1167 need to return anything.</para>
1173 <sect3 id="s28"><title>Minimize function calls when iterating by
1174 using variables</title>
1176 <para><emphasis>Explanation:</emphasis></para>
1178 <para>It is easy to write the following code, and a clear argument
1179 can be made that the code is easy to understand:</para>
1181 <para><emphasis>Example:</emphasis></para>
1183 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1188 <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
1189 each and every iteration. This increases the overhead in the
1190 program, because the compiler has to look up the function each
1191 time, call it, and return a value. Depending on what occurs in
1192 the blockListLength() call, it might even be creating and
1193 destroying structures with each iteration, even though in each
1194 case it is comparing "cnt" to the same value, over and over.
1195 Remember too - even a call to blockListLength() is a function
1196 call, with the same overhead.</para>
1198 <para>Instead of using a function call during the iterations,
1199 assign the value to a variable, and evaluate using the
1202 <para><emphasis>Example:</emphasis></para>
1204 size_t len = blockListLength();
1206 for ( size_t cnt = 0; cnt < len; cnt ++ )
1211 <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
1212 change or could *potentially* change, then you must code the
1213 function call in the for/while loop.</para>
1219 <sect3 id="s29"><title>Pass and Return by Const Reference</title>
1221 <para><emphasis>Explanation:</emphasis></para>
1223 <para>This allows a developer to define a const pointer and call
1224 your function. If your function does not have the const
1225 keyword, we may not be able to use your function. Consider
1226 strcmp, if it were defined as: extern int strcmp( char *s1,
1229 <para>I could then not use it to compare argv's in main: int main(
1230 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1233 <para>Both these pointers are *const*! If the c runtime library
1234 maintainers do it, we should too.</para>
1240 <sect3 id="s30"><title>Pass and Return by Value</title>
1242 <para><emphasis>Explanation:</emphasis></para>
1244 <para>Most structures cannot fit onto a normal stack entry (i.e.
1245 they are not 4 bytes or less). Aka, a function declaration
1246 like: int load_aclfile( struct client_state csp )</para>
1248 <para>would not work. So, to be consistent, we should declare all
1249 prototypes with "pass by value": int load_aclfile( struct
1250 client_state *csp )</para>
1256 <sect3 id="s31"><title>Names of include files</title>
1258 <para><emphasis>Explanation:</emphasis></para>
1260 <para>Your include statements should contain the file name without
1261 a path. The path should be listed in the Makefile, using -I as
1262 processor directive to search the indicated paths. An exception
1263 to this would be for some proprietary software that utilizes a
1264 partial path to distinguish their header files from system or
1265 other header files.</para>
1267 <para><emphasis>Example:</emphasis></para>
1269 #include <iostream.h> /* This is not a local include */
1270 #include "config.h" /* This IS a local include */
1273 <para><emphasis>Exception:</emphasis></para>
1277 /* This is not a local include, but requires a path element. */
1278 #include <sys/fileName.h>
1282 <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
1283 without a _very_ good reason. This duplicates the #include
1284 "file.h" behaviour.</para>
1290 <sect3 id="s32"><title>Provide multiple inclusion
1293 <para><emphasis>Explanation:</emphasis></para>
1295 <para>Prevents compiler and linker errors resulting from
1296 redefinition of items.</para>
1298 <para>Wrap each header file with the following syntax to prevent
1299 multiple inclusions of the file. Of course, replace PROJECT_H
1300 with your file name, with "." Changed to "_", and make it
1303 <para><emphasis>Example:</emphasis></para>
1305 #ifndef PROJECT_H_INCLUDED
1306 #define PROJECT_H_INCLUDED
1308 #endif /* ndef PROJECT_H_INCLUDED */
1313 <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
1315 <para><emphasis>Explanation:</emphasis></para>
1317 <para>If our headers are included from C++, they must declare our
1318 functions as `extern "C"`. This has no cost in C, but increases
1319 the potential re-usability of our code.</para>
1321 <para><emphasis>Example:</emphasis></para>
1326 #endif /* def __cplusplus */
1328 ... function definitions here ...
1332 #endif /* def __cplusplus */
1337 <sect3 id="s34"><title>Where Possible, Use Forward Struct
1338 Declaration Instead of Includes</title>
1340 <para><emphasis>Explanation:</emphasis></para>
1342 <para>Useful in headers that include pointers to other struct's.
1343 Modifications to excess header files may cause needless
1346 <para><emphasis>Example:</emphasis></para>
1348 /*********************************************************************
1349 * We're avoiding an include statement here!
1350 *********************************************************************/
1352 extern file_list *xyz;</programlisting>
1354 <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
1355 pointer), then including the proper header file is necessary.
1356 If you only want to prototype a pointer, however, the header
1357 file is unneccessary.</para>
1359 <para><emphasis>Status:</emphasis> Use with discrection.</para>
1365 <sect2 id="s35"><title>General Coding Practices</title>
1369 <sect3 id="s36"><title>Turn on warnings</title>
1371 <para><emphasis>Explanation</emphasis></para>
1373 <para>Compiler warnings are meant to help you find bugs. You
1374 should turn on as many as possible. With GCC, the switch is
1375 "-Wall". Try and fix as many warnings as possible.</para>
1381 <sect3 id="s37"><title>Provide a default case for all switch
1384 <para><emphasis>Explanation:</emphasis></para>
1386 <para>What you think is guaranteed is never really guaranteed. The
1387 value that you don't think you need to check is the one that
1388 someday will be passed. So, to protect yourself from the
1389 unknown, always have a default step in a switch statement.</para>
1391 <para><emphasis>Example:</emphasis></para>
1393 switch( hash_string( cmd ) )
1395 case hash_actions_file :
1405 ... anomly code goes here ...
1406 continue; / break; / exit( 1 ); / etc ...
1408 } /* end switch( hash_string( cmd ) ) */</programlisting>
1410 <para><emphasis>Note:</emphasis> If you already have a default condition, you
1411 are obviously exempt from this point. Of note, most of the
1412 WIN32 code calls `DefWindowProc' after the switch statement.
1413 This API call *should* be included in a default statement.</para>
1415 <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1416 as a robust programming issue. The "anomly code goes here" may
1417 be no more than a print to the STDERR stream (as in
1418 load_config). Or it may really be an ABEND condition.</para>
1420 <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1426 <sect3 id="s38"><title>Try to avoid falling through cases in a
1427 switch statement.</title>
1429 <para><emphasis>Explanation:</emphasis></para>
1431 <para>In general, you will want to have a 'break' statement within
1432 each 'case' of a switch statement. This allows for the code to
1433 be more readable and understandable, and furthermore can
1434 prevent unwanted surprises if someone else later gets creative
1435 and moves the code around.</para>
1437 <para>The language allows you to plan the fall through from one
1438 case statement to another simply by omitting the break
1439 statement within the case statement. This feature does have
1440 benefits, but should only be used in rare cases. In general,
1441 use a break statement for each case statement.</para>
1443 <para>If you choose to allow fall through, you should comment both
1444 the fact of the fall through and reason why you felt it was
1451 <sect3 id="s39"><title>Use 'long' or 'short' Instead of
1454 <para><emphasis>Explanation:</emphasis></para>
1456 <para>On 32-bit platforms, int usually has the range of long. On
1457 16-bit platforms, int has the range of short.</para>
1459 <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
1460 projects (including X/GNU-Emacs), there are typedefs to int4,
1461 int8, int16, (or equivalence ... I forget the exact typedefs
1462 now). Should we add these to IJB now that we have a "configure"
1469 <sect3 id="s40"><title>Don't mix size_t and other types</title>
1471 <para><emphasis>Explanation:</emphasis></para>
1473 <para>The type of size_t varies across platforms. Do not make
1474 assumptions about whether it is signed or unsigned, or about
1475 how long it is. Do not compare a size_t against another
1476 variable of a different type (or even against a constant)
1477 without casting one of the values. Try to avoid using size_t if
1484 <sect3 id="s41"><title>Declare each variable and struct on its
1487 <para><emphasis>Explanation:</emphasis></para>
1489 <para>It can be tempting to declare a series of variables all on
1490 one line. Don't.</para>
1492 <para><emphasis>Example:</emphasis></para>
1496 long c = 0;</programlisting>
1498 <para><emphasis>Instead of:</emphasis></para>
1500 <para>long a, b, c;</para>
1502 <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1503 individual variables - easier to add new variables without
1504 messing up the original ones - when searching on a variable to
1505 find its type, there is less clutter to "visually"
1508 <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1509 variables or other trivial variables; feel free to declare them
1510 on 1 line. You should, although, provide a good comment on
1511 their functions.</para>
1513 <para><emphasis>Status:</emphasis> developer-discrection.</para>
1519 <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1521 <para><emphasis>Explanation:</emphasis></para>
1523 <para>Create a local stuct (on the stack) if the variable will
1524 live and die within the context of one function call.</para>
1526 <para>Only "malloc" a struct (on the heap) if the variable's life
1527 will extend beyond the context of one function call.</para>
1529 <para><emphasis>Example:</emphasis></para>
1531 If a function creates a struct and stores a pointer to it in a
1532 list, then it should definately be allocated via `malloc'.
1537 <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1538 Responsible for Ensuring 'free'</title>
1540 <para><emphasis>Explanation:</emphasis></para>
1542 <para>If you have to "malloc" an instance, you are responsible for
1543 insuring that the instance is `free'd, even if the deallocation
1544 event falls within some other programmer's code. You are also
1545 responsible for ensuring that deletion is timely (i.e. not too
1546 soon, not too late). This is known as "low-coupling" and is a
1547 "good thing (tm)". You may need to offer a
1548 free/unload/destuctor type function to accomodate this.</para>
1550 <para><emphasis>Example:</emphasis></para>
1552 int load_re_filterfile( struct client_state *csp ) { ... }
1553 static void unload_re_filterfile( void *f ) { ... }</programlisting>
1555 <para><emphasis>Exceptions:</emphasis></para>
1557 <para>The developer cannot be expected to provide `free'ing
1558 functions for C run-time library functions ... such as
1561 <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
1562 standard is for allocating and freeing data structures (complex
1569 <sect3 id="s44"><title>Add loaders to the `file_list' structure
1570 and in order</title>
1572 <para><emphasis>Explanation:</emphasis></para>
1574 <para>I have ordered all of the "blocker" file code to be in alpha
1575 order. It is easier to add/read new blockers when you expect a
1576 certain order.</para>
1578 <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1579 places by POPUP tests coming before PCRS tests. But since
1580 POPUPs can also be referred to as KILLPOPUPs, it is clear that
1581 it should come first.</para>
1587 <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1588 exitinst code, use FIXME</title>
1590 <para><emphasis>Explanation:</emphasis></para>
1592 <para>If you have enough confidence in new code or confidence in
1593 your changes, but are not *quite* sure of the reprocussions,
1596 <para>/* FIXME: this code has a logic error on platform XYZ, *
1597 attempthing to fix */ #ifdef PLATFORM ...changed code here...
1602 <para>/* FIXME: I think the original author really meant this...
1603 */ ...changed code here...</para>
1607 <para>/* FIXME: new code that *may* break something else... */
1608 ...new code here...</para>
1610 <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1611 be a "good thing (tm)", it will be easier to identify and
1612 include in the project (or conversly exclude from the
1620 <sect2 id="s46"><title>Addendum: Template for files and function
1621 comment blocks:</title>
1623 <para><emphasis>Example for file comments:</emphasis></para>
1625 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $";
1626 /*********************************************************************
1628 * File : $S<!-- Break CVS Substitution -->ource$
1630 * Purpose : (Fill me in with a good description!)
1632 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1633 * Privoxy team. http://www.privoxy.org/
1635 * Based on the Internet Junkbuster originally written
1636 * by and Copyright (C) 1997 Anonymous Coders and
1637 * Junkbusters Corporation. http://www.junkbusters.com
1639 * This program is free software; you can redistribute it
1640 * and/or modify it under the terms of the GNU General
1641 * Public License as published by the Free Software
1642 * Foundation; either version 2 of the License, or (at
1643 * your option) any later version.
1645 * This program is distributed in the hope that it will
1646 * be useful, but WITHOUT ANY WARRANTY; without even the
1647 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1648 * PARTICULAR PURPOSE. See the GNU General Public
1649 * License for more details.
1651 * The GNU General Public License should be included with
1652 * this file. If not, you can view it at
1653 * http://www.gnu.org/copyleft/gpl.html
1654 * or write to the Free Software Foundation, Inc., 59
1655 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1658 * $L<!-- Break CVS Substitution -->og$
1660 *********************************************************************/
1665 ...necessary include files for us to do our work...
1667 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1670 <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1671 added to the "show-proxy-args" page. If this is a brand new
1672 creation by you, you are free to change the "Copyright" section
1673 to represent the rights you wish to maintain.</para>
1675 <para><emphasis>Note:</emphasis> The formfeed character that is present right
1676 after the comment flower box is handy for (X|GNU)Emacs users to
1677 skip the verbige and get to the heart of the code (via
1678 `forward-page' and `backward-page'). Please include it if you
1681 <para><emphasis>Example for file header comments:</emphasis></para>
1685 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.24 2002/04/04 21:33:37 hal9 Exp $"
1686 /*********************************************************************
1688 * File : $S<!-- Break CVS Substitution -->ource$
1690 * Purpose : (Fill me in with a good description!)
1692 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1693 * Privoxy team. http://www.privoxy.org/
1695 * Based on the Internet Junkbuster originally written
1696 * by and Copyright (C) 1997 Anonymous Coders and
1697 * Junkbusters Corporation. http://www.junkbusters.com
1699 * This program is free software; you can redistribute it
1700 * and/or modify it under the terms of the GNU General
1701 * Public License as published by the Free Software
1702 * Foundation; either version 2 of the License, or (at
1703 * your option) any later version.
1705 * This program is distributed in the hope that it will
1706 * be useful, but WITHOUT ANY WARRANTY; without even the
1707 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1708 * PARTICULAR PURPOSE. See the GNU General Public
1709 * License for more details.
1711 * The GNU General Public License should be included with
1712 * this file. If not, you can view it at
1713 * http://www.gnu.org/copyleft/gpl.html
1714 * or write to the Free Software Foundation, Inc., 59
1715 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1718 * $L<!-- Break CVS Substitution -->og$
1720 *********************************************************************/
1723 #include "project.h"
1729 ... function headers here ...
1732 /* Revision control strings from this header and associated .c file */
1733 extern const char FILENAME_rcs[];
1734 extern const char FILENAME_h_rcs[];
1741 #endif /* ndef _FILENAME_H */
1750 <para><emphasis>Example for function comments:</emphasis></para>
1752 /*********************************************************************
1754 * Function : FUNCTION_NAME
1756 * Description : (Fill me in with a good description!)
1759 * 1 : param1 = pointer to an important thing
1760 * 2 : x = pointer to something else
1762 * Returns : 0 => Ok, everything else is an error.
1764 *********************************************************************/
1765 int FUNCTION_NAME( void *param1, const char *x )
1773 <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1774 able to parse our code to create a "self-documenting" web
1781 <!-- ~~~~~ New section ~~~~~ -->
1782 <sect1 id="cvs"><title>Version Control Guidelines</title>
1783 <para>To be filled. note on cvs comments. Don't only comment what you did,
1784 but also why you did it!
1788 <!-- ~~~~~ New section ~~~~~ -->
1789 <sect1 id="testing"><title>Testing Guidelines</title>
1793 <!-- ~~~~~ New section ~~~~~ -->
1794 <sect2 id="testing-plan"><title>Testplan for releases</title>
1796 Explain release numbers. major, minor. developer releases. etc.
1798 <orderedlist numeration="arabic">
1800 Remove any existing rpm with rpm -e
1803 Remove any file that was left over. This includes (but is not limited to)
1805 <listitem><para>/var/log/privoxy</para></listitem>
1806 <listitem><para>/etc/privoxy</para></listitem>
1807 <listitem><para>/usr/sbin/privoxy</para></listitem>
1808 <listitem><para>/etc/init.d/privoxy</para></listitem>
1809 <listitem><para>/usr/doc/privoxy*</para></listitem>
1813 Install the rpm. Any error messages?
1815 <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1816 (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1817 autostart work?</para></listitem>
1818 <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1819 <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1824 <!-- ~~~~~ New section ~~~~~ -->
1825 <sect2 id="testing-report"><title>Test reports</title>
1827 Please submit test reports only with the <ulink url="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005">test form</ulink>
1828 at sourceforge. Three simple steps:
1831 <listitem><para>Select category: the distribution you test on.</para></listitem>
1832 <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
1833 <listitem><para>Fill the Summary and Detailed Description with something
1834 intelligent (keep it short and precise).</para>
1837 Do not mail to the mailinglist (we cannot keep track on issues there).
1843 <!-- ~~~~~ New section ~~~~~ -->
1844 <sect1 id="newrelease"><title>Releasing a new version</title>
1846 To minimize trouble with distribution contents, webpage
1847 errors and the like, we strongly encourage you
1848 to follow this section if you prepare a new release of
1849 code or new pages on the webserver.
1852 The following programs are required to follow this process:
1853 <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
1854 <filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
1857 <sect2 id="beforerelease">
1858 <title>Before the Release</title>
1860 The following <emphasis>must be done by one of the
1861 developers</emphasis> prior to each new release:
1867 Make sure that everybody who has worked on the code in the last
1868 couple of days has had a chance to yell <quote>no!</quote> in case
1869 they have pending changes/fixes in their pipelines.
1874 Increment the version number in <filename>configure.in</filename> in
1875 CVS. Also, the RPM release number in
1876 <filename>configure.in</filename>. Do NOT touch version information
1877 after export from CVS. <emphasis>All packages</emphasis> will use the
1878 version and release data from <filename>configure.in</filename>.
1879 Local files should not be changed, except prior to a CVS commit!!!
1880 This way we are all on the same page!
1885 If the default actionsfile has changed since last release,
1886 bump up its version info in this line:
1890 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1894 Then change the version info in doc/webserver/actions/index.php,
1895 line: '$required_actions_file_version = "A.B";'
1900 Tag all files in CVS with the version number with
1901 <quote><command>cvs tag v_X_Y_Z</command></quote> (where X = major, Y
1902 = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
1908 The first package uploaded should be the official
1909 <quote>tarball</quote> release. This is built with the
1910 <quote><command>make tarball-dist</command></quote> Makefile
1911 target, and then can be uploaded with
1912 <quote><command>make tarball-upload</command></quote> (see below).
1919 <sect2 id="newrelease-web"><title>Update the webserver</title>
1921 All files must be group-readable and group-writable (or no one else
1922 will be able to change them). To update the webserver, create any
1923 pages locally in the <filename>doc/webserver</filename> directory (or
1924 create new directories under <filename>doc/webserver</filename>), then do
1932 Note that <quote><command>make dok</command></quote>
1933 (or <quote><command>make redhat-dok</command></quote>) creates
1934 <filename>doc/webserver/user-manual</filename>,
1935 <filename>doc/webserver/developer-manual</filename>,
1936 <filename>doc/webserver/faq</filename> and
1937 <filename>doc/webserver/man-page</filename> automatically.
1940 Please do NOT use any other means of transferring files to the
1941 webserver. <quote><command>make webserver</command></quote> not only
1942 uploads, but will make sure that the appropriate permissions are
1943 preserved for shared group access.
1947 <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
1949 Ensure that you have the latest code version. Hence run:
1954 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1955 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1963 autoheader && autoconf && ./configure
1971 make suse-dist or make redhat-dist
1975 To upload the package to Sourceforge, simply issue
1979 make suse-upload or make redhat-upload
1983 Go to the displayed URL and release the file publicly on Sourceforge.
1987 <sect2 id="newrelease-os2"><title>OS/2</title>
1989 Ensure that you have the latest code version. Hence run:
1994 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1995 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1997 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
2001 You will need a mix of development tools.
2002 The main compilation takes place with IBM Visual Age C++.
2003 Some ancillary work takes place with GNU tools, available from
2004 various sources like hobbes.nmsu.edu.
2005 Specificially, you will need <filename>autoheader</filename>,
2006 <filename>autoconf</filename> and <filename>sh</filename> tools.
2007 The packaging takes place with WarpIN, available from various sources, including
2008 its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2011 Change directory to the <filename>os2setup</filename> directory.
2012 Edit the os2build.cmd file to set the final executable filename.
2015 installExeName='privoxyos2_setup_X.Y.Z.exe'
2017 Next, edit the <filename>IJB.wis</filename> file so the release number matches
2018 in the <filename>PACKAGEID</filename> section:
2020 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2022 You're now ready to build. Run:
2026 And in the <filename>./files</filename> directory you will have the
2027 WarpIN-installable executable.
2028 Upload this anonymously to
2029 <filename>uploads.sourceforge.net/incoming</filename>, create a release
2030 for it, and you're done.
2034 <sect2 id="newrelease-solaris"><title>Solaris</title>
2036 Login to Sourceforge's compilefarm via ssh
2040 ssh cf.sourceforge.net
2044 Choose the right operating system (not the Debian one). If you have
2045 downloaded <application>Privoxy</application> before,
2050 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2051 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2055 If not, please <ulink
2056 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2057 Privoxy via CVS first</ulink>. Run:
2061 autoheader && autoconf && ./configure
2073 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2074 solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2075 to manually upload the archive to Sourceforge's ftp server and release
2080 <sect2 id="newrelease-windows"><title>Windows</title>
2082 Ensure that you have the latest code version. Hence run
2087 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2088 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2096 autoheader && autoconf && ./configure
2104 <sect2 id="newrelease-debian"><title>Debian</title>
2106 Ensure that you have the latest code version. Hence run:
2111 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2112 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2120 autoheader && autoconf && ./configure
2128 <sect2 id="newrelease-macosx"><title>Mac OSX</title>
2130 Ensure that you have the latest code version. Hence run:
2135 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2136 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2138 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
2142 From the osxsetup directory, run:
2148 This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
2149 <filename>configure</filename> as well as <filename>make</filename>.
2150 Finally, it will copy over the necessary files to the ./osxsetup/files directory
2151 for further processing by <filename>PackageMaker</filename>.
2154 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
2155 name to match the release, and hit the "Create package" button.
2156 If you specify ./Privoxy.pkg as the output package name, you can then create
2157 the distributable zip file with the command:
2159 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2161 You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
2162 <filename>uploads.sourceforge.net/incoming</filename>,
2163 create a release for it, and you're done.
2167 <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
2169 Change the version number of <application>Privoxy</application> in the
2170 configure.in file. Run:
2172 autoheader && autoconf && ./configure
2177 Login to Sourceforge's compilefarm via ssh:
2181 ssh cf.sourceforge.net
2185 Choose the right operating system. If you have downloaded Privoxy
2191 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2192 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2196 If not, please <ulink
2197 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2198 Privoxy via CVS first</ulink>. Run:
2202 autoheader && autoconf && ./configure
2214 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2215 freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
2216 to manually upload the archive to Sourceforge's ftp server and release
2221 <sect2 id="newrelease-tarball"><title>Tarball</title>
2223 Ensure that you have the latest code version. Hence run:
2228 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2229 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2238 autoheader && autoconf && ./configure
2250 To upload the package to Sourceforge, simply issue
2258 Goto the displayed URL and release the file publicly on Sourceforge.
2262 <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
2264 Ensure that you have the latest code version. Hence run:
2269 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2270 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2278 autoheader && autoconf && ./configure
2286 <sect2 id="newrelease-amiga"><title>Amiga OS</title>
2288 Ensure that you have the latest code version. Hence run:
2293 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2294 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2302 autoheader && autoconf && ./configure
2310 <sect2 id="newrelease-aix"><title>AIX</title>
2312 Login to Sourceforge's compilefarm via ssh:
2316 ssh cf.sourceforge.net
2320 Choose the right operating system. If you have downloaded Privoxy
2326 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2327 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2331 If not, please <ulink
2332 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2333 Privoxy via CVS first</ulink>. Run:
2337 autoheader && autoconf && ./configure
2349 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2350 aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
2351 to manually upload the archive to Sourceforge's ftp server and release
2358 <!-- ~~~~~ New section ~~~~~ -->
2359 <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
2360 <!-- Include contacting.sgml -->
2362 <!-- end contacting -->
2365 <!-- ~~~~~ New section ~~~~~ -->
2366 <sect1 id="copyright"><title>Copyright and History</title>
2368 <sect2><title>Copyright</title>
2369 <!-- Include copyright.sgml -->
2374 <sect2><title>History</title>
2375 <!-- Include history.sgml -->
2382 <!-- ~~~~~ New section ~~~~~ -->
2383 <sect1 id="seealso"><title>See also</title>
2384 <!-- Include seealso.sgml -->
2392 This program is free software; you can redistribute it
2393 and/or modify it under the terms of the GNU General
2394 Public License as published by the Free Software
2395 Foundation; either version 2 of the License, or (at
2396 your option) any later version.
2398 This program is distributed in the hope that it will
2399 be useful, but WITHOUT ANY WARRANTY; without even the
2400 implied warranty of MERCHANTABILITY or FITNESS FOR A
2401 PARTICULAR PURPOSE. See the GNU General Public
2402 License for more details.
2404 The GNU General Public License should be included with
2405 this file. If not, you can view it at
2406 http://www.gnu.org/copyleft/gpl.html
2407 or write to the Free Software Foundation, Inc., 59
2408 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2410 $Log: developer-manual.sgml,v $
2411 Revision 1.24 2002/04/04 21:33:37 hal9
2412 More on documenting the documents.
2414 Revision 1.23 2002/04/04 18:46:47 swa
2415 consistent look. reuse of copyright, history et. al.
2417 Revision 1.22 2002/04/04 17:27:56 swa
2418 more single file to be included at multiple points. make maintaining easier
2420 Revision 1.21 2002/04/04 06:48:37 hal9
2421 Structural changes to allow for conditional inclusion/exclusion of content
2422 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
2423 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2424 eventually be set by Makefile.
2425 More boilerplate text for use across multiple docs.
2427 Revision 1.20 2002/04/04 03:28:27 david__schmidt
2430 Revision 1.19 2002/04/03 15:09:42 david__schmidt
2431 Add OS/2 build section
2433 Revision 1.18 2002/04/03 03:51:48 hal9
2436 Revision 1.17 2002/04/03 01:21:17 hal9
2437 Implementing Andreas's suggestions for Release sections.
2439 Revision 1.16 2002/03/31 23:04:40 hal9
2440 Fleshed out the doc section, and added something for an intro so it was not
2443 Revision 1.15 2002/03/30 22:29:47 swa
2446 Revision 1.14 2002/03/30 19:04:08 swa
2447 people release differently. no good.
2448 I want to make parts of the docs only.
2450 Revision 1.13 2002/03/27 01:16:41 hal9
2453 Revision 1.12 2002/03/27 01:02:51 hal9
2454 Touch up on name change...
2456 Revision 1.11 2002/03/26 22:29:55 swa
2457 we have a new homepage!
2459 Revision 1.10 2002/03/24 12:33:01 swa
2462 Revision 1.9 2002/03/24 11:01:05 swa
2465 Revision 1.8 2002/03/23 15:13:11 swa
2466 renamed every reference to the old name with foobar.
2467 fixed "application foobar application" tag, fixed
2468 "the foobar" with "foobar". left junkbustser in cvs
2469 comments and remarks to history untouched.
2471 Revision 1.7 2002/03/11 13:13:27 swa
2472 correct feedback channels
2474 Revision 1.6 2002/02/24 14:25:06 jongfoster
2475 Formatting changes. Now changing the doctype to DocBook XML 4.1
2476 will work - no other changes are needed.
2478 Revision 1.5 2001/10/31 18:16:51 swa
2479 documentation added: howto generate docs in text and html
2480 format, howto move stuff to the webserver.
2482 Revision 1.4 2001/09/23 10:13:48 swa
2483 upload process established. run make webserver and
2484 the documentation is moved to the webserver. documents
2485 are now linked correctly.
2487 Revision 1.3 2001/09/13 15:27:40 swa
2490 Revision 1.2 2001/09/13 15:20:17 swa
2491 merged standards into developer manual
2493 Revision 1.1 2001/09/12 15:36:41 swa
2494 source files for junkbuster documentation
2496 Revision 1.3 2001/09/10 17:43:59 swa
2497 first proposal of a structure.
2499 Revision 1.2 2001/06/13 14:28:31 swa
2500 docs should have an author.
2502 Revision 1.1 2001/06/13 14:20:37 swa
2503 first import of project's documentation for the webserver.