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">
13 <!entity % p-stable "IGNORE">
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.25 2002/04/06 05:07:28 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.25 2002/04/06 05:07:28 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>, <citetitle>AUTHORS</citetitle>
169 <citetitle>privoxy.1</citetitle> (man page)
170 files are also now maintained
171 as SGML. The finished files are all in the top-level source
172 directory are generated files! Also, <filename>index.html</filename>,
173 the <application>Privoxy</application> home page, is maintained
174 as sgml. <emphasis>DO NOT edit these
175 directly</emphasis>. Edit the SGML source, or contact someone
176 involved in the documentation (at present Stefan and Hal).
179 Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as
180 plain text files in the toplevel source directory. At least for the
184 Packagers are encouraged to include this documentation. For those without
185 the ability to build the docs locally, text versions of each are kept in
186 CVS. HTML versions are also now being kept in CVS under
187 <filename>doc/webserver/*</filename>.
190 Formal documents are built with the Makefile targets of
191 <computeroutput>make dok</computeroutput>, or alternately
192 <computeroutput>make redhat-dok</computeroutput>. If you have problems,
193 try both. The build process uses the document SGML sources in
194 <computeroutput>doc/source/*</computeroutput> to update all text files in
195 <computeroutput>doc/text/</computeroutput> and to update all HTML
196 documents in <computeroutput>doc/webserver/</computeroutput>.
199 Documentation writers should please make sure documents build
200 successfully before committing to CVS.
203 How do you update the webserver (i.e. the pages on privoxy.org)?
205 <orderedlist numeration="arabic">
207 First, build the docs by running <computeroutput>make
208 dok</computeroutput> (or alternately <computeroutput>make
209 redhat-dok</computeroutput>).
212 Run <computeroutput>make webserver</computeroutput> which copies all
213 files from <computeroutput>doc/webserver</computeroutput> to the
214 sourceforge webserver via scp.
220 <!-- ~~~~~ New section ~~~~~ -->
222 <title>Quickstart to Docbook and SGML</title>
224 If you are not familiar with SGML, it is a markup language similar to HTML.
225 In fact, HTML is an SGML application. Both use <quote>tags</quote>
226 to format text and other content. SGML tags are much more varied,
227 and flexible, but do much of the same kinds of things. The tags,
228 or <quote>elements</quote>, are definable in SGML. There is no
229 set <quote>standards</quote>. Since we are using
230 <application>Docbook</application>, our tags are those that are
231 defined by <application>Docbook</application>. Much of how the
232 finish document is rendered is determined by the <quote>stylesheets</quote>.
233 The stylesheets determine how each tag gets translated to HTML, or
238 Tags in SGML need to be always <quote>closed</quote>. If not, you
239 will likely generate errors. Example:
240 <literal><title>My Title</title></literal>. They are
241 also case-insensitive, but we strongly suggest using all lower
242 case. This keeps compatibility with [Docbook] <application>XML</application>.
246 Our documents use <quote>sections</quote> for the most part. Sections
247 will be processed into HTML headers (e.g. <literal>h1</literal> for
248 <literal>sect1</literal>). The <application>Docbook</application> stylesheets
249 will use these to also generate the Table of Contents for each doc. Our
250 TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
251 <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
252 entries, but <literal>sect4</literal> will not. Each section requires
253 a <literal><title></literal> element, and at least one
254 <literal><para></literal>. There is a limit of five section
255 levels in Docbook, but generally three should be sufficient for our
260 Some common elements that you likely will use:
265 <emphasis><para></para></emphasis>, paragraph delimiter. Most
266 text needs to be within paragraph elements.
269 <emphasis><emphasis></emphasis></emphasis>, stylesheets make this
273 <emphasis><filename></filename></emphasis>, files and directories.
276 <emphasis><command></command></emphasis>, command examples.
279 <emphasis><literallayout></literllayout></emphasis>, like
280 <literal><pre></literal>, more or less.
283 <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
286 <emphasis><listitem></listitem></emphasis>, member of the above.
289 <emphasis><screen></screen></emphasis>, screen output, implies
290 <literal><literallayout></literal>.
293 <emphasis><ulink url="example.com"></ulink></emphasis>, like
294 HTML <literal><a></literal> tag.
297 <emphasis><quote></quote></emphasis>, for, doh, quoting text.
302 Look at any of the existing docs for examples of all these and more.
308 <!-- ~~~~~ New section ~~~~~ -->
309 <sect2 id="docstyle">
310 <title><application>Privoxy</application> Documentation Style</title>
312 It will be easier if everyone follows a similar writing style. This
313 just makes it easier to read what someone else has written if it
314 is all done in a similar fashion.
323 All tags should be lower case.
328 Tags delimiting a <emphasis>block</emphasis> of text should be on their
335 Tags marking individual words, or few words, should be in-line:
337 Just to <emphasis>emphasize</emphasis>, some text goes here.
343 Tags should be nested and step indented like (except in-line tags):
349 Some text goes here in our list example.
352 </itemizedlist>
355 This makes it easier to find the text amongst the tags ;-)
360 Use white space to separate logical divisions within a document,
361 like between sections. Running everything together consistently
362 makes it harder to read and work on.
367 Do not hesitate to make comments. Comments can either use the
368 <comment> element, or the <!-- --> style comment
369 familiar from HTML. (Note in Docbook v4.x <comment> is
370 replaced by <remark>.)
375 We have an international audience. Refrain from slang, or English
376 idiosyncrasies (too many to list :).
381 Try to keep overall line lengths in source files to 80 characters or less
382 for obvious reasons. This is not always possible, with lenghty URLs for
388 Our documents are available in differing formats. Right now, they
389 are just plain text, and HTML, but PDF, and others is always a
390 future possibility. Be careful with URLs (<ulink>), and avoid
394 My favorite site is <ulink url="http://example.com">here</ulink>.
397 This will render as <quote>My favorite site is here</quote>, which is
398 not real helpful in a text doc. Better like this:
401 My favorite site is <ulink url="http://example.com">example.com</ulink>.
406 All documents should be spell checked occasionally.
407 <application>aspell</application> can check SGML with the
408 <literal>-H</literal> option. (<application>ispell</application> I think
419 <!-- ~~~~~ New section ~~~~~ -->
421 <sect2><title>Privoxy Custom Entities</title>
423 <application>Privoxy</application> documentation is using
424 a number of customized <quote>entities</quote> to facilitate
425 documentation maintenance.
428 We are using a set of <quote>boilerplate</quote> files with generic text,
429 that is used by multiple docs. This way we can write something once, and use
430 it repeatedly without having to re-write the same content over and over again.
431 If editing such a file, keep in mind that it should be
432 <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
433 contexts without additional modifications.
436 We are also using what <application>Docbook</application> calls
437 <quote>internal entities</quote>. These are like variables in
438 programming. Well, sort of. For instance, we have the
439 <literal>p-version</literal> entity that contains the current
440 <application>Privoxy</application> version string. You are strongly
441 encouraged to use these where possible. Some of these obviously
442 require re-setting with each release. A sampling of custom entities are
443 listed below. See any of the main docs for examples.
450 Re-cyclable <quote>boilerplate</quote> text entities are defined like:
453 <literal><!entity supported SYSTEM "supported.sgml"></literal>
456 In this example, the contents of the file,
457 <filename>supported.sgml</filename> is available for inclusion anywhere
458 in the doc. To make this happen, just reference the now defined
459 entity: <literal>&supported;</literal> (starts with an ampersand
460 and ends with a semi-colon), and the contents will be dumped into
461 the finished doc at that point.
466 Commonly used <quote>internal entities</quote>:
470 <emphasis>p-version</emphasis>: the <application>Privoxy</application>
471 version string, e.g. <quote>2.9.13</quote>.
474 <emphasis>p-status</emphasis>: the project status, either
475 <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
478 <emphasis>p-not-stable</emphasis>: use to conditionally include
479 text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
482 <emphasis>p-stable</emphasis>: just the opposite.
485 <emphasis>p-text</emphasis>: this doc is only generated as text.
492 There are others in various places that are defined for a specific
493 purpose. Read the source!
500 <!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
501 <!-- points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
503 <!-- ~~~~~ New section ~~~~~ -->
504 <sect1 id="coding"><title>Coding Guidelines</title>
506 <sect2 id="s1"><title>Introduction</title>
508 <para>This set of standards is designed to make our lives easier. It is
509 developed with the simple goal of helping us keep the "new and improved
510 <application>Privoxy</application>" consistent and reliable. Thus making
511 maintenance easier and increasing chances of success of the
514 <para>And that of course comes back to us as individuals. If we can
515 increase our development and product efficiencies then we can solve more
516 of the request for changes/improvements and in general feel good about
517 ourselves. ;-></para>
521 <sect2 id="s2"><title>Using Comments</title>
524 <sect3 id="s3"><title>Comment, Comment, Comment</title>
526 <para><emphasis>Explanation:</emphasis></para>
528 <para>Comment as much as possible without commenting the obvious.
529 For example do not comment "aVariable is equal to bVariable".
530 Instead explain why aVariable should be equal to the bVariable.
531 Just because a person can read code does not mean they will
532 understand why or what is being done. A reader may spend a lot
533 more time figuring out what is going on when a simple comment
534 or explanation would have prevented the extra research. Please
535 help your brother IJB'ers out!</para>
537 <para>The comments will also help justify the intent of the code.
538 If the comment describes something different than what the code
539 is doing then maybe a programming error is occurring.</para>
541 <para><emphasis>Example:</emphasis></para>
543 /* if page size greater than 1k ... */
544 if ( PageLength() > 1024 )
546 ... "block" the page up ...
549 /* if page size is small, send it in blocks */
550 if ( PageLength() > 1024 )
552 ... "block" the page up ...
555 This demonstrates 2 cases of "what not to do". The first is a
556 "syntax comment". The second is a comment that does not fit what
557 is actually being done.
563 <sect3 id="s4"><title>Use blocks for comments</title>
565 <para><emphasis>Explanation:</emphasis></para>
567 <para>Comments can help or they can clutter. They help when they
568 are differentiated from the code they describe. One line
569 comments do not offer effective separation between the comment
570 and the code. Block identifiers do, by surrounding the code
571 with a clear, definable pattern.</para>
573 <para><emphasis>Example:</emphasis></para>
575 /*********************************************************************
576 * This will stand out clearly in your code!
577 *********************************************************************/
578 if ( thisVariable == thatVariable )
580 DoSomethingVeryImportant();
584 /* unfortunately, this may not */
585 if ( thisVariable == thatVariable )
587 DoSomethingVeryImportant();
591 if ( thisVariable == thatVariable ) /* this may not either */
593 DoSomethingVeryImportant();
596 <para><emphasis>Exception:</emphasis></para>
598 <para>If you are trying to add a small logic comment and do not
599 wish to "disrubt" the flow of the code, feel free to use a 1
600 line comment which is NOT on the same line as the code.</para>
606 <sect3 id="s5"><title>Keep Comments on their own line</title>
608 <para><emphasis>Explanation:</emphasis></para>
610 <para>It goes back to the question of readability. If the comment
611 is on the same line as the code it will be harder to read than
612 the comment that is on its own line.</para>
614 <para>There are three exceptions to this rule, which should be
615 violated freely and often: during the definition of variables,
616 at the end of closing braces, when used to comment
619 <para><emphasis>Example:</emphasis></para>
621 /*********************************************************************
622 * This will stand out clearly in your code,
623 * But the second example won't.
624 *********************************************************************/
625 if ( thisVariable == thatVariable )
627 DoSomethingVeryImportant();
630 if ( thisVariable == thatVariable ) /*can you see me?*/
632 DoSomethingVeryImportant(); /*not easily*/
636 /*********************************************************************
637 * But, the encouraged exceptions:
638 *********************************************************************/
639 int urls_read = 0; /* # of urls read + rejected */
640 int urls_rejected = 0; /* # of urls rejected */
644 DoSomethingVeryImportant();
648 short DoSomethingVeryImportant(
649 short firstparam, /* represents something */
650 short nextparam /* represents something else */ )
654 } /* -END- DoSomethingVeryImportant */
659 <sect3 id="s6"><title>Comment each logical step</title>
661 <para><emphasis>Explanation:</emphasis></para>
663 <para>Logical steps should be commented to help others follow the
664 intent of the written code and comments will make the code more
667 <para>If you have 25 lines of code without a comment, you should
668 probably go back into it to see where you forgot to put
671 <para>Most "for", "while", "do", etc... loops _probably_ need a
672 comment. After all, these are usually major logic
679 <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
681 <para><emphasis>Explanation:</emphasis></para>
683 <para>A reader of the code should be able to look at the comments
684 just prior to the beginning of a function and discern the
685 reason for its existence and the consequences of using it. The
686 reader should not have to read through the code to determine if
687 a given function is safe for a desired use. The proper
688 information thoroughly presented at the introduction of a
689 function not only saves time for subsequent maintenance or
690 debugging, it more importantly aids in code reuse by allowing a
691 user to determine the safety and applicability of any function
692 for the problem at hand. As a result of such benefits, all
693 functions should contain the information presented in the
694 addendum section of this document.</para>
700 <sect3 id="s8"><title>Comment at the end of braces if the
701 content is more than one screen length</title>
703 <para><emphasis>Explanation:</emphasis></para>
705 <para>Each closing brace should be followed on the same line by a
706 comment that describes the origination of the brace if the
707 original brace is off of the screen, or otherwise far away from
708 the closing brace. This will simplify the debugging,
709 maintenance, and readability of the code.</para>
711 <para>As a suggestion , use the following flags to make the
712 comment and its brace more readable:</para>
714 <para>use following a closing brace: } /* -END- if() or while ()
717 <para><emphasis>Example:</emphasis></para>
721 DoSomethingVeryImportant();
722 ...some long list of commands...
723 } /* -END- if x is 1 */
729 DoSomethingVeryImportant();
730 ...some long list of commands...
731 } /* -END- if ( 1 == X ) */
737 <sect2 id="s9"><title>Naming Conventions</title>
741 <sect3 id="s10"><title>Variable Names</title>
743 <para><emphasis>Explanation:</emphasis></para>
745 <para>Use all lowercase, and seperate words via an underscore
746 ('_'). Do not start an identifier with an underscore. (ANSI C
747 reserves these for use by the compiler and system headers.) Do
748 not use identifiers which are reserved in ANSI C++. (E.g.
749 template, class, true, false, ...). This is in case we ever
750 decide to port Privoxy to C++.</para>
752 <para><emphasis>Example:</emphasis></para>
754 int ms_iis5_hack = 0;</programlisting>
756 <para><emphasis>Instead of:</emphasis></para>
760 int msiis5hack = 0; int msIis5Hack = 0;
768 <sect3 id="s11"><title>Function Names</title>
770 <para><emphasis>Explanation:</emphasis></para>
772 <para>Use all lowercase, and seperate words via an underscore
773 ('_'). Do not start an identifier with an underscore. (ANSI C
774 reserves these for use by the compiler and system headers.) Do
775 not use identifiers which are reserved in ANSI C++. (E.g.
776 template, class, true, false, ...). This is in case we ever
777 decide to port Privoxy to C++.</para>
779 <para><emphasis>Example:</emphasis></para>
781 int load_some_file( struct client_state *csp )</programlisting>
783 <para><emphasis>Instead of:</emphasis></para>
787 int loadsomefile( struct client_state *csp )
788 int loadSomeFile( struct client_state *csp )
796 <sect3 id="s12"><title>Header file prototypes</title>
798 <para><emphasis>Explanation:</emphasis></para>
800 <para>Use a descriptive parameter name in the function prototype
801 in header files. Use the same parameter name in the header file
802 that you use in the c file.</para>
804 <para><emphasis>Example:</emphasis></para>
806 (.h) extern int load_aclfile( struct client_state *csp );
807 (.c) int load_aclfile( struct client_state *csp )</programlisting>
809 <para><emphasis>Instead of:</emphasis>
811 (.h) extern int load_aclfile( struct client_state * ); or
812 (.h) extern int load_aclfile();
813 (.c) int load_aclfile( struct client_state *csp )
821 <sect3 id="s13"><title>Enumerations, and #defines</title>
823 <para><emphasis>Explanation:</emphasis></para>
825 <para>Use all capital letters, with underscores between words. Do
826 not start an identifier with an underscore. (ANSI C reserves
827 these for use by the compiler and system headers.)</para>
829 <para><emphasis>Example:</emphasis></para>
831 (enumeration) : enum Boolean { FALSE, TRUE };
832 (#define) : #define DEFAULT_SIZE 100;</programlisting>
834 <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
835 that toggle a feature in the preprocessor: FEATURE_>, where
836 > is a short (preferably 1 or 2 word) description.</para>
838 <para><emphasis>Example:</emphasis></para>
840 #define FEATURE_FORCE 1
843 #define FORCE_PREFIX blah
844 #endif /* def FEATURE_FORCE */
849 <sect3 id="s14"><title>Constants</title>
851 <para><emphasis>Explanation:</emphasis></para>
853 <para>Spell common words out entirely (do not remove vowels).</para>
855 <para>Use only widely-known domain acronyms and abbreviations.
856 Capitalize all letters of an acronym.</para>
858 <para>Use underscore (_) to separate adjacent acronyms and
859 abbreviations. Never terminate a name with an underscore.</para>
861 <para><emphasis>Example:</emphasis></para>
863 #define USE_IMAGE_LIST 1</programlisting>
865 <para><emphasis>Instead of:</emphasis></para>
869 #define USE_IMG_LST 1 or
870 #define _USE_IMAGE_LIST 1 or
871 #define USE_IMAGE_LIST_ 1 or
872 #define use_image_list 1 or
873 #define UseImageList 1
883 <sect2 id="s15"><title>Using Space</title>
887 <sect3 id="s16"><title>Put braces on a line by themselves.</title>
889 <para><emphasis>Explanation:</emphasis></para>
891 <para>The brace needs to be on a line all by itself, not at the
892 end of the statement. Curly braces should line up with the
893 construct that they're associated with. This practice makes it
894 easier to identify the opening and closing braces for a
897 <para><emphasis>Example:</emphasis></para>
904 <para><emphasis>Instead of:</emphasis></para>
906 <para>if ( this == that ) { ... }</para>
910 <para>if ( this == that ) { ... }</para>
912 <para><emphasis>Note:</emphasis> In the special case that the if-statement is
913 inside a loop, and it is trivial, i.e. it tests for a
914 condidtion that is obvious from the purpose of the block,
915 one-liners as above may optically preserve the loop structure
916 and make it easier to read.</para>
918 <para><emphasis>Status:</emphasis> developer-discrection.</para>
920 <para><emphasis>Example exception:</emphasis></para>
922 while ( more lines are read )
924 /* Please document what is/is not a comment line here */
925 if ( it's a comment ) continue;
927 do_something( line );
933 <sect3 id="s17"><title>ALL control statements should have a
936 <para><emphasis>Explanation:</emphasis></para>
938 <para>Using braces to make a block will make your code more
939 readable and less prone to error. All control statements should
940 have a block defined.</para>
942 <para><emphasis>Example:</emphasis></para>
950 <para><emphasis>Instead of:</emphasis></para>
952 <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
956 <para>if ( this == that ) DoSomething();</para>
958 <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
959 in a manner other than that which the developer desired (per
960 indentation). Using code braces would have prevented this
961 "feature". The "explanation" and "exception" from the point
962 above also applies.</para>
968 <sect3 id="s18"><title>Do not belabor/blow-up boolean
971 <para><emphasis>Example:</emphasis></para>
973 structure->flag = ( condition );</programlisting>
975 <para><emphasis>Instead of:</emphasis></para>
977 <para>if ( condition ) { structure->flag = 1; } else {
978 structure->flag = 0; }</para>
980 <para><emphasis>Note:</emphasis> The former is readable and consice. The later
981 is wordy and inefficient. Please assume that any developer new
982 to the project has at least a "good" knowledge of C/C++. (Hope
983 I do not offend by that last comment ... 8-)</para>
989 <sect3 id="s19"><title>Use white space freely because it is
992 <para><emphasis>Explanation:</emphasis></para>
994 <para>Make it readable. The notable exception to using white space
995 freely is listed in the next guideline.</para>
997 <para><emphasis>Example:</emphasis></para>
1001 int anotherValue = 0;
1002 int thisVariable = 0;
1004 if ( thisVariable == thatVariable )
1006 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
1011 <sect3 id="s20"><title>Don't use white space around structure
1014 <para><emphasis>Explanation:</emphasis></para>
1016 <para>- structure pointer operator ( "->" ) - member operator (
1017 "." ) - functions and parentheses</para>
1019 <para>It is a general coding practice to put pointers, references,
1020 and function parentheses next to names. With spaces, the
1021 connection between the object and variable/function name is not
1024 <para><emphasis>Example:</emphasis></para>
1028 FunctionName();</programlisting>
1030 <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
1031 FunctionName ();</para>
1037 <sect3 id="s21"><title>Make the last brace of a function stand
1040 <para><emphasis>Example:</emphasis></para>
1042 int function1( ... )
1047 } /* -END- function1 */
1050 int function2( ... )
1052 } /* -END- function2 */
1055 <para><emphasis>Instead of:</emphasis></para>
1057 <para>int function1( ... ) { ...code... return( retCode ); } int
1058 function2( ... ) { }</para>
1060 <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
1061 lines afterwards. This makes the end of function standout to
1062 the most casual viewer. Although function comments help
1063 seperate functions, this is still a good coding practice. In
1064 fact, I follow these rules when using blocks in "for", "while",
1065 "do" loops, and long if {} statements too. After all whitespace
1068 <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
1069 lines. Enforced is the end of function comments.</para>
1075 <sect3 id="s22"><title>Use 3 character indentions</title>
1077 <para><emphasis>Explanation:</emphasis></para>
1079 <para>If some use 8 character TABs and some use 3 character TABs,
1080 the code can look *very* ragged. So use 3 character indentions
1081 only. If you like to use TABs, pass your code through a filter
1082 such as "expand -t3" before checking in your code.</para>
1084 <para><emphasis>Example:</emphasis></para>
1086 static const char * const url_code_map[256] =
1092 int function1( ... )
1096 return( ALWAYS_TRUE );
1100 return( HOW_DID_YOU_GET_HERE );
1103 return( NEVER_GETS_HERE );
1112 <sect2 id="s23"><title>Initializing</title>
1116 <sect3 id="s24"><title>Initialize all variables</title>
1118 <para><emphasis>Explanation:</emphasis></para>
1120 <para>Do not assume that the variables declared will not be used
1121 until after they have been assigned a value somewhere else in
1122 the code. Remove the chance of accidentally using an unassigned
1125 <para><emphasis>Example:</emphasis></para>
1129 struct *ptr = NULL;</programlisting>
1131 <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
1132 message says you are trying to access memory address 00000000
1133 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
1136 <para><emphasis>Status:</emphasis> developer-discrection if and only if the
1137 variable is assigned a value "shortly after" declaration.</para>
1143 <sect2 id="s25"><title>Functions</title>
1147 <sect3 id="s26"><title>Name functions that return a boolean as a
1150 <para><emphasis>Explanation:</emphasis></para>
1152 <para>Value should be phrased as a question that would logically
1153 be answered as a true or false statement</para>
1155 <para><emphasis>Example:</emphasis></para>
1157 ShouldWeBlockThis();
1164 <sect3 id="s27"><title>Always specify a return type for a
1167 <para><emphasis>Explanation:</emphasis></para>
1169 <para>The default return for a function is an int. To avoid
1170 ambiguity, create a return for a function when the return has a
1171 purpose, and create a void return type if the function does not
1172 need to return anything.</para>
1178 <sect3 id="s28"><title>Minimize function calls when iterating by
1179 using variables</title>
1181 <para><emphasis>Explanation:</emphasis></para>
1183 <para>It is easy to write the following code, and a clear argument
1184 can be made that the code is easy to understand:</para>
1186 <para><emphasis>Example:</emphasis></para>
1188 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1193 <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
1194 each and every iteration. This increases the overhead in the
1195 program, because the compiler has to look up the function each
1196 time, call it, and return a value. Depending on what occurs in
1197 the blockListLength() call, it might even be creating and
1198 destroying structures with each iteration, even though in each
1199 case it is comparing "cnt" to the same value, over and over.
1200 Remember too - even a call to blockListLength() is a function
1201 call, with the same overhead.</para>
1203 <para>Instead of using a function call during the iterations,
1204 assign the value to a variable, and evaluate using the
1207 <para><emphasis>Example:</emphasis></para>
1209 size_t len = blockListLength();
1211 for ( size_t cnt = 0; cnt < len; cnt ++ )
1216 <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
1217 change or could *potentially* change, then you must code the
1218 function call in the for/while loop.</para>
1224 <sect3 id="s29"><title>Pass and Return by Const Reference</title>
1226 <para><emphasis>Explanation:</emphasis></para>
1228 <para>This allows a developer to define a const pointer and call
1229 your function. If your function does not have the const
1230 keyword, we may not be able to use your function. Consider
1231 strcmp, if it were defined as: extern int strcmp( char *s1,
1234 <para>I could then not use it to compare argv's in main: int main(
1235 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1238 <para>Both these pointers are *const*! If the c runtime library
1239 maintainers do it, we should too.</para>
1245 <sect3 id="s30"><title>Pass and Return by Value</title>
1247 <para><emphasis>Explanation:</emphasis></para>
1249 <para>Most structures cannot fit onto a normal stack entry (i.e.
1250 they are not 4 bytes or less). Aka, a function declaration
1251 like: int load_aclfile( struct client_state csp )</para>
1253 <para>would not work. So, to be consistent, we should declare all
1254 prototypes with "pass by value": int load_aclfile( struct
1255 client_state *csp )</para>
1261 <sect3 id="s31"><title>Names of include files</title>
1263 <para><emphasis>Explanation:</emphasis></para>
1265 <para>Your include statements should contain the file name without
1266 a path. The path should be listed in the Makefile, using -I as
1267 processor directive to search the indicated paths. An exception
1268 to this would be for some proprietary software that utilizes a
1269 partial path to distinguish their header files from system or
1270 other header files.</para>
1272 <para><emphasis>Example:</emphasis></para>
1274 #include <iostream.h> /* This is not a local include */
1275 #include "config.h" /* This IS a local include */
1278 <para><emphasis>Exception:</emphasis></para>
1282 /* This is not a local include, but requires a path element. */
1283 #include <sys/fileName.h>
1287 <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
1288 without a _very_ good reason. This duplicates the #include
1289 "file.h" behaviour.</para>
1295 <sect3 id="s32"><title>Provide multiple inclusion
1298 <para><emphasis>Explanation:</emphasis></para>
1300 <para>Prevents compiler and linker errors resulting from
1301 redefinition of items.</para>
1303 <para>Wrap each header file with the following syntax to prevent
1304 multiple inclusions of the file. Of course, replace PROJECT_H
1305 with your file name, with "." Changed to "_", and make it
1308 <para><emphasis>Example:</emphasis></para>
1310 #ifndef PROJECT_H_INCLUDED
1311 #define PROJECT_H_INCLUDED
1313 #endif /* ndef PROJECT_H_INCLUDED */
1318 <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
1320 <para><emphasis>Explanation:</emphasis></para>
1322 <para>If our headers are included from C++, they must declare our
1323 functions as `extern "C"`. This has no cost in C, but increases
1324 the potential re-usability of our code.</para>
1326 <para><emphasis>Example:</emphasis></para>
1331 #endif /* def __cplusplus */
1333 ... function definitions here ...
1337 #endif /* def __cplusplus */
1342 <sect3 id="s34"><title>Where Possible, Use Forward Struct
1343 Declaration Instead of Includes</title>
1345 <para><emphasis>Explanation:</emphasis></para>
1347 <para>Useful in headers that include pointers to other struct's.
1348 Modifications to excess header files may cause needless
1351 <para><emphasis>Example:</emphasis></para>
1353 /*********************************************************************
1354 * We're avoiding an include statement here!
1355 *********************************************************************/
1357 extern file_list *xyz;</programlisting>
1359 <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
1360 pointer), then including the proper header file is necessary.
1361 If you only want to prototype a pointer, however, the header
1362 file is unneccessary.</para>
1364 <para><emphasis>Status:</emphasis> Use with discrection.</para>
1370 <sect2 id="s35"><title>General Coding Practices</title>
1374 <sect3 id="s36"><title>Turn on warnings</title>
1376 <para><emphasis>Explanation</emphasis></para>
1378 <para>Compiler warnings are meant to help you find bugs. You
1379 should turn on as many as possible. With GCC, the switch is
1380 "-Wall". Try and fix as many warnings as possible.</para>
1386 <sect3 id="s37"><title>Provide a default case for all switch
1389 <para><emphasis>Explanation:</emphasis></para>
1391 <para>What you think is guaranteed is never really guaranteed. The
1392 value that you don't think you need to check is the one that
1393 someday will be passed. So, to protect yourself from the
1394 unknown, always have a default step in a switch statement.</para>
1396 <para><emphasis>Example:</emphasis></para>
1398 switch( hash_string( cmd ) )
1400 case hash_actions_file :
1410 ... anomly code goes here ...
1411 continue; / break; / exit( 1 ); / etc ...
1413 } /* end switch( hash_string( cmd ) ) */</programlisting>
1415 <para><emphasis>Note:</emphasis> If you already have a default condition, you
1416 are obviously exempt from this point. Of note, most of the
1417 WIN32 code calls `DefWindowProc' after the switch statement.
1418 This API call *should* be included in a default statement.</para>
1420 <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1421 as a robust programming issue. The "anomly code goes here" may
1422 be no more than a print to the STDERR stream (as in
1423 load_config). Or it may really be an ABEND condition.</para>
1425 <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1431 <sect3 id="s38"><title>Try to avoid falling through cases in a
1432 switch statement.</title>
1434 <para><emphasis>Explanation:</emphasis></para>
1436 <para>In general, you will want to have a 'break' statement within
1437 each 'case' of a switch statement. This allows for the code to
1438 be more readable and understandable, and furthermore can
1439 prevent unwanted surprises if someone else later gets creative
1440 and moves the code around.</para>
1442 <para>The language allows you to plan the fall through from one
1443 case statement to another simply by omitting the break
1444 statement within the case statement. This feature does have
1445 benefits, but should only be used in rare cases. In general,
1446 use a break statement for each case statement.</para>
1448 <para>If you choose to allow fall through, you should comment both
1449 the fact of the fall through and reason why you felt it was
1456 <sect3 id="s39"><title>Use 'long' or 'short' Instead of
1459 <para><emphasis>Explanation:</emphasis></para>
1461 <para>On 32-bit platforms, int usually has the range of long. On
1462 16-bit platforms, int has the range of short.</para>
1464 <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
1465 projects (including X/GNU-Emacs), there are typedefs to int4,
1466 int8, int16, (or equivalence ... I forget the exact typedefs
1467 now). Should we add these to IJB now that we have a "configure"
1474 <sect3 id="s40"><title>Don't mix size_t and other types</title>
1476 <para><emphasis>Explanation:</emphasis></para>
1478 <para>The type of size_t varies across platforms. Do not make
1479 assumptions about whether it is signed or unsigned, or about
1480 how long it is. Do not compare a size_t against another
1481 variable of a different type (or even against a constant)
1482 without casting one of the values. Try to avoid using size_t if
1489 <sect3 id="s41"><title>Declare each variable and struct on its
1492 <para><emphasis>Explanation:</emphasis></para>
1494 <para>It can be tempting to declare a series of variables all on
1495 one line. Don't.</para>
1497 <para><emphasis>Example:</emphasis></para>
1501 long c = 0;</programlisting>
1503 <para><emphasis>Instead of:</emphasis></para>
1505 <para>long a, b, c;</para>
1507 <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1508 individual variables - easier to add new variables without
1509 messing up the original ones - when searching on a variable to
1510 find its type, there is less clutter to "visually"
1513 <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1514 variables or other trivial variables; feel free to declare them
1515 on 1 line. You should, although, provide a good comment on
1516 their functions.</para>
1518 <para><emphasis>Status:</emphasis> developer-discrection.</para>
1524 <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1526 <para><emphasis>Explanation:</emphasis></para>
1528 <para>Create a local stuct (on the stack) if the variable will
1529 live and die within the context of one function call.</para>
1531 <para>Only "malloc" a struct (on the heap) if the variable's life
1532 will extend beyond the context of one function call.</para>
1534 <para><emphasis>Example:</emphasis></para>
1536 If a function creates a struct and stores a pointer to it in a
1537 list, then it should definately be allocated via `malloc'.
1542 <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1543 Responsible for Ensuring 'free'</title>
1545 <para><emphasis>Explanation:</emphasis></para>
1547 <para>If you have to "malloc" an instance, you are responsible for
1548 insuring that the instance is `free'd, even if the deallocation
1549 event falls within some other programmer's code. You are also
1550 responsible for ensuring that deletion is timely (i.e. not too
1551 soon, not too late). This is known as "low-coupling" and is a
1552 "good thing (tm)". You may need to offer a
1553 free/unload/destuctor type function to accomodate this.</para>
1555 <para><emphasis>Example:</emphasis></para>
1557 int load_re_filterfile( struct client_state *csp ) { ... }
1558 static void unload_re_filterfile( void *f ) { ... }</programlisting>
1560 <para><emphasis>Exceptions:</emphasis></para>
1562 <para>The developer cannot be expected to provide `free'ing
1563 functions for C run-time library functions ... such as
1566 <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
1567 standard is for allocating and freeing data structures (complex
1574 <sect3 id="s44"><title>Add loaders to the `file_list' structure
1575 and in order</title>
1577 <para><emphasis>Explanation:</emphasis></para>
1579 <para>I have ordered all of the "blocker" file code to be in alpha
1580 order. It is easier to add/read new blockers when you expect a
1581 certain order.</para>
1583 <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1584 places by POPUP tests coming before PCRS tests. But since
1585 POPUPs can also be referred to as KILLPOPUPs, it is clear that
1586 it should come first.</para>
1592 <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1593 exitinst code, use FIXME</title>
1595 <para><emphasis>Explanation:</emphasis></para>
1597 <para>If you have enough confidence in new code or confidence in
1598 your changes, but are not *quite* sure of the reprocussions,
1601 <para>/* FIXME: this code has a logic error on platform XYZ, *
1602 attempthing to fix */ #ifdef PLATFORM ...changed code here...
1607 <para>/* FIXME: I think the original author really meant this...
1608 */ ...changed code here...</para>
1612 <para>/* FIXME: new code that *may* break something else... */
1613 ...new code here...</para>
1615 <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1616 be a "good thing (tm)", it will be easier to identify and
1617 include in the project (or conversly exclude from the
1625 <sect2 id="s46"><title>Addendum: Template for files and function
1626 comment blocks:</title>
1628 <para><emphasis>Example for file comments:</emphasis></para>
1630 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $";
1631 /*********************************************************************
1633 * File : $S<!-- Break CVS Substitution -->ource$
1635 * Purpose : (Fill me in with a good description!)
1637 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1638 * Privoxy team. http://www.privoxy.org/
1640 * Based on the Internet Junkbuster originally written
1641 * by and Copyright (C) 1997 Anonymous Coders and
1642 * Junkbusters Corporation. http://www.junkbusters.com
1644 * This program is free software; you can redistribute it
1645 * and/or modify it under the terms of the GNU General
1646 * Public License as published by the Free Software
1647 * Foundation; either version 2 of the License, or (at
1648 * your option) any later version.
1650 * This program is distributed in the hope that it will
1651 * be useful, but WITHOUT ANY WARRANTY; without even the
1652 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1653 * PARTICULAR PURPOSE. See the GNU General Public
1654 * License for more details.
1656 * The GNU General Public License should be included with
1657 * this file. If not, you can view it at
1658 * http://www.gnu.org/copyleft/gpl.html
1659 * or write to the Free Software Foundation, Inc., 59
1660 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1663 * $L<!-- Break CVS Substitution -->og$
1665 *********************************************************************/
1670 ...necessary include files for us to do our work...
1672 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1675 <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1676 added to the "show-proxy-args" page. If this is a brand new
1677 creation by you, you are free to change the "Copyright" section
1678 to represent the rights you wish to maintain.</para>
1680 <para><emphasis>Note:</emphasis> The formfeed character that is present right
1681 after the comment flower box is handy for (X|GNU)Emacs users to
1682 skip the verbige and get to the heart of the code (via
1683 `forward-page' and `backward-page'). Please include it if you
1686 <para><emphasis>Example for file header comments:</emphasis></para>
1690 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $"
1691 /*********************************************************************
1693 * File : $S<!-- Break CVS Substitution -->ource$
1695 * Purpose : (Fill me in with a good description!)
1697 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1698 * Privoxy team. http://www.privoxy.org/
1700 * Based on the Internet Junkbuster originally written
1701 * by and Copyright (C) 1997 Anonymous Coders and
1702 * Junkbusters Corporation. http://www.junkbusters.com
1704 * This program is free software; you can redistribute it
1705 * and/or modify it under the terms of the GNU General
1706 * Public License as published by the Free Software
1707 * Foundation; either version 2 of the License, or (at
1708 * your option) any later version.
1710 * This program is distributed in the hope that it will
1711 * be useful, but WITHOUT ANY WARRANTY; without even the
1712 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1713 * PARTICULAR PURPOSE. See the GNU General Public
1714 * License for more details.
1716 * The GNU General Public License should be included with
1717 * this file. If not, you can view it at
1718 * http://www.gnu.org/copyleft/gpl.html
1719 * or write to the Free Software Foundation, Inc., 59
1720 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1723 * $L<!-- Break CVS Substitution -->og$
1725 *********************************************************************/
1728 #include "project.h"
1734 ... function headers here ...
1737 /* Revision control strings from this header and associated .c file */
1738 extern const char FILENAME_rcs[];
1739 extern const char FILENAME_h_rcs[];
1746 #endif /* ndef _FILENAME_H */
1755 <para><emphasis>Example for function comments:</emphasis></para>
1757 /*********************************************************************
1759 * Function : FUNCTION_NAME
1761 * Description : (Fill me in with a good description!)
1764 * 1 : param1 = pointer to an important thing
1765 * 2 : x = pointer to something else
1767 * Returns : 0 => Ok, everything else is an error.
1769 *********************************************************************/
1770 int FUNCTION_NAME( void *param1, const char *x )
1778 <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1779 able to parse our code to create a "self-documenting" web
1786 <!-- ~~~~~ New section ~~~~~ -->
1787 <sect1 id="cvs"><title>Version Control Guidelines</title>
1788 <para>To be filled. note on cvs comments. Don't only comment what you did,
1789 but also why you did it!
1793 <!-- ~~~~~ New section ~~~~~ -->
1794 <sect1 id="testing"><title>Testing Guidelines</title>
1798 <!-- ~~~~~ New section ~~~~~ -->
1799 <sect2 id="testing-plan"><title>Testplan for releases</title>
1801 Explain release numbers. major, minor. developer releases. etc.
1803 <orderedlist numeration="arabic">
1805 Remove any existing rpm with rpm -e
1808 Remove any file that was left over. This includes (but is not limited to)
1810 <listitem><para>/var/log/privoxy</para></listitem>
1811 <listitem><para>/etc/privoxy</para></listitem>
1812 <listitem><para>/usr/sbin/privoxy</para></listitem>
1813 <listitem><para>/etc/init.d/privoxy</para></listitem>
1814 <listitem><para>/usr/doc/privoxy*</para></listitem>
1818 Install the rpm. Any error messages?
1820 <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1821 (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1822 autostart work?</para></listitem>
1823 <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1824 <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1829 <!-- ~~~~~ New section ~~~~~ -->
1830 <sect2 id="testing-report"><title>Test reports</title>
1832 Please submit test reports only with the <ulink url="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005">test form</ulink>
1833 at sourceforge. Three simple steps:
1836 <listitem><para>Select category: the distribution you test on.</para></listitem>
1837 <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
1838 <listitem><para>Fill the Summary and Detailed Description with something
1839 intelligent (keep it short and precise).</para>
1842 Do not mail to the mailinglist (we cannot keep track on issues there).
1848 <!-- ~~~~~ New section ~~~~~ -->
1849 <sect1 id="newrelease"><title>Releasing a new version</title>
1851 To minimize trouble with distribution contents, webpage
1852 errors and the like, we strongly encourage you
1853 to follow this section if you prepare a new release of
1854 code or new pages on the webserver.
1857 The following programs are required to follow this process:
1858 <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
1859 <filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
1862 <sect2 id="beforerelease">
1863 <title>Before the Release</title>
1865 The following <emphasis>must be done by one of the
1866 developers</emphasis> prior to each new release:
1872 Make sure that everybody who has worked on the code in the last
1873 couple of days has had a chance to yell <quote>no!</quote> in case
1874 they have pending changes/fixes in their pipelines.
1879 Increment the version number in <filename>configure.in</filename> in
1880 CVS. Also, the RPM release number in
1881 <filename>configure.in</filename>. Do NOT touch version information
1882 after export from CVS. <emphasis>All packages</emphasis> will use the
1883 version and release data from <filename>configure.in</filename>.
1884 Local files should not be changed, except prior to a CVS commit!!!
1885 This way we are all on the same page!
1890 If the default actionsfile has changed since last release,
1891 bump up its version info in this line:
1895 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1899 Then change the version info in doc/webserver/actions/index.php,
1900 line: '$required_actions_file_version = "A.B";'
1905 Tag all files in CVS with the version number with
1906 <quote><command>cvs tag v_X_Y_Z</command></quote> (where X = major, Y
1907 = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
1913 The first package uploaded should be the official
1914 <quote>tarball</quote> release. This is built with the
1915 <quote><command>make tarball-dist</command></quote> Makefile
1916 target, and then can be uploaded with
1917 <quote><command>make tarball-upload</command></quote> (see below).
1924 <sect2 id="newrelease-web"><title>Update the webserver</title>
1926 All files must be group-readable and group-writable (or no one else
1927 will be able to change them). To update the webserver, create any
1928 pages locally in the <filename>doc/webserver</filename> directory (or
1929 create new directories under <filename>doc/webserver</filename>), then do
1937 Note that <quote><command>make dok</command></quote>
1938 (or <quote><command>make redhat-dok</command></quote>) creates
1939 <filename>doc/webserver/user-manual</filename>,
1940 <filename>doc/webserver/developer-manual</filename>,
1941 <filename>doc/webserver/faq</filename> and
1942 <filename>doc/webserver/man-page</filename> automatically.
1945 Please do NOT use any other means of transferring files to the
1946 webserver. <quote><command>make webserver</command></quote> not only
1947 uploads, but will make sure that the appropriate permissions are
1948 preserved for shared group access.
1952 <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
1954 Ensure that you have the latest code version. Hence run:
1959 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1960 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1968 autoheader && autoconf && ./configure
1976 make suse-dist or make redhat-dist
1980 To upload the package to Sourceforge, simply issue
1984 make suse-upload or make redhat-upload
1988 Go to the displayed URL and release the file publicly on Sourceforge.
1992 <sect2 id="newrelease-os2"><title>OS/2</title>
1994 Ensure that you have the latest code version. Hence run:
1999 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2000 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2002 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
2006 You will need a mix of development tools.
2007 The main compilation takes place with IBM Visual Age C++.
2008 Some ancillary work takes place with GNU tools, available from
2009 various sources like hobbes.nmsu.edu.
2010 Specificially, you will need <filename>autoheader</filename>,
2011 <filename>autoconf</filename> and <filename>sh</filename> tools.
2012 The packaging takes place with WarpIN, available from various sources, including
2013 its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2016 Change directory to the <filename>os2setup</filename> directory.
2017 Edit the os2build.cmd file to set the final executable filename.
2020 installExeName='privoxyos2_setup_X.Y.Z.exe'
2022 Next, edit the <filename>IJB.wis</filename> file so the release number matches
2023 in the <filename>PACKAGEID</filename> section:
2025 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2027 You're now ready to build. Run:
2031 And in the <filename>./files</filename> directory you will have the
2032 WarpIN-installable executable.
2033 Upload this anonymously to
2034 <filename>uploads.sourceforge.net/incoming</filename>, create a release
2035 for it, and you're done.
2039 <sect2 id="newrelease-solaris"><title>Solaris</title>
2041 Login to Sourceforge's compilefarm via ssh
2045 ssh cf.sourceforge.net
2049 Choose the right operating system (not the Debian one). If you have
2050 downloaded <application>Privoxy</application> before,
2055 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2056 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2060 If not, please <ulink
2061 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2062 Privoxy via CVS first</ulink>. Run:
2066 autoheader && autoconf && ./configure
2078 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2079 solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2080 to manually upload the archive to Sourceforge's ftp server and release
2085 <sect2 id="newrelease-windows"><title>Windows</title>
2087 Ensure that you have the latest code version. Hence run
2092 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2093 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2101 autoheader && autoconf && ./configure
2109 <sect2 id="newrelease-debian"><title>Debian</title>
2111 Ensure that you have the latest code version. Hence run:
2116 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2117 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2125 autoheader && autoconf && ./configure
2133 <sect2 id="newrelease-macosx"><title>Mac OSX</title>
2135 Ensure that you have the latest code version. Hence run:
2140 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2141 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2143 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
2147 From the osxsetup directory, run:
2153 This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
2154 <filename>configure</filename> as well as <filename>make</filename>.
2155 Finally, it will copy over the necessary files to the ./osxsetup/files directory
2156 for further processing by <filename>PackageMaker</filename>.
2159 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
2160 name to match the release, and hit the "Create package" button.
2161 If you specify ./Privoxy.pkg as the output package name, you can then create
2162 the distributable zip file with the command:
2164 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2166 You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
2167 <filename>uploads.sourceforge.net/incoming</filename>,
2168 create a release for it, and you're done.
2172 <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
2174 Change the version number of <application>Privoxy</application> in the
2175 configure.in file. Run:
2177 autoheader && autoconf && ./configure
2182 Login to Sourceforge's compilefarm via ssh:
2186 ssh cf.sourceforge.net
2190 Choose the right operating system. If you have downloaded Privoxy
2196 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2197 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2201 If not, please <ulink
2202 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2203 Privoxy via CVS first</ulink>. Run:
2207 autoheader && autoconf && ./configure
2219 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2220 freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
2221 to manually upload the archive to Sourceforge's ftp server and release
2226 <sect2 id="newrelease-tarball"><title>Tarball</title>
2228 Ensure that you have the latest code version. Hence run:
2233 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2234 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2243 autoheader && autoconf && ./configure
2255 To upload the package to Sourceforge, simply issue
2263 Goto the displayed URL and release the file publicly on Sourceforge.
2267 <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
2269 Ensure that you have the latest code version. Hence run:
2274 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2275 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2283 autoheader && autoconf && ./configure
2291 <sect2 id="newrelease-amiga"><title>Amiga OS</title>
2293 Ensure that you have the latest code version. Hence run:
2298 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2299 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2307 autoheader && autoconf && ./configure
2315 <sect2 id="newrelease-aix"><title>AIX</title>
2317 Login to Sourceforge's compilefarm via ssh:
2321 ssh cf.sourceforge.net
2325 Choose the right operating system. If you have downloaded Privoxy
2331 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2332 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2336 If not, please <ulink
2337 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2338 Privoxy via CVS first</ulink>. Run:
2342 autoheader && autoconf && ./configure
2354 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2355 aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
2356 to manually upload the archive to Sourceforge's ftp server and release
2363 <!-- ~~~~~ New section ~~~~~ -->
2364 <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
2365 <!-- Include contacting.sgml -->
2367 <!-- end contacting -->
2370 <!-- ~~~~~ New section ~~~~~ -->
2371 <sect1 id="copyright"><title>Copyright and History</title>
2373 <sect2><title>Copyright</title>
2374 <!-- Include copyright.sgml -->
2379 <sect2><title>History</title>
2380 <!-- Include history.sgml -->
2387 <!-- ~~~~~ New section ~~~~~ -->
2388 <sect1 id="seealso"><title>See also</title>
2389 <!-- Include seealso.sgml -->
2397 This program is free software; you can redistribute it
2398 and/or modify it under the terms of the GNU General
2399 Public License as published by the Free Software
2400 Foundation; either version 2 of the License, or (at
2401 your option) any later version.
2403 This program is distributed in the hope that it will
2404 be useful, but WITHOUT ANY WARRANTY; without even the
2405 implied warranty of MERCHANTABILITY or FITNESS FOR A
2406 PARTICULAR PURPOSE. See the GNU General Public
2407 License for more details.
2409 The GNU General Public License should be included with
2410 this file. If not, you can view it at
2411 http://www.gnu.org/copyleft/gpl.html
2412 or write to the Free Software Foundation, Inc., 59
2413 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2415 $Log: developer-manual.sgml,v $
2416 Revision 1.25 2002/04/06 05:07:28 hal9
2417 -Add privoxy-man-page.sgml, for man page.
2418 -Add authors.sgml for AUTHORS (and p-authors.sgml)
2419 -Reworked various aspects of various docs.
2420 -Added additional comments to sub-docs.
2422 Revision 1.24 2002/04/04 21:33:37 hal9
2423 More on documenting the documents.
2425 Revision 1.23 2002/04/04 18:46:47 swa
2426 consistent look. reuse of copyright, history et. al.
2428 Revision 1.22 2002/04/04 17:27:56 swa
2429 more single file to be included at multiple points. make maintaining easier
2431 Revision 1.21 2002/04/04 06:48:37 hal9
2432 Structural changes to allow for conditional inclusion/exclusion of content
2433 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
2434 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2435 eventually be set by Makefile.
2436 More boilerplate text for use across multiple docs.
2438 Revision 1.20 2002/04/04 03:28:27 david__schmidt
2441 Revision 1.19 2002/04/03 15:09:42 david__schmidt
2442 Add OS/2 build section
2444 Revision 1.18 2002/04/03 03:51:48 hal9
2447 Revision 1.17 2002/04/03 01:21:17 hal9
2448 Implementing Andreas's suggestions for Release sections.
2450 Revision 1.16 2002/03/31 23:04:40 hal9
2451 Fleshed out the doc section, and added something for an intro so it was not
2454 Revision 1.15 2002/03/30 22:29:47 swa
2457 Revision 1.14 2002/03/30 19:04:08 swa
2458 people release differently. no good.
2459 I want to make parts of the docs only.
2461 Revision 1.13 2002/03/27 01:16:41 hal9
2464 Revision 1.12 2002/03/27 01:02:51 hal9
2465 Touch up on name change...
2467 Revision 1.11 2002/03/26 22:29:55 swa
2468 we have a new homepage!
2470 Revision 1.10 2002/03/24 12:33:01 swa
2473 Revision 1.9 2002/03/24 11:01:05 swa
2476 Revision 1.8 2002/03/23 15:13:11 swa
2477 renamed every reference to the old name with foobar.
2478 fixed "application foobar application" tag, fixed
2479 "the foobar" with "foobar". left junkbustser in cvs
2480 comments and remarks to history untouched.
2482 Revision 1.7 2002/03/11 13:13:27 swa
2483 correct feedback channels
2485 Revision 1.6 2002/02/24 14:25:06 jongfoster
2486 Formatting changes. Now changing the doctype to DocBook XML 4.1
2487 will work - no other changes are needed.
2489 Revision 1.5 2001/10/31 18:16:51 swa
2490 documentation added: howto generate docs in text and html
2491 format, howto move stuff to the webserver.
2493 Revision 1.4 2001/09/23 10:13:48 swa
2494 upload process established. run make webserver and
2495 the documentation is moved to the webserver. documents
2496 are now linked correctly.
2498 Revision 1.3 2001/09/13 15:27:40 swa
2501 Revision 1.2 2001/09/13 15:20:17 swa
2502 merged standards into developer manual
2504 Revision 1.1 2001/09/12 15:36:41 swa
2505 source files for junkbuster documentation
2507 Revision 1.3 2001/09/10 17:43:59 swa
2508 first proposal of a structure.
2510 Revision 1.2 2001/06/13 14:28:31 swa
2511 docs should have an author.
2513 Revision 1.1 2001/06/13 14:20:37 swa
2514 first import of project's documentation for the webserver.