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.31 2002/04/11 09:32:52 oes 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.31 2002/04/11 09:32:52 oes 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
129 development. Mail your ID to the list and wait until a project
130 manager has added you.
133 For the time being (read, this section is under construction), please
134 note the 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
154 Note that near a major public release, we get a bit more cautious - if
155 unsure, it doesn't hurt to ask first.
159 <!-- ~~~~~ New section ~~~~~ -->
160 <sect1 id="documentation"><title>Documentation Guidelines</title>
162 All formal documents are maintained in docbook SGML and located in the
163 <computeroutput>doc/source/*</computeroutput> directory. You will need
164 <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
165 DTD's and the Docbook modular stylesheets (or comparable alternatives),
166 and either <application>jade</application> or
167 <application>openjade</application> (recommended) installed in order to
168 build docs from source. Currently there is <ulink
169 url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
170 <ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
171 course this, the <citetitle>developer-manual</citetitle> in this format.
172 The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
173 <citetitle>privoxy.1</citetitle> (man page) files are also now maintained
174 as Docbook SGML. The finished files are all in the top-level source
175 directory are generated files! Also, <filename>index.html</filename>, the
176 <application>Privoxy</application> home page, is maintained as SGML.
177 <emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
178 contact someone involved in the documentation (at present Stefan and
182 Other, less formal documents (e.g. <filename>LICENSE</filename>,
183 <filename>INSTALL</filename>) are maintained as plain text files in the
184 toplevel source directory. At least for the time being.
187 Packagers are encouraged to include this documentation. For those without
188 the ability to build the docs locally, text versions of each are kept in
189 CVS. HTML versions are also now being kept in CVS under
190 <filename>doc/webserver/*</filename>.
193 Formal documents are built with the Makefile targets of
194 <computeroutput>make dok</computeroutput>, or alternately
195 <computeroutput>make redhat-dok</computeroutput>. If you have problems,
196 try both. The build process uses the document SGML sources in
197 <computeroutput>doc/source/*/*</computeroutput> to update all text files in
198 <computeroutput>doc/text/</computeroutput> and to update all HTML
199 documents in <computeroutput>doc/webserver/</computeroutput>.
202 Documentation writers should please make sure documents build
203 successfully before committing to CVS.
206 How do you update the webserver (i.e. the pages on privoxy.org)?
208 <orderedlist numeration="arabic">
210 First, build the docs by running <computeroutput>make
211 dok</computeroutput> (or alternately <computeroutput>make
212 redhat-dok</computeroutput>).
215 Run <computeroutput>make webserver</computeroutput> which copies all
216 files from <computeroutput>doc/webserver</computeroutput> to the
217 sourceforge webserver via scp.
223 <!-- ~~~~~ New section ~~~~~ -->
225 <title>Quickstart to Docbook and SGML</title>
227 If you are not familiar with SGML, it is a markup language similar to HTML.
228 Actually, not a mark up language per se, but a language used to define
229 markup languages. In fact, HTML is an SGML application. Both will use
230 <quote>tags</quote> to format text and other content. SGML tags can be much
231 more varied, and flexible, but do much of the same kinds of things. The tags,
232 or <quote>elements</quote>, are definable in SGML. There is no set
233 <quote>standards</quote>. Since we are using
234 <application>Docbook</application>, our tags are those that are defined by
235 <application>Docbook</application>. Much of how the finish document is
236 rendered is determined by the <quote>stylesheets</quote>.
237 The stylesheets determine how each tag gets translated to HTML, or other
242 Tags in Docbook SGML need to be always <quote>closed</quote>. If not, you
243 will likely generate errors. Example: <literal><title>My
244 Title</title></literal>. They are also case-insensitive, but we
245 strongly suggest using all lower case. This keeps compatibility with
246 [Docbook] <application>XML</application>.
250 Our documents use <quote>sections</quote> for the most part. Sections
251 will be processed into HTML headers (e.g. <literal>h1</literal> for
252 <literal>sect1</literal>). The <application>Docbook</application> stylesheets
253 will use these to also generate the Table of Contents for each doc. Our
254 TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
255 <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
256 entries, but <literal>sect4</literal> will not. Each section requires
257 a <literal><title></literal> element, and at least one
258 <literal><para></literal>. There is a limit of five section
259 levels in Docbook, but generally three should be sufficient for our
264 Some common elements that you likely will use:
269 <emphasis><para></para></emphasis>, paragraph delimiter. Most
270 text needs to be within paragraph elements (there are some exceptions).
273 <emphasis><emphasis></emphasis></emphasis>, the stylesheets make this
277 <emphasis><filename></filename></emphasis>, files and directories.
280 <emphasis><command></command></emphasis>, command examples.
283 <emphasis><literallayout></literllayout></emphasis>, like
284 <literal><pre></literal>, more or less.
287 <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
290 <emphasis><listitem></listitem></emphasis>, member of the above.
293 <emphasis><screen></screen></emphasis>, screen output, implies
294 <literal><literallayout></literal>.
297 <emphasis><ulink url="example.com"></ulink></emphasis>, like
298 HTML <literal><a></literal> tag.
301 <emphasis><quote></quote></emphasis>, for, doh, quoting text.
306 Look at any of the existing docs for examples of all these and more.
312 <!-- ~~~~~ New section ~~~~~ -->
313 <sect2 id="docstyle">
314 <title><application>Privoxy</application> Documentation Style</title>
316 It will be easier if everyone follows a similar writing style. This
317 just makes it easier to read what someone else has written if it
318 is all done in a similar fashion.
327 All tags should be lower case.
332 Tags delimiting a <emphasis>block</emphasis> of text (even small
333 blocks) should be on their own line. Like:
339 Tags marking individual words, or few words, should be in-line:
341 Just to <emphasis>emphasize</emphasis>, some text goes here.
347 Tags should be nested and step indented for block text like: (except
354 Some text goes here in our list example.
357 </itemizedlist>
360 This makes it easier to find the text amongst the tags ;-)
365 Use white space to separate logical divisions within a document,
366 like between sections. Running everything together consistently
367 makes it harder to read and work on.
372 Do not hesitate to make comments. Comments can either use the
373 <comment> element, or the <!-- --> style comment
374 familiar from HTML. (Note in Docbook v4.x <comment> is
375 replaced by <remark>.)
380 We have an international audience. Refrain from slang, or English
381 idiosyncrasies (too many to list :).
386 Try to keep overall line lengths in source files to 80 characters or less
387 for obvious reasons. This is not always possible, with lenghty URLs for
393 Our documents are available in differing formats. Right now, they
394 are just plain text, and HTML, but PDF, and others is always a
395 future possibility. Be careful with URLs (<ulink>), and avoid
399 My favorite site is <ulink url="http://example.com">here</ulink>.
402 This will render as <quote>My favorite site is here</quote>, which is
403 not real helpful in a text doc. Better like this:
406 My favorite site is <ulink url="http://example.com">example.com</ulink>.
411 All documents should be spell checked occasionally.
412 <application>aspell</application> can check SGML with the
413 <literal>-H</literal> option. (<application>ispell</application> I think
424 <!-- ~~~~~ New section ~~~~~ -->
426 <sect2><title>Privoxy Custom Entities</title>
428 <application>Privoxy</application> documentation is using
429 a number of customized <quote>entities</quote> to facilitate
430 documentation maintenance.
433 We are using a set of <quote>boilerplate</quote> files with generic text,
434 that is used by multiple docs. This way we can write something once, and use
435 it repeatedly without having to re-write the same content over and over again.
436 If editing such a file, keep in mind that it should be
437 <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
438 contexts without additional modifications.
441 We are also using what <application>Docbook</application> calls
442 <quote>internal entities</quote>. These are like variables in
443 programming. Well, sort of. For instance, we have the
444 <literal>p-version</literal> entity that contains the current
445 <application>Privoxy</application> version string. You are strongly
446 encouraged to use these where possible. Some of these obviously
447 require re-setting with each release (done by the Makefile). A sampling of
448 custom entities are listed below. See any of the main docs for examples.
455 Re-cyclable <quote>boilerplate</quote> text entities are defined like:
458 <literal><!entity supported SYSTEM "supported.sgml"></literal>
461 In this example, the contents of the file,
462 <filename>supported.sgml</filename> is available for inclusion anywhere
463 in the doc. To make this happen, just reference the now defined
464 entity: <literal>&supported;</literal> (starts with an ampersand
465 and ends with a semi-colon), and the contents will be dumped into
466 the finished doc at that point.
471 Commonly used <quote>internal entities</quote>:
475 <emphasis>p-version</emphasis>: the <application>Privoxy</application>
476 version string, e.g. <quote>2.9.13</quote>.
479 <emphasis>p-status</emphasis>: the project status, either
480 <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
483 <emphasis>p-not-stable</emphasis>: use to conditionally include
484 text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
487 <emphasis>p-stable</emphasis>: just the opposite.
490 <emphasis>p-text</emphasis>: this doc is only generated as text.
497 There are others in various places that are defined for a specific
498 purpose. Read the source!
505 <!-- <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
506 <!-- points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
508 <!-- ~~~~~ New section ~~~~~ -->
509 <sect1 id="coding"><title>Coding Guidelines</title>
511 <sect2 id="s1"><title>Introduction</title>
513 <para>This set of standards is designed to make our lives easier. It is
514 developed with the simple goal of helping us keep the "new and improved
515 <application>Privoxy</application>" consistent and reliable. Thus making
516 maintenance easier and increasing chances of success of the
519 <para>And that of course comes back to us as individuals. If we can
520 increase our development and product efficiencies then we can solve more
521 of the request for changes/improvements and in general feel good about
522 ourselves. ;-></para>
526 <sect2 id="s2"><title>Using Comments</title>
529 <sect3 id="s3"><title>Comment, Comment, Comment</title>
531 <para><emphasis>Explanation:</emphasis></para>
533 <para>Comment as much as possible without commenting the obvious.
534 For example do not comment "aVariable is equal to bVariable".
535 Instead explain why aVariable should be equal to the bVariable.
536 Just because a person can read code does not mean they will
537 understand why or what is being done. A reader may spend a lot
538 more time figuring out what is going on when a simple comment
539 or explanation would have prevented the extra research. Please
540 help your brother IJB'ers out!</para>
542 <para>The comments will also help justify the intent of the code.
543 If the comment describes something different than what the code
544 is doing then maybe a programming error is occurring.</para>
546 <para><emphasis>Example:</emphasis></para>
548 /* if page size greater than 1k ... */
549 if ( PageLength() > 1024 )
551 ... "block" the page up ...
554 /* if page size is small, send it in blocks */
555 if ( PageLength() > 1024 )
557 ... "block" the page up ...
560 This demonstrates 2 cases of "what not to do". The first is a
561 "syntax comment". The second is a comment that does not fit what
562 is actually being done.
568 <sect3 id="s4"><title>Use blocks for comments</title>
570 <para><emphasis>Explanation:</emphasis></para>
572 <para>Comments can help or they can clutter. They help when they
573 are differentiated from the code they describe. One line
574 comments do not offer effective separation between the comment
575 and the code. Block identifiers do, by surrounding the code
576 with a clear, definable pattern.</para>
578 <para><emphasis>Example:</emphasis></para>
580 /*********************************************************************
581 * This will stand out clearly in your code!
582 *********************************************************************/
583 if ( thisVariable == thatVariable )
585 DoSomethingVeryImportant();
589 /* unfortunately, this may not */
590 if ( thisVariable == thatVariable )
592 DoSomethingVeryImportant();
596 if ( thisVariable == thatVariable ) /* this may not either */
598 DoSomethingVeryImportant();
601 <para><emphasis>Exception:</emphasis></para>
603 <para>If you are trying to add a small logic comment and do not
604 wish to "disrubt" the flow of the code, feel free to use a 1
605 line comment which is NOT on the same line as the code.</para>
611 <sect3 id="s5"><title>Keep Comments on their own line</title>
613 <para><emphasis>Explanation:</emphasis></para>
615 <para>It goes back to the question of readability. If the comment
616 is on the same line as the code it will be harder to read than
617 the comment that is on its own line.</para>
619 <para>There are three exceptions to this rule, which should be
620 violated freely and often: during the definition of variables,
621 at the end of closing braces, when used to comment
624 <para><emphasis>Example:</emphasis></para>
626 /*********************************************************************
627 * This will stand out clearly in your code,
628 * But the second example won't.
629 *********************************************************************/
630 if ( thisVariable == thatVariable )
632 DoSomethingVeryImportant();
635 if ( thisVariable == thatVariable ) /*can you see me?*/
637 DoSomethingVeryImportant(); /*not easily*/
641 /*********************************************************************
642 * But, the encouraged exceptions:
643 *********************************************************************/
644 int urls_read = 0; /* # of urls read + rejected */
645 int urls_rejected = 0; /* # of urls rejected */
649 DoSomethingVeryImportant();
653 short DoSomethingVeryImportant(
654 short firstparam, /* represents something */
655 short nextparam /* represents something else */ )
659 } /* -END- DoSomethingVeryImportant */
664 <sect3 id="s6"><title>Comment each logical step</title>
666 <para><emphasis>Explanation:</emphasis></para>
668 <para>Logical steps should be commented to help others follow the
669 intent of the written code and comments will make the code more
672 <para>If you have 25 lines of code without a comment, you should
673 probably go back into it to see where you forgot to put
676 <para>Most "for", "while", "do", etc... loops _probably_ need a
677 comment. After all, these are usually major logic
684 <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
686 <para><emphasis>Explanation:</emphasis></para>
688 <para>A reader of the code should be able to look at the comments
689 just prior to the beginning of a function and discern the
690 reason for its existence and the consequences of using it. The
691 reader should not have to read through the code to determine if
692 a given function is safe for a desired use. The proper
693 information thoroughly presented at the introduction of a
694 function not only saves time for subsequent maintenance or
695 debugging, it more importantly aids in code reuse by allowing a
696 user to determine the safety and applicability of any function
697 for the problem at hand. As a result of such benefits, all
698 functions should contain the information presented in the
699 addendum section of this document.</para>
705 <sect3 id="s8"><title>Comment at the end of braces if the
706 content is more than one screen length</title>
708 <para><emphasis>Explanation:</emphasis></para>
710 <para>Each closing brace should be followed on the same line by a
711 comment that describes the origination of the brace if the
712 original brace is off of the screen, or otherwise far away from
713 the closing brace. This will simplify the debugging,
714 maintenance, and readability of the code.</para>
716 <para>As a suggestion , use the following flags to make the
717 comment and its brace more readable:</para>
719 <para>use following a closing brace: } /* -END- if() or while ()
722 <para><emphasis>Example:</emphasis></para>
726 DoSomethingVeryImportant();
727 ...some long list of commands...
728 } /* -END- if x is 1 */
734 DoSomethingVeryImportant();
735 ...some long list of commands...
736 } /* -END- if ( 1 == X ) */
742 <sect2 id="s9"><title>Naming Conventions</title>
746 <sect3 id="s10"><title>Variable Names</title>
748 <para><emphasis>Explanation:</emphasis></para>
750 <para>Use all lowercase, and seperate words via an underscore
751 ('_'). Do not start an identifier with an underscore. (ANSI C
752 reserves these for use by the compiler and system headers.) Do
753 not use identifiers which are reserved in ANSI C++. (E.g.
754 template, class, true, false, ...). This is in case we ever
755 decide to port Privoxy to C++.</para>
757 <para><emphasis>Example:</emphasis></para>
759 int ms_iis5_hack = 0;</programlisting>
761 <para><emphasis>Instead of:</emphasis></para>
765 int msiis5hack = 0; int msIis5Hack = 0;
773 <sect3 id="s11"><title>Function Names</title>
775 <para><emphasis>Explanation:</emphasis></para>
777 <para>Use all lowercase, and seperate words via an underscore
778 ('_'). Do not start an identifier with an underscore. (ANSI C
779 reserves these for use by the compiler and system headers.) Do
780 not use identifiers which are reserved in ANSI C++. (E.g.
781 template, class, true, false, ...). This is in case we ever
782 decide to port Privoxy to C++.</para>
784 <para><emphasis>Example:</emphasis></para>
786 int load_some_file( struct client_state *csp )</programlisting>
788 <para><emphasis>Instead of:</emphasis></para>
792 int loadsomefile( struct client_state *csp )
793 int loadSomeFile( struct client_state *csp )
801 <sect3 id="s12"><title>Header file prototypes</title>
803 <para><emphasis>Explanation:</emphasis></para>
805 <para>Use a descriptive parameter name in the function prototype
806 in header files. Use the same parameter name in the header file
807 that you use in the c file.</para>
809 <para><emphasis>Example:</emphasis></para>
811 (.h) extern int load_aclfile( struct client_state *csp );
812 (.c) int load_aclfile( struct client_state *csp )</programlisting>
814 <para><emphasis>Instead of:</emphasis>
816 (.h) extern int load_aclfile( struct client_state * ); or
817 (.h) extern int load_aclfile();
818 (.c) int load_aclfile( struct client_state *csp )
826 <sect3 id="s13"><title>Enumerations, and #defines</title>
828 <para><emphasis>Explanation:</emphasis></para>
830 <para>Use all capital letters, with underscores between words. Do
831 not start an identifier with an underscore. (ANSI C reserves
832 these for use by the compiler and system headers.)</para>
834 <para><emphasis>Example:</emphasis></para>
836 (enumeration) : enum Boolean { FALSE, TRUE };
837 (#define) : #define DEFAULT_SIZE 100;</programlisting>
839 <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
840 that toggle a feature in the preprocessor: FEATURE_>, where
841 > is a short (preferably 1 or 2 word) description.</para>
843 <para><emphasis>Example:</emphasis></para>
845 #define FEATURE_FORCE 1
848 #define FORCE_PREFIX blah
849 #endif /* def FEATURE_FORCE */
854 <sect3 id="s14"><title>Constants</title>
856 <para><emphasis>Explanation:</emphasis></para>
858 <para>Spell common words out entirely (do not remove vowels).</para>
860 <para>Use only widely-known domain acronyms and abbreviations.
861 Capitalize all letters of an acronym.</para>
863 <para>Use underscore (_) to separate adjacent acronyms and
864 abbreviations. Never terminate a name with an underscore.</para>
866 <para><emphasis>Example:</emphasis></para>
868 #define USE_IMAGE_LIST 1</programlisting>
870 <para><emphasis>Instead of:</emphasis></para>
874 #define USE_IMG_LST 1 or
875 #define _USE_IMAGE_LIST 1 or
876 #define USE_IMAGE_LIST_ 1 or
877 #define use_image_list 1 or
878 #define UseImageList 1
888 <sect2 id="s15"><title>Using Space</title>
892 <sect3 id="s16"><title>Put braces on a line by themselves.</title>
894 <para><emphasis>Explanation:</emphasis></para>
896 <para>The brace needs to be on a line all by itself, not at the
897 end of the statement. Curly braces should line up with the
898 construct that they're associated with. This practice makes it
899 easier to identify the opening and closing braces for a
902 <para><emphasis>Example:</emphasis></para>
909 <para><emphasis>Instead of:</emphasis></para>
911 <para>if ( this == that ) { ... }</para>
915 <para>if ( this == that ) { ... }</para>
917 <para><emphasis>Note:</emphasis> In the special case that the if-statement is
918 inside a loop, and it is trivial, i.e. it tests for a
919 condidtion that is obvious from the purpose of the block,
920 one-liners as above may optically preserve the loop structure
921 and make it easier to read.</para>
923 <para><emphasis>Status:</emphasis> developer-discrection.</para>
925 <para><emphasis>Example exception:</emphasis></para>
927 while ( more lines are read )
929 /* Please document what is/is not a comment line here */
930 if ( it's a comment ) continue;
932 do_something( line );
938 <sect3 id="s17"><title>ALL control statements should have a
941 <para><emphasis>Explanation:</emphasis></para>
943 <para>Using braces to make a block will make your code more
944 readable and less prone to error. All control statements should
945 have a block defined.</para>
947 <para><emphasis>Example:</emphasis></para>
955 <para><emphasis>Instead of:</emphasis></para>
957 <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
961 <para>if ( this == that ) DoSomething();</para>
963 <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
964 in a manner other than that which the developer desired (per
965 indentation). Using code braces would have prevented this
966 "feature". The "explanation" and "exception" from the point
967 above also applies.</para>
973 <sect3 id="s18"><title>Do not belabor/blow-up boolean
976 <para><emphasis>Example:</emphasis></para>
978 structure->flag = ( condition );</programlisting>
980 <para><emphasis>Instead of:</emphasis></para>
982 <para>if ( condition ) { structure->flag = 1; } else {
983 structure->flag = 0; }</para>
985 <para><emphasis>Note:</emphasis> The former is readable and consice. The later
986 is wordy and inefficient. Please assume that any developer new
987 to the project has at least a "good" knowledge of C/C++. (Hope
988 I do not offend by that last comment ... 8-)</para>
994 <sect3 id="s19"><title>Use white space freely because it is
997 <para><emphasis>Explanation:</emphasis></para>
999 <para>Make it readable. The notable exception to using white space
1000 freely is listed in the next guideline.</para>
1002 <para><emphasis>Example:</emphasis></para>
1006 int anotherValue = 0;
1007 int thisVariable = 0;
1009 if ( thisVariable == thatVariable )
1011 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
1016 <sect3 id="s20"><title>Don't use white space around structure
1019 <para><emphasis>Explanation:</emphasis></para>
1021 <para>- structure pointer operator ( "->" ) - member operator (
1022 "." ) - functions and parentheses</para>
1024 <para>It is a general coding practice to put pointers, references,
1025 and function parentheses next to names. With spaces, the
1026 connection between the object and variable/function name is not
1029 <para><emphasis>Example:</emphasis></para>
1033 FunctionName();</programlisting>
1035 <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
1036 FunctionName ();</para>
1042 <sect3 id="s21"><title>Make the last brace of a function stand
1045 <para><emphasis>Example:</emphasis></para>
1047 int function1( ... )
1052 } /* -END- function1 */
1055 int function2( ... )
1057 } /* -END- function2 */
1060 <para><emphasis>Instead of:</emphasis></para>
1062 <para>int function1( ... ) { ...code... return( retCode ); } int
1063 function2( ... ) { }</para>
1065 <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
1066 lines afterwards. This makes the end of function standout to
1067 the most casual viewer. Although function comments help
1068 seperate functions, this is still a good coding practice. In
1069 fact, I follow these rules when using blocks in "for", "while",
1070 "do" loops, and long if {} statements too. After all whitespace
1073 <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
1074 lines. Enforced is the end of function comments.</para>
1080 <sect3 id="s22"><title>Use 3 character indentions</title>
1082 <para><emphasis>Explanation:</emphasis></para>
1084 <para>If some use 8 character TABs and some use 3 character TABs,
1085 the code can look *very* ragged. So use 3 character indentions
1086 only. If you like to use TABs, pass your code through a filter
1087 such as "expand -t3" before checking in your code.</para>
1089 <para><emphasis>Example:</emphasis></para>
1091 static const char * const url_code_map[256] =
1097 int function1( ... )
1101 return( ALWAYS_TRUE );
1105 return( HOW_DID_YOU_GET_HERE );
1108 return( NEVER_GETS_HERE );
1117 <sect2 id="s23"><title>Initializing</title>
1121 <sect3 id="s24"><title>Initialize all variables</title>
1123 <para><emphasis>Explanation:</emphasis></para>
1125 <para>Do not assume that the variables declared will not be used
1126 until after they have been assigned a value somewhere else in
1127 the code. Remove the chance of accidentally using an unassigned
1130 <para><emphasis>Example:</emphasis></para>
1134 struct *ptr = NULL;</programlisting>
1136 <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
1137 message says you are trying to access memory address 00000000
1138 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
1141 <para><emphasis>Status:</emphasis> developer-discrection if and only if the
1142 variable is assigned a value "shortly after" declaration.</para>
1148 <sect2 id="s25"><title>Functions</title>
1152 <sect3 id="s26"><title>Name functions that return a boolean as a
1155 <para><emphasis>Explanation:</emphasis></para>
1157 <para>Value should be phrased as a question that would logically
1158 be answered as a true or false statement</para>
1160 <para><emphasis>Example:</emphasis></para>
1162 ShouldWeBlockThis();
1169 <sect3 id="s27"><title>Always specify a return type for a
1172 <para><emphasis>Explanation:</emphasis></para>
1174 <para>The default return for a function is an int. To avoid
1175 ambiguity, create a return for a function when the return has a
1176 purpose, and create a void return type if the function does not
1177 need to return anything.</para>
1183 <sect3 id="s28"><title>Minimize function calls when iterating by
1184 using variables</title>
1186 <para><emphasis>Explanation:</emphasis></para>
1188 <para>It is easy to write the following code, and a clear argument
1189 can be made that the code is easy to understand:</para>
1191 <para><emphasis>Example:</emphasis></para>
1193 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1198 <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
1199 each and every iteration. This increases the overhead in the
1200 program, because the compiler has to look up the function each
1201 time, call it, and return a value. Depending on what occurs in
1202 the blockListLength() call, it might even be creating and
1203 destroying structures with each iteration, even though in each
1204 case it is comparing "cnt" to the same value, over and over.
1205 Remember too - even a call to blockListLength() is a function
1206 call, with the same overhead.</para>
1208 <para>Instead of using a function call during the iterations,
1209 assign the value to a variable, and evaluate using the
1212 <para><emphasis>Example:</emphasis></para>
1214 size_t len = blockListLength();
1216 for ( size_t cnt = 0; cnt < len; cnt ++ )
1221 <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
1222 change or could *potentially* change, then you must code the
1223 function call in the for/while loop.</para>
1229 <sect3 id="s29"><title>Pass and Return by Const Reference</title>
1231 <para><emphasis>Explanation:</emphasis></para>
1233 <para>This allows a developer to define a const pointer and call
1234 your function. If your function does not have the const
1235 keyword, we may not be able to use your function. Consider
1236 strcmp, if it were defined as: extern int strcmp( char *s1,
1239 <para>I could then not use it to compare argv's in main: int main(
1240 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1243 <para>Both these pointers are *const*! If the c runtime library
1244 maintainers do it, we should too.</para>
1250 <sect3 id="s30"><title>Pass and Return by Value</title>
1252 <para><emphasis>Explanation:</emphasis></para>
1254 <para>Most structures cannot fit onto a normal stack entry (i.e.
1255 they are not 4 bytes or less). Aka, a function declaration
1256 like: int load_aclfile( struct client_state csp )</para>
1258 <para>would not work. So, to be consistent, we should declare all
1259 prototypes with "pass by value": int load_aclfile( struct
1260 client_state *csp )</para>
1266 <sect3 id="s31"><title>Names of include files</title>
1268 <para><emphasis>Explanation:</emphasis></para>
1270 <para>Your include statements should contain the file name without
1271 a path. The path should be listed in the Makefile, using -I as
1272 processor directive to search the indicated paths. An exception
1273 to this would be for some proprietary software that utilizes a
1274 partial path to distinguish their header files from system or
1275 other header files.</para>
1277 <para><emphasis>Example:</emphasis></para>
1279 #include <iostream.h> /* This is not a local include */
1280 #include "config.h" /* This IS a local include */
1283 <para><emphasis>Exception:</emphasis></para>
1287 /* This is not a local include, but requires a path element. */
1288 #include <sys/fileName.h>
1292 <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
1293 without a _very_ good reason. This duplicates the #include
1294 "file.h" behaviour.</para>
1300 <sect3 id="s32"><title>Provide multiple inclusion
1303 <para><emphasis>Explanation:</emphasis></para>
1305 <para>Prevents compiler and linker errors resulting from
1306 redefinition of items.</para>
1308 <para>Wrap each header file with the following syntax to prevent
1309 multiple inclusions of the file. Of course, replace PROJECT_H
1310 with your file name, with "." Changed to "_", and make it
1313 <para><emphasis>Example:</emphasis></para>
1315 #ifndef PROJECT_H_INCLUDED
1316 #define PROJECT_H_INCLUDED
1318 #endif /* ndef PROJECT_H_INCLUDED */
1323 <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
1325 <para><emphasis>Explanation:</emphasis></para>
1327 <para>If our headers are included from C++, they must declare our
1328 functions as `extern "C"`. This has no cost in C, but increases
1329 the potential re-usability of our code.</para>
1331 <para><emphasis>Example:</emphasis></para>
1336 #endif /* def __cplusplus */
1338 ... function definitions here ...
1342 #endif /* def __cplusplus */
1347 <sect3 id="s34"><title>Where Possible, Use Forward Struct
1348 Declaration Instead of Includes</title>
1350 <para><emphasis>Explanation:</emphasis></para>
1352 <para>Useful in headers that include pointers to other struct's.
1353 Modifications to excess header files may cause needless
1356 <para><emphasis>Example:</emphasis></para>
1358 /*********************************************************************
1359 * We're avoiding an include statement here!
1360 *********************************************************************/
1362 extern file_list *xyz;</programlisting>
1364 <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
1365 pointer), then including the proper header file is necessary.
1366 If you only want to prototype a pointer, however, the header
1367 file is unneccessary.</para>
1369 <para><emphasis>Status:</emphasis> Use with discrection.</para>
1375 <sect2 id="s35"><title>General Coding Practices</title>
1379 <sect3 id="s36"><title>Turn on warnings</title>
1381 <para><emphasis>Explanation</emphasis></para>
1383 <para>Compiler warnings are meant to help you find bugs. You
1384 should turn on as many as possible. With GCC, the switch is
1385 "-Wall". Try and fix as many warnings as possible.</para>
1391 <sect3 id="s37"><title>Provide a default case for all switch
1394 <para><emphasis>Explanation:</emphasis></para>
1396 <para>What you think is guaranteed is never really guaranteed. The
1397 value that you don't think you need to check is the one that
1398 someday will be passed. So, to protect yourself from the
1399 unknown, always have a default step in a switch statement.</para>
1401 <para><emphasis>Example:</emphasis></para>
1403 switch( hash_string( cmd ) )
1405 case hash_actions_file :
1415 ... anomly code goes here ...
1416 continue; / break; / exit( 1 ); / etc ...
1418 } /* end switch( hash_string( cmd ) ) */</programlisting>
1420 <para><emphasis>Note:</emphasis> If you already have a default condition, you
1421 are obviously exempt from this point. Of note, most of the
1422 WIN32 code calls `DefWindowProc' after the switch statement.
1423 This API call *should* be included in a default statement.</para>
1425 <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1426 as a robust programming issue. The "anomly code goes here" may
1427 be no more than a print to the STDERR stream (as in
1428 load_config). Or it may really be an ABEND condition.</para>
1430 <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1436 <sect3 id="s38"><title>Try to avoid falling through cases in a
1437 switch statement.</title>
1439 <para><emphasis>Explanation:</emphasis></para>
1441 <para>In general, you will want to have a 'break' statement within
1442 each 'case' of a switch statement. This allows for the code to
1443 be more readable and understandable, and furthermore can
1444 prevent unwanted surprises if someone else later gets creative
1445 and moves the code around.</para>
1447 <para>The language allows you to plan the fall through from one
1448 case statement to another simply by omitting the break
1449 statement within the case statement. This feature does have
1450 benefits, but should only be used in rare cases. In general,
1451 use a break statement for each case statement.</para>
1453 <para>If you choose to allow fall through, you should comment both
1454 the fact of the fall through and reason why you felt it was
1461 <sect3 id="s39"><title>Use 'long' or 'short' Instead of
1464 <para><emphasis>Explanation:</emphasis></para>
1466 <para>On 32-bit platforms, int usually has the range of long. On
1467 16-bit platforms, int has the range of short.</para>
1469 <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
1470 projects (including X/GNU-Emacs), there are typedefs to int4,
1471 int8, int16, (or equivalence ... I forget the exact typedefs
1472 now). Should we add these to IJB now that we have a "configure"
1479 <sect3 id="s40"><title>Don't mix size_t and other types</title>
1481 <para><emphasis>Explanation:</emphasis></para>
1483 <para>The type of size_t varies across platforms. Do not make
1484 assumptions about whether it is signed or unsigned, or about
1485 how long it is. Do not compare a size_t against another
1486 variable of a different type (or even against a constant)
1487 without casting one of the values. Try to avoid using size_t if
1494 <sect3 id="s41"><title>Declare each variable and struct on its
1497 <para><emphasis>Explanation:</emphasis></para>
1499 <para>It can be tempting to declare a series of variables all on
1500 one line. Don't.</para>
1502 <para><emphasis>Example:</emphasis></para>
1506 long c = 0;</programlisting>
1508 <para><emphasis>Instead of:</emphasis></para>
1510 <para>long a, b, c;</para>
1512 <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1513 individual variables - easier to add new variables without
1514 messing up the original ones - when searching on a variable to
1515 find its type, there is less clutter to "visually"
1518 <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1519 variables or other trivial variables; feel free to declare them
1520 on 1 line. You should, although, provide a good comment on
1521 their functions.</para>
1523 <para><emphasis>Status:</emphasis> developer-discrection.</para>
1529 <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1531 <para><emphasis>Explanation:</emphasis></para>
1533 <para>Create a local stuct (on the stack) if the variable will
1534 live and die within the context of one function call.</para>
1536 <para>Only "malloc" a struct (on the heap) if the variable's life
1537 will extend beyond the context of one function call.</para>
1539 <para><emphasis>Example:</emphasis></para>
1541 If a function creates a struct and stores a pointer to it in a
1542 list, then it should definately be allocated via `malloc'.
1547 <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1548 Responsible for Ensuring 'free'</title>
1550 <para><emphasis>Explanation:</emphasis></para>
1552 <para>If you have to "malloc" an instance, you are responsible for
1553 insuring that the instance is `free'd, even if the deallocation
1554 event falls within some other programmer's code. You are also
1555 responsible for ensuring that deletion is timely (i.e. not too
1556 soon, not too late). This is known as "low-coupling" and is a
1557 "good thing (tm)". You may need to offer a
1558 free/unload/destuctor type function to accomodate this.</para>
1560 <para><emphasis>Example:</emphasis></para>
1562 int load_re_filterfile( struct client_state *csp ) { ... }
1563 static void unload_re_filterfile( void *f ) { ... }</programlisting>
1565 <para><emphasis>Exceptions:</emphasis></para>
1567 <para>The developer cannot be expected to provide `free'ing
1568 functions for C run-time library functions ... such as
1571 <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
1572 standard is for allocating and freeing data structures (complex
1579 <sect3 id="s44"><title>Add loaders to the `file_list' structure
1580 and in order</title>
1582 <para><emphasis>Explanation:</emphasis></para>
1584 <para>I have ordered all of the "blocker" file code to be in alpha
1585 order. It is easier to add/read new blockers when you expect a
1586 certain order.</para>
1588 <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1589 places by POPUP tests coming before PCRS tests. But since
1590 POPUPs can also be referred to as KILLPOPUPs, it is clear that
1591 it should come first.</para>
1597 <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1598 exitinst code, use FIXME</title>
1600 <para><emphasis>Explanation:</emphasis></para>
1602 <para>If you have enough confidence in new code or confidence in
1603 your changes, but are not *quite* sure of the reprocussions,
1606 <para>/* FIXME: this code has a logic error on platform XYZ, *
1607 attempthing to fix */ #ifdef PLATFORM ...changed code here...
1612 <para>/* FIXME: I think the original author really meant this...
1613 */ ...changed code here...</para>
1617 <para>/* FIXME: new code that *may* break something else... */
1618 ...new code here...</para>
1620 <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1621 be a "good thing (tm)", it will be easier to identify and
1622 include in the project (or conversly exclude from the
1630 <sect2 id="s46"><title>Addendum: Template for files and function
1631 comment blocks:</title>
1633 <para><emphasis>Example for file comments:</emphasis></para>
1635 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $";
1636 /*********************************************************************
1638 * File : $S<!-- Break CVS Substitution -->ource$
1640 * Purpose : (Fill me in with a good description!)
1642 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1643 * Privoxy team. http://www.privoxy.org/
1645 * Based on the Internet Junkbuster originally written
1646 * by and Copyright (C) 1997 Anonymous Coders and
1647 * Junkbusters Corporation. http://www.junkbusters.com
1649 * This program is free software; you can redistribute it
1650 * and/or modify it under the terms of the GNU General
1651 * Public License as published by the Free Software
1652 * Foundation; either version 2 of the License, or (at
1653 * your option) any later version.
1655 * This program is distributed in the hope that it will
1656 * be useful, but WITHOUT ANY WARRANTY; without even the
1657 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1658 * PARTICULAR PURPOSE. See the GNU General Public
1659 * License for more details.
1661 * The GNU General Public License should be included with
1662 * this file. If not, you can view it at
1663 * http://www.gnu.org/copyleft/gpl.html
1664 * or write to the Free Software Foundation, Inc., 59
1665 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1668 * $L<!-- Break CVS Substitution -->og$
1670 *********************************************************************/
1675 ...necessary include files for us to do our work...
1677 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1680 <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1681 added to the "show-proxy-args" page. If this is a brand new
1682 creation by you, you are free to change the "Copyright" section
1683 to represent the rights you wish to maintain.</para>
1685 <para><emphasis>Note:</emphasis> The formfeed character that is present right
1686 after the comment flower box is handy for (X|GNU)Emacs users to
1687 skip the verbige and get to the heart of the code (via
1688 `forward-page' and `backward-page'). Please include it if you
1691 <para><emphasis>Example for file header comments:</emphasis></para>
1695 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $"
1696 /*********************************************************************
1698 * File : $S<!-- Break CVS Substitution -->ource$
1700 * Purpose : (Fill me in with a good description!)
1702 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1703 * Privoxy team. http://www.privoxy.org/
1705 * Based on the Internet Junkbuster originally written
1706 * by and Copyright (C) 1997 Anonymous Coders and
1707 * Junkbusters Corporation. http://www.junkbusters.com
1709 * This program is free software; you can redistribute it
1710 * and/or modify it under the terms of the GNU General
1711 * Public License as published by the Free Software
1712 * Foundation; either version 2 of the License, or (at
1713 * your option) any later version.
1715 * This program is distributed in the hope that it will
1716 * be useful, but WITHOUT ANY WARRANTY; without even the
1717 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1718 * PARTICULAR PURPOSE. See the GNU General Public
1719 * License for more details.
1721 * The GNU General Public License should be included with
1722 * this file. If not, you can view it at
1723 * http://www.gnu.org/copyleft/gpl.html
1724 * or write to the Free Software Foundation, Inc., 59
1725 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1728 * $L<!-- Break CVS Substitution -->og$
1730 *********************************************************************/
1733 #include "project.h"
1739 ... function headers here ...
1742 /* Revision control strings from this header and associated .c file */
1743 extern const char FILENAME_rcs[];
1744 extern const char FILENAME_h_rcs[];
1751 #endif /* ndef _FILENAME_H */
1760 <para><emphasis>Example for function comments:</emphasis></para>
1762 /*********************************************************************
1764 * Function : FUNCTION_NAME
1766 * Description : (Fill me in with a good description!)
1769 * 1 : param1 = pointer to an important thing
1770 * 2 : x = pointer to something else
1772 * Returns : 0 => Ok, everything else is an error.
1774 *********************************************************************/
1775 int FUNCTION_NAME( void *param1, const char *x )
1783 <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1784 able to parse our code to create a "self-documenting" web
1791 <!-- ~~~~~ New section ~~~~~ -->
1792 <sect1 id="cvs"><title>Version Control Guidelines</title>
1793 <para>To be filled. note on cvs comments. Don't only comment what you did,
1794 but also why you did it!
1798 <!-- ~~~~~ New section ~~~~~ -->
1799 <sect1 id="testing"><title>Testing Guidelines</title>
1803 <!-- ~~~~~ New section ~~~~~ -->
1804 <sect2 id="testing-plan"><title>Testplan for releases</title>
1806 Explain release numbers. major, minor. developer releases. etc.
1808 <orderedlist numeration="arabic">
1810 Remove any existing rpm with rpm -e
1813 Remove any file that was left over. This includes (but is not limited to)
1815 <listitem><para>/var/log/privoxy</para></listitem>
1816 <listitem><para>/etc/privoxy</para></listitem>
1817 <listitem><para>/usr/sbin/privoxy</para></listitem>
1818 <listitem><para>/etc/init.d/privoxy</para></listitem>
1819 <listitem><para>/usr/doc/privoxy*</para></listitem>
1823 Install the rpm. Any error messages?
1825 <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1826 (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1827 autostart work?</para></listitem>
1828 <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1829 <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1834 <!-- ~~~~~ New section ~~~~~ -->
1835 <sect2 id="testing-report"><title>Test reports</title>
1837 Please submit test reports only with the <ulink url="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005">test form</ulink>
1838 at sourceforge. Three simple steps:
1841 <listitem><para>Select category: the distribution you test on.</para></listitem>
1842 <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
1843 <listitem><para>Fill the Summary and Detailed Description with something
1844 intelligent (keep it short and precise).</para>
1847 Do not mail to the mailinglist (we cannot keep track on issues there).
1853 <!-- ~~~~~ New section ~~~~~ -->
1854 <sect1 id="newrelease"><title>Releasing a new version</title>
1856 To minimize trouble with distribution contents, webpage
1857 errors and the like, we strongly encourage you
1858 to follow this section if you prepare a new release of
1859 code or new pages on the webserver.
1862 The following programs are required to follow this process:
1863 <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
1864 <filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
1867 Replace X, Y and Z with the actual version number (X = major, Y = minor, Z = point):
1870 <sect2 id="beforerelease">
1871 <title>Before the Release</title>
1873 The following <emphasis>must be done by one of the
1874 developers</emphasis> prior to each new release.
1880 Make sure that everybody who has worked on the code in the last
1881 couple of days has had a chance to yell <quote>no!</quote> in case
1882 they have pending changes/fixes in their pipelines.
1887 Increment the version number in <filename>configure.in</filename> in
1888 CVS. Also, inrease or reset the RPM release number in
1889 <filename>configure.in</filename> as appropriate. Do <emphasis>NOT</emphasis>
1890 touch version information after export from CVS.
1891 <emphasis>All packages</emphasis> will use the version and release data
1892 from <filename>configure.in</filename>.
1893 Local files should not be changed, except prior to a CVS commit!!!
1894 This way we are all on the same page!
1899 If the default actionsfile has changed since last release,
1900 bump up its version info in this line:
1904 {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1908 Then change the version info in doc/webserver/actions/index.php,
1909 line: '$required_actions_file_version = "A.B";'
1914 <emphasis>Commit all files that were changed in the above steps!</emphasis>
1919 Tag all files in CVS with the version number with
1920 <quote><command>cvs tag v_X_Y_Z</command></quote>.
1921 Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1926 The first package uploaded should be the official
1927 <quote>tarball</quote> release. This is built with the
1928 <quote><command>make tarball-dist</command></quote> Makefile
1929 target, and then can be uploaded with
1930 <quote><command>make tarball-upload</command></quote> (see below).
1937 <sect2 id="newrelease-web"><title>Update the webserver</title>
1939 All files must be group-readable and group-writable (or no one else
1940 will be able to change them). To update the webserver, create any
1941 pages locally in the <filename>doc/webserver</filename> directory (or
1942 create new directories under <filename>doc/webserver</filename>), then do
1950 Note that <quote><command>make dok</command></quote>
1951 (or <quote><command>make redhat-dok</command></quote>) creates
1952 <filename>doc/webserver/user-manual</filename>,
1953 <filename>doc/webserver/developer-manual</filename>,
1954 <filename>doc/webserver/faq</filename> and
1955 <filename>doc/webserver/man-page</filename> automatically.
1958 Please do NOT use any other means of transferring files to the
1959 webserver. <quote><command>make webserver</command></quote> not only
1960 uploads, but will make sure that the appropriate permissions are
1961 preserved for shared group access.
1965 <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
1967 Ensure that you have the latest code version. Hence run:
1971 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1972 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1981 autoheader && autoconf && ./configure
1989 make suse-dist or make redhat-dist
1993 To upload the package to Sourceforge, simply issue
1997 make suse-upload or make redhat-upload
2001 Go to the displayed URL and release the file publicly on Sourceforge.
2005 <sect2 id="newrelease-os2"><title>OS/2</title>
2007 Ensure that you have the latest code version. Hence run:
2011 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2012 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2014 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
2018 You will need a mix of development tools.
2019 The main compilation takes place with IBM Visual Age C++.
2020 Some ancillary work takes place with GNU tools, available from
2021 various sources like hobbes.nmsu.edu.
2022 Specificially, you will need <filename>autoheader</filename>,
2023 <filename>autoconf</filename> and <filename>sh</filename> tools.
2024 The packaging takes place with WarpIN, available from various sources, including
2025 its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2028 Change directory to the <filename>os2setup</filename> directory.
2029 Edit the os2build.cmd file to set the final executable filename.
2032 installExeName='privoxyos2_setup_X.Y.Z.exe'
2034 Next, edit the <filename>IJB.wis</filename> file so the release number matches
2035 in the <filename>PACKAGEID</filename> section:
2037 PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2039 You're now ready to build. Run:
2043 And in the <filename>./files</filename> directory you will have the
2044 WarpIN-installable executable.
2045 Upload this anonymously to
2046 <filename>uploads.sourceforge.net/incoming</filename>, create a release
2047 for it, and you're done.
2051 <sect2 id="newrelease-solaris"><title>Solaris</title>
2053 Login to Sourceforge's compilefarm via ssh
2057 ssh cf.sourceforge.net
2061 Choose the right operating system (not the Debian one). If you have
2062 downloaded <application>Privoxy</application> before,
2066 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2067 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2072 If not, please <ulink
2073 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2074 Privoxy via CVS first</ulink>. Run:
2078 autoheader && autoconf && ./configure
2090 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2091 solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2092 to manually upload the archive to Sourceforge's ftp server and release
2097 <sect2 id="newrelease-windows"><title>Windows</title>
2099 You should ensure you have the latest version of Cygwin (from
2100 <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>).
2101 Run the following commands from within a Cygwin bash shell.
2104 First check out a clean copy of the correct code version, by running:
2110 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2111 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z .
2115 (Note: It is important that this is a clean copy of the code,
2116 do not re-use a working directory after you have manually compiled
2120 Then you can build the package. This is fully automated, and is
2121 controlled by <filename>winsetup/GNUmakefile</filename>.
2122 All you need to do is:
2131 Now you can manually rename <filename>privoxy_setup.exe</filename> to
2132 <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
2137 <sect2 id="newrelease-debian"><title>Debian</title>
2139 Ensure that you have the latest code version. Hence run:
2143 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2144 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2153 autoheader && autoconf && ./configure
2161 <sect2 id="newrelease-macosx"><title>Mac OSX</title>
2163 Ensure that you have the latest code version. Hence run:
2167 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2168 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2170 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
2174 From the osxsetup directory, run:
2180 This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
2181 <filename>configure</filename> as well as <filename>make</filename>.
2182 Finally, it will copy over the necessary files to the ./osxsetup/files directory
2183 for further processing by <filename>PackageMaker</filename>.
2186 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
2187 name to match the release, and hit the "Create package" button.
2188 If you specify ./Privoxy.pkg as the output package name, you can then create
2189 the distributable zip file with the command:
2191 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2193 You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
2194 <filename>uploads.sourceforge.net/incoming</filename>,
2195 create a release for it, and you're done.
2199 <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
2201 Change the version number of <application>Privoxy</application> in the
2202 configure.in file. Run:
2204 autoheader && autoconf && ./configure
2209 Login to Sourceforge's compilefarm via ssh:
2213 ssh cf.sourceforge.net
2217 Choose the right operating system.
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 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2244 freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
2245 to manually upload the archive to Sourceforge's ftp server and release
2250 <sect2 id="newrelease-tarball"><title>Tarball</title>
2252 Ensure that you have the right code version. Hence run:
2256 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2257 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2266 autoheader && autoconf && ./configure
2278 To upload the package to Sourceforge, simply issue
2286 Goto the displayed URL and release the file publicly on Sourceforge.
2290 <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
2292 Ensure that you have the latest code version. Hence run:
2296 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2297 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2306 autoheader && autoconf && ./configure
2314 <sect2 id="newrelease-amiga"><title>Amiga OS</title>
2316 Ensure that you have the latest code version. Hence run:
2320 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2321 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2330 autoheader && autoconf && ./configure
2338 <sect2 id="newrelease-aix"><title>AIX</title>
2340 Login to Sourceforge's compilefarm via ssh:
2344 ssh cf.sourceforge.net
2348 Choose the right operating system. If you have downloaded Privoxy
2353 cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2354 cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2359 If not, please <ulink
2360 url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2361 Privoxy via CVS first</ulink>. Run:
2365 autoheader && autoconf && ./configure
2377 which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2378 aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
2379 to manually upload the archive to Sourceforge's ftp server and release
2386 <!-- ~~~~~ New section ~~~~~ -->
2387 <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
2388 <!-- Include contacting.sgml -->
2390 <!-- end contacting -->
2393 <!-- ~~~~~ New section ~~~~~ -->
2394 <sect1 id="copyright"><title>Copyright and History</title>
2396 <sect2><title>Copyright</title>
2397 <!-- Include copyright.sgml -->
2402 <sect2><title>History</title>
2403 <!-- Include history.sgml -->
2410 <!-- ~~~~~ New section ~~~~~ -->
2411 <sect1 id="seealso"><title>See also</title>
2412 <!-- Include seealso.sgml -->
2420 This program is free software; you can redistribute it
2421 and/or modify it under the terms of the GNU General
2422 Public License as published by the Free Software
2423 Foundation; either version 2 of the License, or (at
2424 your option) any later version.
2426 This program is distributed in the hope that it will
2427 be useful, but WITHOUT ANY WARRANTY; without even the
2428 implied warranty of MERCHANTABILITY or FITNESS FOR A
2429 PARTICULAR PURPOSE. See the GNU General Public
2430 License for more details.
2432 The GNU General Public License should be included with
2433 this file. If not, you can view it at
2434 http://www.gnu.org/copyleft/gpl.html
2435 or write to the Free Software Foundation, Inc., 59
2436 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2438 $Log: developer-manual.sgml,v $
2439 Revision 1.31 2002/04/11 09:32:52 oes
2442 Revision 1.30 2002/04/11 09:24:53 oes
2445 Revision 1.29 2002/04/10 18:45:14 swa
2448 Revision 1.28 2002/04/08 22:59:26 hal9
2449 Version update. Spell chkconfig correctly :)
2451 Revision 1.27 2002/04/08 15:31:18 hal9
2452 Touch ups to documentation section.
2454 Revision 1.26 2002/04/07 23:50:08 hal9
2455 Documentation changes to reflect HTML docs now in CVS, and new generated files
2458 Revision 1.25 2002/04/06 05:07:28 hal9
2459 -Add privoxy-man-page.sgml, for man page.
2460 -Add authors.sgml for AUTHORS (and p-authors.sgml)
2461 -Reworked various aspects of various docs.
2462 -Added additional comments to sub-docs.
2464 Revision 1.24 2002/04/04 21:33:37 hal9
2465 More on documenting the documents.
2467 Revision 1.23 2002/04/04 18:46:47 swa
2468 consistent look. reuse of copyright, history et. al.
2470 Revision 1.22 2002/04/04 17:27:56 swa
2471 more single file to be included at multiple points. make maintaining easier
2473 Revision 1.21 2002/04/04 06:48:37 hal9
2474 Structural changes to allow for conditional inclusion/exclusion of content
2475 based on entity toggles, e.g. 'entity % p-not-stable "INCLUDE"'. And
2476 definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2477 eventually be set by Makefile.
2478 More boilerplate text for use across multiple docs.
2480 Revision 1.20 2002/04/04 03:28:27 david__schmidt
2483 Revision 1.19 2002/04/03 15:09:42 david__schmidt
2484 Add OS/2 build section
2486 Revision 1.18 2002/04/03 03:51:48 hal9
2489 Revision 1.17 2002/04/03 01:21:17 hal9
2490 Implementing Andreas's suggestions for Release sections.
2492 Revision 1.16 2002/03/31 23:04:40 hal9
2493 Fleshed out the doc section, and added something for an intro so it was not
2496 Revision 1.15 2002/03/30 22:29:47 swa
2499 Revision 1.14 2002/03/30 19:04:08 swa
2500 people release differently. no good.
2501 I want to make parts of the docs only.
2503 Revision 1.13 2002/03/27 01:16:41 hal9
2506 Revision 1.12 2002/03/27 01:02:51 hal9
2507 Touch up on name change...
2509 Revision 1.11 2002/03/26 22:29:55 swa
2510 we have a new homepage!
2512 Revision 1.10 2002/03/24 12:33:01 swa
2515 Revision 1.9 2002/03/24 11:01:05 swa
2518 Revision 1.8 2002/03/23 15:13:11 swa
2519 renamed every reference to the old name with foobar.
2520 fixed "application foobar application" tag, fixed
2521 "the foobar" with "foobar". left junkbustser in cvs
2522 comments and remarks to history untouched.
2524 Revision 1.7 2002/03/11 13:13:27 swa
2525 correct feedback channels
2527 Revision 1.6 2002/02/24 14:25:06 jongfoster
2528 Formatting changes. Now changing the doctype to DocBook XML 4.1
2529 will work - no other changes are needed.
2531 Revision 1.5 2001/10/31 18:16:51 swa
2532 documentation added: howto generate docs in text and html
2533 format, howto move stuff to the webserver.
2535 Revision 1.4 2001/09/23 10:13:48 swa
2536 upload process established. run make webserver and
2537 the documentation is moved to the webserver. documents
2538 are now linked correctly.
2540 Revision 1.3 2001/09/13 15:27:40 swa
2543 Revision 1.2 2001/09/13 15:20:17 swa
2544 merged standards into developer manual
2546 Revision 1.1 2001/09/12 15:36:41 swa
2547 source files for junkbuster documentation
2549 Revision 1.3 2001/09/10 17:43:59 swa
2550 first proposal of a structure.
2552 Revision 1.2 2001/06/13 14:28:31 swa
2553 docs should have an author.
2555 Revision 1.1 2001/06/13 14:20:37 swa
2556 first import of project's documentation for the webserver.