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.23 2002/04/04 18:46:47 swa 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.23 2002/04/04 18:46:47 swa 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 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 Our documents are available in differing formats. Right now, they
377 are just plain text, and HTML, but PDF, and others is always a
378 future possibility. Be careful with URLs (<ulink>), and avoid
382 My favorite site is <ulink url="http://example.com">here</ulink>.
385 This will render as <quote>My favorite site is here</quote>, which is
386 not real helpful in a text doc. Better like this:
389 My favorite site is <ulink url="http://example.com">example.com</ulink>.
394 All documents should be spell checked occasionally.
395 <application>aspell</application> can check SGML with the
396 <literal>-H</literal> option. (<application>ispell</application> I think
407 <!-- ~~~~~ New section ~~~~~ -->
409 <sect2><title>Privoxy Custom Entities</title>
411 <application>Privoxy</application> documentation is using
412 a number of customized <quote>entities</quote> to facilitate
413 documentation maintenance.
416 We are using a set of <quote>boilerplate</quote> files with generic text,
417 that is used by multiple docs. This way we can write something once, and use
418 it repeatedly without having to re-write the same content over and over again.
419 If editing such a file, keep in mind that it should be
420 <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
421 contexts without additional modifications.
424 We are also using what <application>Docbook</application> calls
425 <quote>internal entities</quote>. These are like variables in
426 programming. Well, sort of. For instance, we have the
427 <literal>p-version</literal> entity that contains the current
428 <application>Privoxy</application> version string. You are strongly
429 encouraged to use these where possible. Some of these obviously
430 require re-setting with each release. A sampling of custom entities are
431 listed below. See any of the main docs for examples.
438 Re-cyclable <quote>boilerplate</quote> text entities are defined like:
441 <literal><!entity supported SYSTEM "supported.sgml"></literal>
444 In this example, the contents of the file,
445 <filename>supported.sgml</filename> is available for inclusion anywhere
446 in the doc. To make this happen, just reference the now defined
447 entity: <literal>&supported;</literal> (starts with an ampersand
448 and ends with a semi-colon), and the contents will be dumped into
449 the finished doc at that point.
454 Commonly used <quote>internal entities</quote>:
458 <emphasis>p-version</emphasis>: the <application>Privoxy</application>
459 version string, e.g. <quote>2.9.13</quote>.
462 <emphasis>p-status</emphasis>: the project status, either
463 <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
466 <emphasis>p-not-stable</emphasis>: use to conditionally include
467 text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
470 <emphasis>p-stable</emphasis>: just the opposite.
473 <emphasis>p-text</emphasis>: this doc is only generated as text.
480 There are others in various places that are defined for a specific
481 purpose. Read the source!
488 <!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
489 <!-- points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
491 <!-- ~~~~~ New section ~~~~~ -->
492 <sect1 id="coding"><title>Coding Guidelines</title>
494 <sect2 id="s1"><title>Introduction</title>
496 <para>This set of standards is designed to make our lives easier. It is
497 developed with the simple goal of helping us keep the "new and improved
498 <application>Privoxy</application>" consistent and reliable. Thus making
499 maintenance easier and increasing chances of success of the
502 <para>And that of course comes back to us as individuals. If we can
503 increase our development and product efficiencies then we can solve more
504 of the request for changes/improvements and in general feel good about
505 ourselves. ;-></para>
509 <sect2 id="s2"><title>Using Comments</title>
512 <sect3 id="s3"><title>Comment, Comment, Comment</title>
514 <para><emphasis>Explanation:</emphasis></para>
516 <para>Comment as much as possible without commenting the obvious.
517 For example do not comment "aVariable is equal to bVariable".
518 Instead explain why aVariable should be equal to the bVariable.
519 Just because a person can read code does not mean they will
520 understand why or what is being done. A reader may spend a lot
521 more time figuring out what is going on when a simple comment
522 or explanation would have prevented the extra research. Please
523 help your brother IJB'ers out!</para>
525 <para>The comments will also help justify the intent of the code.
526 If the comment describes something different than what the code
527 is doing then maybe a programming error is occurring.</para>
529 <para><emphasis>Example:</emphasis></para>
531 /* if page size greater than 1k ... */
532 if ( PageLength() > 1024 )
534 ... "block" the page up ...
537 /* if page size is small, send it in blocks */
538 if ( PageLength() > 1024 )
540 ... "block" the page up ...
543 This demonstrates 2 cases of "what not to do". The first is a
544 "syntax comment". The second is a comment that does not fit what
545 is actually being done.
551 <sect3 id="s4"><title>Use blocks for comments</title>
553 <para><emphasis>Explanation:</emphasis></para>
555 <para>Comments can help or they can clutter. They help when they
556 are differentiated from the code they describe. One line
557 comments do not offer effective separation between the comment
558 and the code. Block identifiers do, by surrounding the code
559 with a clear, definable pattern.</para>
561 <para><emphasis>Example:</emphasis></para>
563 /*********************************************************************
564 * This will stand out clearly in your code!
565 *********************************************************************/
566 if ( thisVariable == thatVariable )
568 DoSomethingVeryImportant();
572 /* unfortunately, this may not */
573 if ( thisVariable == thatVariable )
575 DoSomethingVeryImportant();
579 if ( thisVariable == thatVariable ) /* this may not either */
581 DoSomethingVeryImportant();
584 <para><emphasis>Exception:</emphasis></para>
586 <para>If you are trying to add a small logic comment and do not
587 wish to "disrubt" the flow of the code, feel free to use a 1
588 line comment which is NOT on the same line as the code.</para>
594 <sect3 id="s5"><title>Keep Comments on their own line</title>
596 <para><emphasis>Explanation:</emphasis></para>
598 <para>It goes back to the question of readability. If the comment
599 is on the same line as the code it will be harder to read than
600 the comment that is on its own line.</para>
602 <para>There are three exceptions to this rule, which should be
603 violated freely and often: during the definition of variables,
604 at the end of closing braces, when used to comment
607 <para><emphasis>Example:</emphasis></para>
609 /*********************************************************************
610 * This will stand out clearly in your code,
611 * But the second example won't.
612 *********************************************************************/
613 if ( thisVariable == thatVariable )
615 DoSomethingVeryImportant();
618 if ( thisVariable == thatVariable ) /*can you see me?*/
620 DoSomethingVeryImportant(); /*not easily*/
624 /*********************************************************************
625 * But, the encouraged exceptions:
626 *********************************************************************/
627 int urls_read = 0; /* # of urls read + rejected */
628 int urls_rejected = 0; /* # of urls rejected */
632 DoSomethingVeryImportant();
636 short DoSomethingVeryImportant(
637 short firstparam, /* represents something */
638 short nextparam /* represents something else */ )
642 } /* -END- DoSomethingVeryImportant */
647 <sect3 id="s6"><title>Comment each logical step</title>
649 <para><emphasis>Explanation:</emphasis></para>
651 <para>Logical steps should be commented to help others follow the
652 intent of the written code and comments will make the code more
655 <para>If you have 25 lines of code without a comment, you should
656 probably go back into it to see where you forgot to put
659 <para>Most "for", "while", "do", etc... loops _probably_ need a
660 comment. After all, these are usually major logic
667 <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
669 <para><emphasis>Explanation:</emphasis></para>
671 <para>A reader of the code should be able to look at the comments
672 just prior to the beginning of a function and discern the
673 reason for its existence and the consequences of using it. The
674 reader should not have to read through the code to determine if
675 a given function is safe for a desired use. The proper
676 information thoroughly presented at the introduction of a
677 function not only saves time for subsequent maintenance or
678 debugging, it more importantly aids in code reuse by allowing a
679 user to determine the safety and applicability of any function
680 for the problem at hand. As a result of such benefits, all
681 functions should contain the information presented in the
682 addendum section of this document.</para>
688 <sect3 id="s8"><title>Comment at the end of braces if the
689 content is more than one screen length</title>
691 <para><emphasis>Explanation:</emphasis></para>
693 <para>Each closing brace should be followed on the same line by a
694 comment that describes the origination of the brace if the
695 original brace is off of the screen, or otherwise far away from
696 the closing brace. This will simplify the debugging,
697 maintenance, and readability of the code.</para>
699 <para>As a suggestion , use the following flags to make the
700 comment and its brace more readable:</para>
702 <para>use following a closing brace: } /* -END- if() or while ()
705 <para><emphasis>Example:</emphasis></para>
709 DoSomethingVeryImportant();
710 ...some long list of commands...
711 } /* -END- if x is 1 */
717 DoSomethingVeryImportant();
718 ...some long list of commands...
719 } /* -END- if ( 1 == X ) */
725 <sect2 id="s9"><title>Naming Conventions</title>
729 <sect3 id="s10"><title>Variable Names</title>
731 <para><emphasis>Explanation:</emphasis></para>
733 <para>Use all lowercase, and seperate words via an underscore
734 ('_'). Do not start an identifier with an underscore. (ANSI C
735 reserves these for use by the compiler and system headers.) Do
736 not use identifiers which are reserved in ANSI C++. (E.g.
737 template, class, true, false, ...). This is in case we ever
738 decide to port Privoxy to C++.</para>
740 <para><emphasis>Example:</emphasis></para>
742 int ms_iis5_hack = 0;</programlisting>
744 <para><emphasis>Instead of:</emphasis></para>
748 int msiis5hack = 0; int msIis5Hack = 0;
756 <sect3 id="s11"><title>Function Names</title>
758 <para><emphasis>Explanation:</emphasis></para>
760 <para>Use all lowercase, and seperate words via an underscore
761 ('_'). Do not start an identifier with an underscore. (ANSI C
762 reserves these for use by the compiler and system headers.) Do
763 not use identifiers which are reserved in ANSI C++. (E.g.
764 template, class, true, false, ...). This is in case we ever
765 decide to port Privoxy to C++.</para>
767 <para><emphasis>Example:</emphasis></para>
769 int load_some_file( struct client_state *csp )</programlisting>
771 <para><emphasis>Instead of:</emphasis></para>
775 int loadsomefile( struct client_state *csp )
776 int loadSomeFile( struct client_state *csp )
784 <sect3 id="s12"><title>Header file prototypes</title>
786 <para><emphasis>Explanation:</emphasis></para>
788 <para>Use a descriptive parameter name in the function prototype
789 in header files. Use the same parameter name in the header file
790 that you use in the c file.</para>
792 <para><emphasis>Example:</emphasis></para>
794 (.h) extern int load_aclfile( struct client_state *csp );
795 (.c) int load_aclfile( struct client_state *csp )</programlisting>
797 <para><emphasis>Instead of:</emphasis>
799 (.h) extern int load_aclfile( struct client_state * ); or
800 (.h) extern int load_aclfile();
801 (.c) int load_aclfile( struct client_state *csp )
809 <sect3 id="s13"><title>Enumerations, and #defines</title>
811 <para><emphasis>Explanation:</emphasis></para>
813 <para>Use all capital letters, with underscores between words. Do
814 not start an identifier with an underscore. (ANSI C reserves
815 these for use by the compiler and system headers.)</para>
817 <para><emphasis>Example:</emphasis></para>
819 (enumeration) : enum Boolean { FALSE, TRUE };
820 (#define) : #define DEFAULT_SIZE 100;</programlisting>
822 <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
823 that toggle a feature in the preprocessor: FEATURE_>, where
824 > is a short (preferably 1 or 2 word) description.</para>
826 <para><emphasis>Example:</emphasis></para>
828 #define FEATURE_FORCE 1
831 #define FORCE_PREFIX blah
832 #endif /* def FEATURE_FORCE */
837 <sect3 id="s14"><title>Constants</title>
839 <para><emphasis>Explanation:</emphasis></para>
841 <para>Spell common words out entirely (do not remove vowels).</para>
843 <para>Use only widely-known domain acronyms and abbreviations.
844 Capitalize all letters of an acronym.</para>
846 <para>Use underscore (_) to separate adjacent acronyms and
847 abbreviations. Never terminate a name with an underscore.</para>
849 <para><emphasis>Example:</emphasis></para>
851 #define USE_IMAGE_LIST 1</programlisting>
853 <para><emphasis>Instead of:</emphasis></para>
857 #define USE_IMG_LST 1 or
858 #define _USE_IMAGE_LIST 1 or
859 #define USE_IMAGE_LIST_ 1 or
860 #define use_image_list 1 or
861 #define UseImageList 1
871 <sect2 id="s15"><title>Using Space</title>
875 <sect3 id="s16"><title>Put braces on a line by themselves.</title>
877 <para><emphasis>Explanation:</emphasis></para>
879 <para>The brace needs to be on a line all by itself, not at the
880 end of the statement. Curly braces should line up with the
881 construct that they're associated with. This practice makes it
882 easier to identify the opening and closing braces for a
885 <para><emphasis>Example:</emphasis></para>
892 <para><emphasis>Instead of:</emphasis></para>
894 <para>if ( this == that ) { ... }</para>
898 <para>if ( this == that ) { ... }</para>
900 <para><emphasis>Note:</emphasis> In the special case that the if-statement is
901 inside a loop, and it is trivial, i.e. it tests for a
902 condidtion that is obvious from the purpose of the block,
903 one-liners as above may optically preserve the loop structure
904 and make it easier to read.</para>
906 <para><emphasis>Status:</emphasis> developer-discrection.</para>
908 <para><emphasis>Example exception:</emphasis></para>
910 while ( more lines are read )
912 /* Please document what is/is not a comment line here */
913 if ( it's a comment ) continue;
915 do_something( line );
921 <sect3 id="s17"><title>ALL control statements should have a
924 <para><emphasis>Explanation:</emphasis></para>
926 <para>Using braces to make a block will make your code more
927 readable and less prone to error. All control statements should
928 have a block defined.</para>
930 <para><emphasis>Example:</emphasis></para>
938 <para><emphasis>Instead of:</emphasis></para>
940 <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
944 <para>if ( this == that ) DoSomething();</para>
946 <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
947 in a manner other than that which the developer desired (per
948 indentation). Using code braces would have prevented this
949 "feature". The "explanation" and "exception" from the point
950 above also applies.</para>
956 <sect3 id="s18"><title>Do not belabor/blow-up boolean
959 <para><emphasis>Example:</emphasis></para>
961 structure->flag = ( condition );</programlisting>
963 <para><emphasis>Instead of:</emphasis></para>
965 <para>if ( condition ) { structure->flag = 1; } else {
966 structure->flag = 0; }</para>
968 <para><emphasis>Note:</emphasis> The former is readable and consice. The later
969 is wordy and inefficient. Please assume that any developer new
970 to the project has at least a "good" knowledge of C/C++. (Hope
971 I do not offend by that last comment ... 8-)</para>
977 <sect3 id="s19"><title>Use white space freely because it is
980 <para><emphasis>Explanation:</emphasis></para>
982 <para>Make it readable. The notable exception to using white space
983 freely is listed in the next guideline.</para>
985 <para><emphasis>Example:</emphasis></para>
989 int anotherValue = 0;
990 int thisVariable = 0;
992 if ( thisVariable == thatVariable )
994 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
999 <sect3 id="s20"><title>Don't use white space around structure
1002 <para><emphasis>Explanation:</emphasis></para>
1004 <para>- structure pointer operator ( "->" ) - member operator (
1005 "." ) - functions and parentheses</para>
1007 <para>It is a general coding practice to put pointers, references,
1008 and function parentheses next to names. With spaces, the
1009 connection between the object and variable/function name is not
1012 <para><emphasis>Example:</emphasis></para>
1016 FunctionName();</programlisting>
1018 <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
1019 FunctionName ();</para>
1025 <sect3 id="s21"><title>Make the last brace of a function stand
1028 <para><emphasis>Example:</emphasis></para>
1030 int function1( ... )
1035 } /* -END- function1 */
1038 int function2( ... )
1040 } /* -END- function2 */
1043 <para><emphasis>Instead of:</emphasis></para>
1045 <para>int function1( ... ) { ...code... return( retCode ); } int
1046 function2( ... ) { }</para>
1048 <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
1049 lines afterwards. This makes the end of function standout to
1050 the most casual viewer. Although function comments help
1051 seperate functions, this is still a good coding practice. In
1052 fact, I follow these rules when using blocks in "for", "while",
1053 "do" loops, and long if {} statements too. After all whitespace
1056 <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
1057 lines. Enforced is the end of function comments.</para>
1063 <sect3 id="s22"><title>Use 3 character indentions</title>
1065 <para><emphasis>Explanation:</emphasis></para>
1067 <para>If some use 8 character TABs and some use 3 character TABs,
1068 the code can look *very* ragged. So use 3 character indentions
1069 only. If you like to use TABs, pass your code through a filter
1070 such as "expand -t3" before checking in your code.</para>
1072 <para><emphasis>Example:</emphasis></para>
1074 static const char * const url_code_map[256] =
1080 int function1( ... )
1084 return( ALWAYS_TRUE );
1088 return( HOW_DID_YOU_GET_HERE );
1091 return( NEVER_GETS_HERE );
1100 <sect2 id="s23"><title>Initializing</title>
1104 <sect3 id="s24"><title>Initialize all variables</title>
1106 <para><emphasis>Explanation:</emphasis></para>
1108 <para>Do not assume that the variables declared will not be used
1109 until after they have been assigned a value somewhere else in
1110 the code. Remove the chance of accidentally using an unassigned
1113 <para><emphasis>Example:</emphasis></para>
1117 struct *ptr = NULL;</programlisting>
1119 <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
1120 message says you are trying to access memory address 00000000
1121 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
1124 <para><emphasis>Status:</emphasis> developer-discrection if and only if the
1125 variable is assigned a value "shortly after" declaration.</para>
1131 <sect2 id="s25"><title>Functions</title>
1135 <sect3 id="s26"><title>Name functions that return a boolean as a
1138 <para><emphasis>Explanation:</emphasis></para>
1140 <para>Value should be phrased as a question that would logically
1141 be answered as a true or false statement</para>
1143 <para><emphasis>Example:</emphasis></para>
1145 ShouldWeBlockThis();
1152 <sect3 id="s27"><title>Always specify a return type for a
1155 <para><emphasis>Explanation:</emphasis></para>
1157 <para>The default return for a function is an int. To avoid
1158 ambiguity, create a return for a function when the return has a
1159 purpose, and create a void return type if the function does not
1160 need to return anything.</para>
1166 <sect3 id="s28"><title>Minimize function calls when iterating by
1167 using variables</title>
1169 <para><emphasis>Explanation:</emphasis></para>
1171 <para>It is easy to write the following code, and a clear argument
1172 can be made that the code is easy to understand:</para>
1174 <para><emphasis>Example:</emphasis></para>
1176 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1181 <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
1182 each and every iteration. This increases the overhead in the
1183 program, because the compiler has to look up the function each
1184 time, call it, and return a value. Depending on what occurs in
1185 the blockListLength() call, it might even be creating and
1186 destroying structures with each iteration, even though in each
1187 case it is comparing "cnt" to the same value, over and over.
1188 Remember too - even a call to blockListLength() is a function
1189 call, with the same overhead.</para>
1191 <para>Instead of using a function call during the iterations,
1192 assign the value to a variable, and evaluate using the
1195 <para><emphasis>Example:</emphasis></para>
1197 size_t len = blockListLength();
1199 for ( size_t cnt = 0; cnt < len; cnt ++ )
1204 <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
1205 change or could *potentially* change, then you must code the
1206 function call in the for/while loop.</para>
1212 <sect3 id="s29"><title>Pass and Return by Const Reference</title>
1214 <para><emphasis>Explanation:</emphasis></para>
1216 <para>This allows a developer to define a const pointer and call
1217 your function. If your function does not have the const
1218 keyword, we may not be able to use your function. Consider
1219 strcmp, if it were defined as: extern int strcmp( char *s1,
1222 <para>I could then not use it to compare argv's in main: int main(
1223 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1226 <para>Both these pointers are *const*! If the c runtime library
1227 maintainers do it, we should too.</para>
1233 <sect3 id="s30"><title>Pass and Return by Value</title>
1235 <para><emphasis>Explanation:</emphasis></para>
1237 <para>Most structures cannot fit onto a normal stack entry (i.e.
1238 they are not 4 bytes or less). Aka, a function declaration
1239 like: int load_aclfile( struct client_state csp )</para>
1241 <para>would not work. So, to be consistent, we should declare all
1242 prototypes with "pass by value": int load_aclfile( struct
1243 client_state *csp )</para>
1249 <sect3 id="s31"><title>Names of include files</title>
1251 <para><emphasis>Explanation:</emphasis></para>
1253 <para>Your include statements should contain the file name without
1254 a path. The path should be listed in the Makefile, using -I as
1255 processor directive to search the indicated paths. An exception
1256 to this would be for some proprietary software that utilizes a
1257 partial path to distinguish their header files from system or
1258 other header files.</para>
1260 <para><emphasis>Example:</emphasis></para>
1262 #include <iostream.h> /* This is not a local include */
1263 #include "config.h" /* This IS a local include */
1266 <para><emphasis>Exception:</emphasis></para>
1270 /* This is not a local include, but requires a path element. */
1271 #include <sys/fileName.h>
1275 <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
1276 without a _very_ good reason. This duplicates the #include
1277 "file.h" behaviour.</para>
1283 <sect3 id="s32"><title>Provide multiple inclusion
1286 <para><emphasis>Explanation:</emphasis></para>
1288 <para>Prevents compiler and linker errors resulting from
1289 redefinition of items.</para>
1291 <para>Wrap each header file with the following syntax to prevent
1292 multiple inclusions of the file. Of course, replace PROJECT_H
1293 with your file name, with "." Changed to "_", and make it
1296 <para><emphasis>Example:</emphasis></para>
1298 #ifndef PROJECT_H_INCLUDED
1299 #define PROJECT_H_INCLUDED
1301 #endif /* ndef PROJECT_H_INCLUDED */
1306 <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
1308 <para><emphasis>Explanation:</emphasis></para>
1310 <para>If our headers are included from C++, they must declare our
1311 functions as `extern "C"`. This has no cost in C, but increases
1312 the potential re-usability of our code.</para>
1314 <para><emphasis>Example:</emphasis></para>
1319 #endif /* def __cplusplus */
1321 ... function definitions here ...
1325 #endif /* def __cplusplus */
1330 <sect3 id="s34"><title>Where Possible, Use Forward Struct
1331 Declaration Instead of Includes</title>
1333 <para><emphasis>Explanation:</emphasis></para>
1335 <para>Useful in headers that include pointers to other struct's.
1336 Modifications to excess header files may cause needless
1339 <para><emphasis>Example:</emphasis></para>
1341 /*********************************************************************
1342 * We're avoiding an include statement here!
1343 *********************************************************************/
1345 extern file_list *xyz;</programlisting>
1347 <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
1348 pointer), then including the proper header file is necessary.
1349 If you only want to prototype a pointer, however, the header
1350 file is unneccessary.</para>
1352 <para><emphasis>Status:</emphasis> Use with discrection.</para>
1358 <sect2 id="s35"><title>General Coding Practices</title>
1362 <sect3 id="s36"><title>Turn on warnings</title>
1364 <para><emphasis>Explanation</emphasis></para>
1366 <para>Compiler warnings are meant to help you find bugs. You
1367 should turn on as many as possible. With GCC, the switch is
1368 "-Wall". Try and fix as many warnings as possible.</para>
1374 <sect3 id="s37"><title>Provide a default case for all switch
1377 <para><emphasis>Explanation:</emphasis></para>
1379 <para>What you think is guaranteed is never really guaranteed. The
1380 value that you don't think you need to check is the one that
1381 someday will be passed. So, to protect yourself from the
1382 unknown, always have a default step in a switch statement.</para>
1384 <para><emphasis>Example:</emphasis></para>
1386 switch( hash_string( cmd ) )
1388 case hash_actions_file :
1398 ... anomly code goes here ...
1399 continue; / break; / exit( 1 ); / etc ...
1401 } /* end switch( hash_string( cmd ) ) */</programlisting>
1403 <para><emphasis>Note:</emphasis> If you already have a default condition, you
1404 are obviously exempt from this point. Of note, most of the
1405 WIN32 code calls `DefWindowProc' after the switch statement.
1406 This API call *should* be included in a default statement.</para>
1408 <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1409 as a robust programming issue. The "anomly code goes here" may
1410 be no more than a print to the STDERR stream (as in
1411 load_config). Or it may really be an ABEND condition.</para>
1413 <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1419 <sect3 id="s38"><title>Try to avoid falling through cases in a
1420 switch statement.</title>
1422 <para><emphasis>Explanation:</emphasis></para>
1424 <para>In general, you will want to have a 'break' statement within
1425 each 'case' of a switch statement. This allows for the code to
1426 be more readable and understandable, and furthermore can
1427 prevent unwanted surprises if someone else later gets creative
1428 and moves the code around.</para>
1430 <para>The language allows you to plan the fall through from one
1431 case statement to another simply by omitting the break
1432 statement within the case statement. This feature does have
1433 benefits, but should only be used in rare cases. In general,
1434 use a break statement for each case statement.</para>
1436 <para>If you choose to allow fall through, you should comment both
1437 the fact of the fall through and reason why you felt it was
1444 <sect3 id="s39"><title>Use 'long' or 'short' Instead of
1447 <para><emphasis>Explanation:</emphasis></para>
1449 <para>On 32-bit platforms, int usually has the range of long. On
1450 16-bit platforms, int has the range of short.</para>
1452 <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
1453 projects (including X/GNU-Emacs), there are typedefs to int4,
1454 int8, int16, (or equivalence ... I forget the exact typedefs
1455 now). Should we add these to IJB now that we have a "configure"
1462 <sect3 id="s40"><title>Don't mix size_t and other types</title>
1464 <para><emphasis>Explanation:</emphasis></para>
1466 <para>The type of size_t varies across platforms. Do not make
1467 assumptions about whether it is signed or unsigned, or about
1468 how long it is. Do not compare a size_t against another
1469 variable of a different type (or even against a constant)
1470 without casting one of the values. Try to avoid using size_t if
1477 <sect3 id="s41"><title>Declare each variable and struct on its
1480 <para><emphasis>Explanation:</emphasis></para>
1482 <para>It can be tempting to declare a series of variables all on
1483 one line. Don't.</para>
1485 <para><emphasis>Example:</emphasis></para>
1489 long c = 0;</programlisting>
1491 <para><emphasis>Instead of:</emphasis></para>
1493 <para>long a, b, c;</para>
1495 <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1496 individual variables - easier to add new variables without
1497 messing up the original ones - when searching on a variable to
1498 find its type, there is less clutter to "visually"
1501 <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1502 variables or other trivial variables; feel free to declare them
1503 on 1 line. You should, although, provide a good comment on
1504 their functions.</para>
1506 <para><emphasis>Status:</emphasis> developer-discrection.</para>
1512 <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1514 <para><emphasis>Explanation:</emphasis></para>
1516 <para>Create a local stuct (on the stack) if the variable will
1517 live and die within the context of one function call.</para>
1519 <para>Only "malloc" a struct (on the heap) if the variable's life
1520 will extend beyond the context of one function call.</para>
1522 <para><emphasis>Example:</emphasis></para>
1524 If a function creates a struct and stores a pointer to it in a
1525 list, then it should definately be allocated via `malloc'.
1530 <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1531 Responsible for Ensuring 'free'</title>
1533 <para><emphasis>Explanation:</emphasis></para>
1535 <para>If you have to "malloc" an instance, you are responsible for
1536 insuring that the instance is `free'd, even if the deallocation
1537 event falls within some other programmer's code. You are also
1538 responsible for ensuring that deletion is timely (i.e. not too
1539 soon, not too late). This is known as "low-coupling" and is a
1540 "good thing (tm)". You may need to offer a
1541 free/unload/destuctor type function to accomodate this.</para>
1543 <para><emphasis>Example:</emphasis></para>
1545 int load_re_filterfile( struct client_state *csp ) { ... }
1546 static void unload_re_filterfile( void *f ) { ... }</programlisting>
1548 <para><emphasis>Exceptions:</emphasis></para>
1550 <para>The developer cannot be expected to provide `free'ing
1551 functions for C run-time library functions ... such as
1554 <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
1555 standard is for allocating and freeing data structures (complex
1562 <sect3 id="s44"><title>Add loaders to the `file_list' structure
1563 and in order</title>
1565 <para><emphasis>Explanation:</emphasis></para>
1567 <para>I have ordered all of the "blocker" file code to be in alpha
1568 order. It is easier to add/read new blockers when you expect a
1569 certain order.</para>
1571 <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1572 places by POPUP tests coming before PCRS tests. But since
1573 POPUPs can also be referred to as KILLPOPUPs, it is clear that
1574 it should come first.</para>
1580 <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1581 exitinst code, use FIXME</title>
1583 <para><emphasis>Explanation:</emphasis></para>
1585 <para>If you have enough confidence in new code or confidence in
1586 your changes, but are not *quite* sure of the reprocussions,
1589 <para>/* FIXME: this code has a logic error on platform XYZ, *
1590 attempthing to fix */ #ifdef PLATFORM ...changed code here...
1595 <para>/* FIXME: I think the original author really meant this...
1596 */ ...changed code here...</para>
1600 <para>/* FIXME: new code that *may* break something else... */
1601 ...new code here...</para>
1603 <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1604 be a "good thing (tm)", it will be easier to identify and
1605 include in the project (or conversly exclude from the
1613 <sect2 id="s46"><title>Addendum: Template for files and function
1614 comment blocks:</title>
1616 <para><emphasis>Example for file comments:</emphasis></para>
1618 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.23 2002/04/04 18:46:47 swa Exp $";
1619 /*********************************************************************
1621 * File : $S<!-- Break CVS Substitution -->ource$
1623 * Purpose : (Fill me in with a good description!)
1625 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1626 * Privoxy team. http://www.privoxy.org/
1628 * Based on the Internet Junkbuster originally written
1629 * by and Copyright (C) 1997 Anonymous Coders and
1630 * Junkbusters Corporation. http://www.junkbusters.com
1632 * This program is free software; you can redistribute it
1633 * and/or modify it under the terms of the GNU General
1634 * Public License as published by the Free Software
1635 * Foundation; either version 2 of the License, or (at
1636 * your option) any later version.
1638 * This program is distributed in the hope that it will
1639 * be useful, but WITHOUT ANY WARRANTY; without even the
1640 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1641 * PARTICULAR PURPOSE. See the GNU General Public
1642 * License for more details.
1644 * The GNU General Public License should be included with
1645 * this file. If not, you can view it at
1646 * http://www.gnu.org/copyleft/gpl.html
1647 * or write to the Free Software Foundation, Inc., 59
1648 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1651 * $L<!-- Break CVS Substitution -->og$
1653 *********************************************************************/
1658 ...necessary include files for us to do our work...
1660 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1663 <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1664 added to the "show-proxy-args" page. If this is a brand new
1665 creation by you, you are free to change the "Copyright" section
1666 to represent the rights you wish to maintain.</para>
1668 <para><emphasis>Note:</emphasis> The formfeed character that is present right
1669 after the comment flower box is handy for (X|GNU)Emacs users to
1670 skip the verbige and get to the heart of the code (via
1671 `forward-page' and `backward-page'). Please include it if you
1674 <para><emphasis>Example for file header comments:</emphasis></para>
1678 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.23 2002/04/04 18:46:47 swa Exp $"
1679 /*********************************************************************
1681 * File : $S<!-- Break CVS Substitution -->ource$
1683 * Purpose : (Fill me in with a good description!)
1685 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1686 * Privoxy team. http://www.privoxy.org/
1688 * Based on the Internet Junkbuster originally written
1689 * by and Copyright (C) 1997 Anonymous Coders and
1690 * Junkbusters Corporation. http://www.junkbusters.com
1692 * This program is free software; you can redistribute it
1693 * and/or modify it under the terms of the GNU General
1694 * Public License as published by the Free Software
1695 * Foundation; either version 2 of the License, or (at
1696 * your option) any later version.
1698 * This program is distributed in the hope that it will
1699 * be useful, but WITHOUT ANY WARRANTY; without even the
1700 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1701 * PARTICULAR PURPOSE. See the GNU General Public
1702 * License for more details.
1704 * The GNU General Public License should be included with
1705 * this file. If not, you can view it at
1706 * http://www.gnu.org/copyleft/gpl.html
1707 * or write to the Free Software Foundation, Inc., 59
1708 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1711 * $L<!-- Break CVS Substitution -->og$
1713 *********************************************************************/
1716 #include "project.h"
1722 ... function headers here ...
1725 /* Revision control strings from this header and associated .c file */
1726 extern const char FILENAME_rcs[];
1727 extern const char FILENAME_h_rcs[];
1734 #endif /* ndef _FILENAME_H */
1743 <para><emphasis>Example for function comments:</emphasis></para>
1745 /*********************************************************************
1747 * Function : FUNCTION_NAME
1749 * Description : (Fill me in with a good description!)
1752 * 1 : param1 = pointer to an important thing
1753 * 2 : x = pointer to something else
1755 * Returns : 0 => Ok, everything else is an error.
1757 *********************************************************************/
1758 int FUNCTION_NAME( void *param1, const char *x )
1766 <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1767 able to parse our code to create a "self-documenting" web
1774 <!-- ~~~~~ New section ~~~~~ -->
1775 <sect1 id="cvs"><title>Version Control Guidelines</title>
1776 <para>To be filled. note on cvs comments. Don't only comment what you did,
1777 but also why you did it!
1781 <!-- ~~~~~ New section ~~~~~ -->
1782 <sect1 id="testing"><title>Testing Guidelines</title>
1786 <!-- ~~~~~ New section ~~~~~ -->
1787 <sect2 id="testing-plan"><title>Testplan for releases</title>
1789 Explain release numbers. major, minor. developer releases. etc.
1791 <orderedlist numeration="arabic">
1793 Remove any existing rpm with rpm -e
1796 Remove any file that was left over. This includes (but is not limited to)
1798 <listitem><para>/var/log/privoxy</para></listitem>
1799 <listitem><para>/etc/privoxy</para></listitem>
1800 <listitem><para>/usr/sbin/privoxy</para></listitem>
1801 <listitem><para>/etc/init.d/privoxy</para></listitem>
1802 <listitem><para>/usr/doc/privoxy*</para></listitem>
1806 Install the rpm. Any error messages?
1808 <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1809 (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1810 autostart work?</para></listitem>
1811 <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1812 <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1817 <!-- ~~~~~ New section ~~~~~ -->
1818 <sect2 id="testing-report"><title>Test reports</title>
1820 Please submit test reports only with the <ulink url="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005">test form</ulink>
1821 at sourceforge. Three simple steps:
1824 <listitem><para>Select category: the distribution you test on.</para></listitem>
1825 <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
1826 <listitem><para>Fill the Summary and Detailed Description with something
1827 intelligent (keep it short and precise).</para>
1830 Do not mail to the mailinglist (we cannot keep track on issues there).
1836 <!-- ~~~~~ New section ~~~~~ -->
1837 <sect1 id="newrelease"><title>Releasing a new version</title>
1839 To minimize trouble with distribution contents, webpage
1840 errors and the like, we strongly encourage you
1841 to follow this section if you prepare a new release of
1842 code or new pages on the webserver.
1845 The following programs are required to follow this process:
1846 <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
1847 <filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
1850 <sect2 id="beforerelease">
1851 <title>Before the Release</title>
1853 The following <emphasis>must be done by one of the
1854 developers</emphasis> prior to each new release:
1860 Make sure that everybody who has worked on the code in the last
1861 couple of days has had a chance to yell <quote>no!</quote> in case
1862 they have pending changes/fixes in their pipelines.
1867 Increment the version number in <filename>configure.in</filename> in
1868 CVS. Also, the RPM release number in
1869 <filename>configure.in</filename>. Do NOT touch version information
1870 after export from CVS. <emphasis>All packages</emphasis> will use the
1871 version and release data from <filename>configure.in</filename>.
1872 Local files should not be changed, except prior to a CVS commit!!!
1873 This way we are all on the same page!
1878 If the default actionsfile has changed since last release,
1879 bump up its version info in this line:
1883 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1887 Then change the version info in doc/webserver/actions/index.php,
1888 line: '$required_actions_file_version = "A.B";'
1893 Tag all files in CVS with the version number with
1894 <quote><command>cvs tag v_X_Y_Z</command></quote> (where X = major, Y
1895 = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
1901 The first package uploaded should be the official
1902 <quote>tarball</quote> release. This is built with the
1903 <quote><command>make tarball-dist</command></quote> Makefile
1904 target, and then can be uploaded with
1905 <quote><command>make tarball-upload</command></quote> (see below).
1912 <sect2 id="newrelease-web"><title>Update the webserver</title>
1914 All files must be group-readable and group-writable (or no one else
1915 will be able to change them). To update the webserver, create any
1916 pages locally in the <filename>doc/webserver</filename> directory (or
1917 create new directories under <filename>doc/webserver</filename>), then do
1925 Note that <quote><command>make dok</command></quote>
1926 (or <quote><command>make redhat-dok</command></quote>) creates
1927 <filename>doc/webserver/user-manual</filename>,
1928 <filename>doc/webserver/developer-manual</filename>,
1929 <filename>doc/webserver/faq</filename> and
1930 <filename>doc/webserver/man-page</filename> automatically.
1933 Please do NOT use any other means of transferring files to the
1934 webserver. <quote><command>make webserver</command></quote> not only
1935 uploads, but will make sure that the appropriate permissions are
1936 preserved for shared group access.
1940 <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
1942 Ensure that you have the latest code version. Hence run:
1947 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1948 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1956 autoheader && autoconf && ./configure
1964 make suse-dist or make redhat-dist
1968 To upload the package to Sourceforge, simply issue
1972 make suse-upload or make redhat-upload
1976 Go to the displayed URL and release the file publicly on Sourceforge.
1980 <sect2 id="newrelease-os2"><title>OS/2</title>
1982 Ensure that you have the latest code version. Hence run:
1987 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1988 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1990 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
1994 You will need a mix of development tools.
1995 The main compilation takes place with IBM Visual Age C++.
1996 Some ancillary work takes place with GNU tools, available from
1997 various sources like hobbes.nmsu.edu.
1998 Specificially, you will need <filename>autoheader</filename>,
1999 <filename>autoconf</filename> and <filename>sh</filename> tools.
2000 The packaging takes place with WarpIN, available from various sources, including
2001 its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2004 Change directory to the <filename>os2setup</filename> directory.
2005 Edit the os2build.cmd file to set the final executable filename.
2008 installExeName='privoxyos2_setup_X.Y.Z.exe'
2010 Next, edit the <filename>IJB.wis</filename> file so the release number matches
2011 in the <filename>PACKAGEID</filename> section:
2013 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2015 You're now ready to build. Run:
2019 And in the <filename>./files</filename> directory you will have the
2020 WarpIN-installable executable.
2021 Upload this anonymously to
2022 <filename>uploads.sourceforge.net/incoming</filename>, create a release
2023 for it, and you're done.
2027 <sect2 id="newrelease-solaris"><title>Solaris</title>
2029 Login to Sourceforge's compilefarm via ssh
2033 ssh cf.sourceforge.net
2037 Choose the right operating system (not the Debian one). If you have
2038 downloaded <application>Privoxy</application> before,
2043 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2044 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2048 If not, please <ulink
2049 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2050 Privoxy via CVS first</ulink>. Run:
2054 autoheader && autoconf && ./configure
2066 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2067 solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2068 to manually upload the archive to Sourceforge's ftp server and release
2073 <sect2 id="newrelease-windows"><title>Windows</title>
2075 Ensure that you have the latest code version. Hence run
2080 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2081 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2089 autoheader && autoconf && ./configure
2097 <sect2 id="newrelease-debian"><title>Debian</title>
2099 Ensure that you have the latest code version. Hence run:
2104 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2105 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2113 autoheader && autoconf && ./configure
2121 <sect2 id="newrelease-macosx"><title>Mac OSX</title>
2123 Ensure that you have the latest code version. Hence run:
2128 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2129 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2131 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
2135 From the osxsetup directory, run:
2141 This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
2142 <filename>configure</filename> as well as <filename>make</filename>.
2143 Finally, it will copy over the necessary files to the ./osxsetup/files directory
2144 for further processing by <filename>PackageMaker</filename>.
2147 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
2148 name to match the release, and hit the "Create package" button.
2149 If you specify ./Privoxy.pkg as the output package name, you can then create
2150 the distributable zip file with the command:
2152 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2154 You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
2155 <filename>uploads.sourceforge.net/incoming</filename>,
2156 create a release for it, and you're done.
2160 <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
2162 Change the version number of <application>Privoxy</application> in the
2163 configure.in file. Run:
2165 autoheader && autoconf && ./configure
2170 Login to Sourceforge's compilefarm via ssh:
2174 ssh cf.sourceforge.net
2178 Choose the right operating system. If you have downloaded Privoxy
2184 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2185 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2189 If not, please <ulink
2190 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2191 Privoxy via CVS first</ulink>. Run:
2195 autoheader && autoconf && ./configure
2207 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2208 freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
2209 to manually upload the archive to Sourceforge's ftp server and release
2214 <sect2 id="newrelease-tarball"><title>Tarball</title>
2216 Ensure that you have the latest code version. Hence run:
2221 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2222 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2231 autoheader && autoconf && ./configure
2243 To upload the package to Sourceforge, simply issue
2251 Goto the displayed URL and release the file publicly on Sourceforge.
2255 <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
2257 Ensure that you have the latest code version. Hence run:
2262 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2263 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2271 autoheader && autoconf && ./configure
2279 <sect2 id="newrelease-amiga"><title>Amiga OS</title>
2281 Ensure that you have the latest code version. Hence run:
2286 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2287 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2295 autoheader && autoconf && ./configure
2303 <sect2 id="newrelease-aix"><title>AIX</title>
2305 Login to Sourceforge's compilefarm via ssh:
2309 ssh cf.sourceforge.net
2313 Choose the right operating system. If you have downloaded Privoxy
2319 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2320 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2324 If not, please <ulink
2325 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2326 Privoxy via CVS first</ulink>. Run:
2330 autoheader && autoconf && ./configure
2342 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2343 aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
2344 to manually upload the archive to Sourceforge's ftp server and release
2351 <!-- ~~~~~ New section ~~~~~ -->
2352 <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
2353 <!-- Include contacting.sgml -->
2355 <!-- end contacting -->
2358 <!-- ~~~~~ New section ~~~~~ -->
2359 <sect1 id="copyright"><title>Copyright and History</title>
2361 <sect2><title>Copyright</title>
2362 <!-- Include copyright.sgml -->
2367 <sect2><title>History</title>
2368 <!-- Include history.sgml -->
2375 <!-- ~~~~~ New section ~~~~~ -->
2376 <sect1 id="seealso"><title>See also</title>
2377 <!-- Include seealso.sgml -->
2385 This program is free software; you can redistribute it
2386 and/or modify it under the terms of the GNU General
2387 Public License as published by the Free Software
2388 Foundation; either version 2 of the License, or (at
2389 your option) any later version.
2391 This program is distributed in the hope that it will
2392 be useful, but WITHOUT ANY WARRANTY; without even the
2393 implied warranty of MERCHANTABILITY or FITNESS FOR A
2394 PARTICULAR PURPOSE. See the GNU General Public
2395 License for more details.
2397 The GNU General Public License should be included with
2398 this file. If not, you can view it at
2399 http://www.gnu.org/copyleft/gpl.html
2400 or write to the Free Software Foundation, Inc., 59
2401 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2403 $Log: developer-manual.sgml,v $
2404 Revision 1.23 2002/04/04 18:46:47 swa
2405 consistent look. reuse of copyright, history et. al.
2407 Revision 1.22 2002/04/04 17:27:56 swa
2408 more single file to be included at multiple points. make maintaining easier
2410 Revision 1.21 2002/04/04 06:48:37 hal9
2411 Structural changes to allow for conditional inclusion/exclusion of content
2412 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
2413 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2414 eventually be set by Makefile.
2415 More boilerplate text for use across multiple docs.
2417 Revision 1.20 2002/04/04 03:28:27 david__schmidt
2420 Revision 1.19 2002/04/03 15:09:42 david__schmidt
2421 Add OS/2 build section
2423 Revision 1.18 2002/04/03 03:51:48 hal9
2426 Revision 1.17 2002/04/03 01:21:17 hal9
2427 Implementing Andreas's suggestions for Release sections.
2429 Revision 1.16 2002/03/31 23:04:40 hal9
2430 Fleshed out the doc section, and added something for an intro so it was not
2433 Revision 1.15 2002/03/30 22:29:47 swa
2436 Revision 1.14 2002/03/30 19:04:08 swa
2437 people release differently. no good.
2438 I want to make parts of the docs only.
2440 Revision 1.13 2002/03/27 01:16:41 hal9
2443 Revision 1.12 2002/03/27 01:02:51 hal9
2444 Touch up on name change...
2446 Revision 1.11 2002/03/26 22:29:55 swa
2447 we have a new homepage!
2449 Revision 1.10 2002/03/24 12:33:01 swa
2452 Revision 1.9 2002/03/24 11:01:05 swa
2455 Revision 1.8 2002/03/23 15:13:11 swa
2456 renamed every reference to the old name with foobar.
2457 fixed "application foobar application" tag, fixed
2458 "the foobar" with "foobar". left junkbustser in cvs
2459 comments and remarks to history untouched.
2461 Revision 1.7 2002/03/11 13:13:27 swa
2462 correct feedback channels
2464 Revision 1.6 2002/02/24 14:25:06 jongfoster
2465 Formatting changes. Now changing the doctype to DocBook XML 4.1
2466 will work - no other changes are needed.
2468 Revision 1.5 2001/10/31 18:16:51 swa
2469 documentation added: howto generate docs in text and html
2470 format, howto move stuff to the webserver.
2472 Revision 1.4 2001/09/23 10:13:48 swa
2473 upload process established. run make webserver and
2474 the documentation is moved to the webserver. documents
2475 are now linked correctly.
2477 Revision 1.3 2001/09/13 15:27:40 swa
2480 Revision 1.2 2001/09/13 15:20:17 swa
2481 merged standards into developer manual
2483 Revision 1.1 2001/09/12 15:36:41 swa
2484 source files for junkbuster documentation
2486 Revision 1.3 2001/09/10 17:43:59 swa
2487 first proposal of a structure.
2489 Revision 1.2 2001/06/13 14:28:31 swa
2490 docs should have an author.
2492 Revision 1.1 2001/06/13 14:20:37 swa
2493 first import of project's documentation for the webserver.