generated
[privoxy.git] / doc / text / developer-manual.txt
1 Privoxy Developer Manual
2
3 By: Privoxy Developers
4
5 $Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $
6
7 The developer manual gives the users information on how to help the developer
8 team. It provides guidance on coding, testing, documentation and other issues.
9
10 You can find the latest version of the this manual at http://www.privoxy.org/
11 developer-manual/. Please see the Contact section on how to contact the
12 developers.
13
14 -------------------------------------------------------------------------------
15
16 Table of Contents
17  
18 1. Introduction
19 3. Quickstart to Privoxy Development
20 4. The CVS Repository
21    
22     4.1. Access to CVS
23     4.2. CVS Commit Guideline
24     4.3. Discussing Changes First
25    
26 5. Documentation Guidelines
27    
28     5.1. Quickstart to Docbook and SGML
29     5.2. Privoxy Documentation Style
30     5.3. Privoxy Custom Entities
31    
32 6. Coding Guidelines
33    
34     6.1. Introduction
35     6.2. Using Comments
36        
37         6.2.1. Comment, Comment, Comment
38         6.2.2. Use blocks for comments
39         6.2.3. Keep Comments on their own line
40         6.2.4. Comment each logical step
41         6.2.5. Comment All Functions Thoroughly
42         6.2.6. Comment at the end of braces if the content is more than one
43             screen length
44        
45     6.3. Naming Conventions
46        
47         6.3.1. Variable Names
48         6.3.2. Function Names
49         6.3.3. Header file prototypes
50         6.3.4. Enumerations, and #defines
51         6.3.5. Constants
52        
53     6.4. Using Space
54        
55         6.4.1. Put braces on a line by themselves.
56         6.4.2. ALL control statements should have a block
57         6.4.3. Do not belabor/blow-up boolean expressions
58         6.4.4. Use white space freely because it is free
59         6.4.5. Don't use white space around structure operators
60         6.4.6. Make the last brace of a function stand out
61         6.4.7. Use 3 character indentions
62        
63     6.5. Initializing
64        
65         6.5.1. Initialize all variables
66        
67     6.6. Functions
68        
69         6.6.1. Name functions that return a boolean as a question.
70         6.6.2. Always specify a return type for a function.
71         6.6.3. Minimize function calls when iterating by using variables
72         6.6.4. Pass and Return by Const Reference
73         6.6.5. Pass and Return by Value
74         6.6.6. Names of include files
75         6.6.7. Provide multiple inclusion protection
76         6.6.8. Use `extern "C"` when appropriate
77         6.6.9. Where Possible, Use Forward Struct Declaration Instead of
78             Includes
79        
80     6.7. General Coding Practices
81        
82         6.7.1. Turn on warnings
83         6.7.2. Provide a default case for all switch statements
84         6.7.3. Try to avoid falling through cases in a switch statement.
85         6.7.4. Use 'long' or 'short' Instead of 'int'
86         6.7.5. Don't mix size_t and other types
87         6.7.6. Declare each variable and struct on its own line.
88         6.7.7. Use malloc/zalloc sparingly
89         6.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring
90             'free'
91         6.7.9. Add loaders to the `file_list' structure and in order
92         6.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
93        
94     6.8. Addendum: Template for files and function comment blocks:
95    
96 7. Testing Guidelines
97    
98     7.1. Testplan for releases
99     7.2. Test reports
100    
101 8. Releasing a New Version
102    
103     8.1. Before the Release
104     8.2. Building and Releasing the Packages
105        
106         8.2.1. Source Tarball
107         8.2.2. SuSE or Red Hat
108         8.2.3. OS/2
109         8.2.4. Solaris
110         8.2.5. Windows
111         8.2.6. Debian
112         8.2.7. Mac OSX
113         8.2.8. FreeBSD
114         8.2.9. HP-UX 11
115         8.2.10. Amiga OS
116         8.2.11. AIX
117        
118     8.3. After the Release
119    
120 9. Update the Webserver
121 10. Contacting the developers, Bug Reporting and Feature Requests
122    
123     10.1. Get Support
124     10.2. Report bugs
125     10.3. Request new features
126     10.4. Report ads or other filter problems
127     10.5. Other
128    
129 11. Copyright and History
130    
131     11.1. Copyright
132     11.2. History
133    
134 12. See also
135
136 -------------------------------------------------------------------------------
137
138 1. Introduction
139
140 Privoxy, as an heir to Junkbuster, is an Open Source project and licensed under
141 the GPL. As such, Privoxy development is potentially open to anyone who has the
142 time, knowledge, and desire to contribute in any capacity. Our goals are simply
143 to continue the mission, to improve Privoxy, and to make it available to as
144 wide an audience as possible.
145
146 One does not have to be a programmer to contribute. Packaging, testing, and
147 porting, are all important jobs as well.
148
149 -------------------------------------------------------------------------------
150
151 3. Quickstart to Privoxy Development
152
153 You'll need an account on Sourceforge to support our development. Mail your ID
154 to the list and wait until a project manager has added you.
155
156 For the time being (read, this section is under construction), please refer to
157 the extensive comments in the source code.
158
159 -------------------------------------------------------------------------------
160
161 4. The CVS Repository
162
163 If you intend to help us with programming, documentation or packaging you will
164 need write access to our holy grail, the CVS repository. Please read this
165 chapter completely before accessing via CVS.
166
167 -------------------------------------------------------------------------------
168
169 4.1. Access to CVS
170
171 The project's CVS repository is hosted on SourceForge. Please refer to the
172 chapters 6 and 7 in SF's site documentation for the technical access details
173 for your operating system. For historical reasons, the CVS server is called
174 cvs.ijbswa.sourceforge.net, the repository is called ijbswa, and the source
175 tree module is called current.
176
177 -------------------------------------------------------------------------------
178
179 4.2. CVS Commit Guideline
180
181 The source tree is the heart of every software project. Every effort must be
182 made to ensure that it is readable, compilable and consistent at all times. We
183 therefore ask anyone with CVS access to strictly adhere to the following
184 guidelines:
185
186   * Never (read: never, ever) be tempted to commit that small change without
187     testing it thoroughly first. When we're close to a public release, ask a
188     fellow developer to review your changes.
189    
190   * Your commit message should give a concise overview of what you changed (no
191     big details) and why you changed it Just check previous messages for good
192     examples.
193    
194   * Don't use the same message on multiple files, unless it equally applies to
195     all those files.
196    
197   * If your changes span multiple files, and the code won't recompile unless
198     all changes are commited (e.g. when changing the signature of a function),
199     then commit all files one after another, without long delays in beween. If
200     necessary, prepare the commit messages in advance.
201    
202   * Before changing things on CVS, make sure that your changes are in line with
203     the team's general consensus on what should be done (see below).
204    
205 -------------------------------------------------------------------------------
206
207 4.3. Discussing Changes First
208
209 We don't have a too formal policy on this, just use common sense. Hints: If it
210 is..
211
212  1. ..a bugfix / clean-up / cosmetic thing: shoot
213    
214  2. ..a new feature that can be turned off: shoot
215    
216  3. ..a clear improvement w/o side effects on other parts of the code: shoot
217    
218  4. ..a matter of taste: ask the list
219    
220  5. ..a major redesign of some part of the code: ask the list
221    
222 Note that near a major public release, we get a bit more cautious - if unsure,
223 it doesn't hurt to ask first. There is always the possibility to submit a patch
224 to the patches tracker instead.
225
226 -------------------------------------------------------------------------------
227
228 5. Documentation Guidelines
229
230 All formal documents are maintained in Docbook SGML and located in the doc/
231 source/* directory. You will need Docbook, the Docbook DTD's and the Docbook
232 modular stylesheets (or comparable alternatives), and either jade or openjade
233 (recommended) installed in order to build docs from source. Currently there is 
234 user-manual, FAQ, and, of course this, the developer-manual in this format. The
235 README, AUTHORS privoxy.1 (man page) files are also now maintained as Docbook
236 SGML. The finished files are all in the top-level source directory are
237 generated files! Also, index.html, the Privoxy home page, is maintained as
238 SGML. DO NOT edit these directly. Edit the SGML source, or contact someone
239 involved in the documentation (at present Stefan and Hal).
240
241 Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as plain
242 text files in the top-level source directory. At least for the time being.
243
244 Packagers are encouraged to include this documentation. For those without the
245 ability to build the docs locally, text versions of each are kept in CVS. HTML
246 versions are also now being kept in CVS under doc/webserver/*.
247
248 Formal documents are built with the Makefile targets of make dok, or
249 alternately make redhat-dok. If you have problems, try both. The build process
250 uses the document SGML sources in doc/source/*/* to update all text files in
251 doc/text/ and to update all HTML documents in doc/webserver/.
252
253 Documentation writers should please make sure documents build successfully
254 before committing to CVS, if possible.
255
256 How do you update the webserver (i.e. the pages on privoxy.org)?
257
258  1. First, build the docs by running make dok (or alternately make redhat-dok).
259    
260  2. Run make webserver which copies all files from doc/webserver to the
261     sourceforge webserver via scp.
262    
263 Finished docs should be occasionally submitted to CVS (doc/webserver/*/*.html)
264 so that those without the ability to build them locally, have access to them if
265 needed. This is especially important just prior to a new release! Please do
266 this after the $VERSION and other release specific data in configure.in has
267 been updated (this is done just prior to a new release).
268
269 -------------------------------------------------------------------------------
270
271 5.1. Quickstart to Docbook and SGML
272
273 If you are not familiar with SGML, it is a markup language similar to HTML.
274 Actually, not a mark up language per se, but a language used to define markup
275 languages. In fact, HTML is an SGML application. Both will use "tags" to format
276 text and other content. SGML tags can be much more varied, and flexible, but do
277 much of the same kinds of things. The tags, or "elements", are definable in
278 SGML. There is no set "standards". Since we are using Docbook, our tags are
279 those that are defined by Docbook. Much of how the finish document is rendered
280 is determined by the "stylesheets". The stylesheets determine how each tag gets
281 translated to HTML, or other formats.
282
283 Tags in Docbook SGML need to be always "closed". If not, you will likely
284 generate errors. Example: <title>My Title</title>. They are also
285 case-insensitive, but we strongly suggest using all lower case. This keeps
286 compatibility with [Docbook] XML.
287
288 Our documents use "sections" for the most part. Sections will be processed into
289 HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to
290 also generate the Table of Contents for each doc. Our TOC's are set to a depth
291 of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will
292 not. Each section requires a <title> element, and at least one <para>. There is
293 a limit of five section levels in Docbook, but generally three should be
294 sufficient for our purposes.
295
296 Some common elements that you likely will use:
297
298 , paragraph delimiter. Most text needs to be within paragraph elements (there  
299 are some exceptions).                                                          
300 , the stylesheets make this italics.                                           
301 , files and directories.                                                       
302 , command examples.                                                            
303 , like                                                                         
304 , more or less.                                                                
305 , list with bullets.                                                           
306 , member of the above.                                                         
307 , screen output, implies .                                                     
308 , like HTML tag.                                                               
309 , for, doh, quoting text.                                                      
310
311 Look at any of the existing docs for examples of all these and more.
312
313 You might also find "Writing Documentation Using DocBook - A Crash Course"
314 useful.
315
316 -------------------------------------------------------------------------------
317
318 5.2. Privoxy Documentation Style
319
320 It will be easier if everyone follows a similar writing style. This just makes
321 it easier to read what someone else has written if it is all done in a similar
322 fashion.
323
324 Here it is:
325
326   * All tags should be lower case.
327    
328   * Tags delimiting a block of text (even small blocks) should be on their own
329     line. Like:
330    
331      <para>
332       Some text goes here.
333      </para>
334            
335    
336     Tags marking individual words, or few words, should be in-line:
337    
338       Just to <emphasis>emphasize</emphasis>, some text goes here.
339            
340    
341   * Tags should be nested and step indented for block text like: (except
342     in-line tags)
343    
344      <para>
345       <itemizedlist>
346        <para>
347         <listitem>
348           Some text goes here in our list example.
349          </listitem>
350        </para>
351       </itemizedlist>
352      </para>
353            
354    
355     This makes it easier to find the text amongst the tags ;-)
356    
357   * Use white space to separate logical divisions within a document, like
358     between sections. Running everything together consistently makes it harder
359     to read and work on.
360    
361   * Do not hesitate to make comments. Comments can either use the <comment>
362     element, or the <!-- --> style comment familiar from HTML. (Note in Docbook
363     v4.x <comment> is replaced by <remark>.)
364    
365   * We have an international audience. Refrain from slang, or English
366     idiosyncrasies (too many to list :). Humor also does not translate well
367     sometimes.
368    
369   * Try to keep overall line lengths in source files to 80 characters or less
370     for obvious reasons. This is not always possible, with lengthy URLs for
371     instance.
372    
373   * Our documents are available in differing formats. Right now, they are just
374     plain text, and HTML, but PDF, and others is always a future possibility.
375     Be careful with URLs (<ulink>), and avoid this mistake:
376    
377     My favorite site is <ulink url="http://example.com">here</ulink>.
378    
379     This will render as "My favorite site is here", which is not real helpful
380     in a text doc. Better like this:
381    
382     My favorite site is <ulink url="http://example.com">example.com</ulink>.
383    
384   * All documents should be spell checked occasionally. aspell can check SGML
385     with the -H option. (ispell I think too.)
386    
387 -------------------------------------------------------------------------------
388
389 5.3. Privoxy Custom Entities
390
391 Privoxy documentation is using a number of customized "entities" to facilitate
392 documentation maintenance.
393
394 We are using a set of "boilerplate" files with generic text, that is used by
395 multiple docs. This way we can write something once, and use it repeatedly
396 without having to re-write the same content over and over again. If editing
397 such a file, keep in mind that it should be generic. That is the purpose; so it
398 can be used in varying contexts without additional modifications.
399
400 We are also using what Docbook calls "internal entities". These are like
401 variables in programming. Well, sort of. For instance, we have the p-version
402 entity that contains the current Privoxy version string. You are strongly
403 encouraged to use these where possible. Some of these obviously require
404 re-setting with each release (done by the Makefile). A sampling of custom
405 entities are listed below. See any of the main docs for examples.
406
407   * Re- "boilerplate" text entities are defined like:
408    
409     <!entity supported SYSTEM "supported.sgml">
410    
411     In this example, the contents of the file, supported.sgml is available for
412     inclusion anywhere in the doc. To make this happen, just reference the now
413     defined entity: &supported; (starts with an ampersand and ends with a
414     semi-colon), and the contents will be dumped into the finished doc at that
415     point.
416    
417   * Commonly used "internal entities":
418    
419     p-version: the Privoxy version string, e.g. "2.9.14".                      
420     p-status: the project status, either "alpha", "beta", or "stable".         
421     p-not-stable: use to conditionally include text in "not stable" releases   
422     (e.g. "beta").                                                             
423     p-stable: just the opposite.                                               
424     p-text: this doc is only generated as text.                                
425    
426 There are others in various places that are defined for a specific purpose.
427 Read the source!
428
429 -------------------------------------------------------------------------------
430
431 6. Coding Guidelines
432
433 6.1. Introduction
434
435 This set of standards is designed to make our lives easier. It is developed
436 with the simple goal of helping us keep the "new and improved Privoxy"
437 consistent and reliable. Thus making maintenance easier and increasing chances
438 of success of the project.
439
440 And that of course comes back to us as individuals. If we can increase our
441 development and product efficiencies then we can solve more of the request for
442 changes/improvements and in general feel good about ourselves. ;->
443
444 -------------------------------------------------------------------------------
445
446 6.2. Using Comments
447
448 6.2.1. Comment, Comment, Comment
449
450 Explanation:
451
452 Comment as much as possible without commenting the obvious. For example do not
453 comment "aVariable is equal to bVariable". Instead explain why aVariable should
454 be equal to the bVariable. Just because a person can read code does not mean
455 they will understand why or what is being done. A reader may spend a lot more
456 time figuring out what is going on when a simple comment or explanation would
457 have prevented the extra research. Please help your brother IJB'ers out!
458
459 The comments will also help justify the intent of the code. If the comment
460 describes something different than what the code is doing then maybe a
461 programming error is occurring.
462
463 Example:
464
465 /* if page size greater than 1k ... */                                         
466 if ( PageLength() > 1024 )                                                     
467 {                                                                              
468     ... "block" the page up ...                                                
469 }                                                                              
470                                                                                
471 /* if page size is small, send it in blocks */                                 
472 if ( PageLength() > 1024 )                                                     
473 {                                                                              
474     ... "block" the page up ...                                                
475 }                                                                              
476                                                                                
477 This demonstrates 2 cases of "what not to do".  The first is a                 
478 "syntax comment".  The second is a comment that does not fit what              
479 is actually being done.                                                        
480
481 -------------------------------------------------------------------------------
482
483 6.2.2. Use blocks for comments
484
485 Explanation:
486
487 Comments can help or they can clutter. They help when they are differentiated
488 from the code they describe. One line comments do not offer effective
489 separation between the comment and the code. Block identifiers do, by
490 surrounding the code with a clear, definable pattern.
491
492 Example:
493
494 /*********************************************************************         
495  * This will stand out clearly in your code!                                   
496  *********************************************************************/        
497 if ( thisVariable == thatVariable )                                            
498 {                                                                              
499    DoSomethingVeryImportant();                                                 
500 }                                                                              
501                                                                                
502                                                                                
503 /* unfortunately, this may not */                                              
504 if ( thisVariable == thatVariable )                                            
505 {                                                                              
506    DoSomethingVeryImportant();                                                 
507 }                                                                              
508                                                                                
509                                                                                
510 if ( thisVariable == thatVariable ) /* this may not either */                  
511 {                                                                              
512    DoSomethingVeryImportant();                                                 
513 }                                                                              
514
515 Exception:
516
517 If you are trying to add a small logic comment and do not wish to "disrupt" the
518 flow of the code, feel free to use a 1 line comment which is NOT on the same
519 line as the code.
520
521 -------------------------------------------------------------------------------
522
523 6.2.3. Keep Comments on their own line
524
525 Explanation:
526
527 It goes back to the question of readability. If the comment is on the same line
528 as the code it will be harder to read than the comment that is on its own line.
529
530 There are three exceptions to this rule, which should be violated freely and
531 often: during the definition of variables, at the end of closing braces, when
532 used to comment parameters.
533
534 Example:
535
536 /*********************************************************************         
537  * This will stand out clearly in your code,                                   
538  * But the second example won't.                                               
539  *********************************************************************/        
540 if ( thisVariable == thatVariable )                                            
541 {                                                                              
542    DoSomethingVeryImportant();                                                 
543 }                                                                              
544                                                                                
545 if ( thisVariable == thatVariable ) /*can you see me?*/                        
546 {                                                                              
547    DoSomethingVeryImportant(); /*not easily*/                                  
548 }                                                                              
549                                                                                
550                                                                                
551 /*********************************************************************         
552  * But, the encouraged exceptions:                                             
553  *********************************************************************/        
554 int urls_read     = 0;     /* # of urls read + rejected */                     
555 int urls_rejected = 0;     /* # of urls rejected */                            
556                                                                                
557 if ( 1 == X )                                                                  
558 {                                                                              
559    DoSomethingVeryImportant();                                                 
560 }                                                                              
561                                                                                
562                                                                                
563 short DoSomethingVeryImportant(                                                
564    short firstparam,   /* represents something */                              
565    short nextparam     /* represents something else */ )                       
566 {                                                                              
567    ...code here...                                                             
568                                                                                
569 }   /* -END- DoSomethingVeryImportant */                                       
570
571 -------------------------------------------------------------------------------
572
573 6.2.4. Comment each logical step
574
575 Explanation:
576
577 Logical steps should be commented to help others follow the intent of the
578 written code and comments will make the code more readable.
579
580 If you have 25 lines of code without a comment, you should probably go back
581 into it to see where you forgot to put one.
582
583 Most "for", "while", "do", etc... loops _probably_ need a comment. After all,
584 these are usually major logic containers.
585
586 -------------------------------------------------------------------------------
587
588 6.2.5. Comment All Functions Thoroughly
589
590 Explanation:
591
592 A reader of the code should be able to look at the comments just prior to the
593 beginning of a function and discern the reason for its existence and the
594 consequences of using it. The reader should not have to read through the code
595 to determine if a given function is safe for a desired use. The proper
596 information thoroughly presented at the introduction of a function not only
597 saves time for subsequent maintenance or debugging, it more importantly aids in
598 code reuse by allowing a user to determine the safety and applicability of any
599 function for the problem at hand. As a result of such benefits, all functions
600 should contain the information presented in the addendum section of this
601 document.
602
603 -------------------------------------------------------------------------------
604
605 6.2.6. Comment at the end of braces if the content is more than one screen
606 length
607
608 Explanation:
609
610 Each closing brace should be followed on the same line by a comment that
611 describes the origination of the brace if the original brace is off of the
612 screen, or otherwise far away from the closing brace. This will simplify the
613 debugging, maintenance, and readability of the code.
614
615 As a suggestion , use the following flags to make the comment and its brace
616 more readable:
617
618 use following a closing brace: } /* -END- if() or while () or etc... */
619
620 Example:
621
622 if ( 1 == X )                                                                  
623 {                                                                              
624    DoSomethingVeryImportant();                                                 
625    ...some long list of commands...                                            
626 } /* -END- if x is 1 */                                                        
627                                                                                
628 or:                                                                            
629                                                                                
630 if ( 1 == X )                                                                  
631 {                                                                              
632    DoSomethingVeryImportant();                                                 
633    ...some long list of commands...                                            
634 } /* -END- if ( 1 == X ) */                                                    
635
636 -------------------------------------------------------------------------------
637
638 6.3. Naming Conventions
639
640 6.3.1. Variable Names
641
642 Explanation:
643
644 Use all lowercase, and separate words via an underscore ('_'). Do not start an
645 identifier with an underscore. (ANSI C reserves these for use by the compiler
646 and system headers.) Do not use identifiers which are reserved in ANSI C++.
647 (E.g. template, class, true, false, ...). This is in case we ever decide to
648 port Privoxy to C++.
649
650 Example:
651
652 int ms_iis5_hack = 0;                                                          
653
654 Instead of:
655
656 int msiis5hack = 0; int msIis5Hack = 0;                                        
657
658 -------------------------------------------------------------------------------
659
660 6.3.2. Function Names
661
662 Explanation:
663
664 Use all lowercase, and separate words via an underscore ('_'). Do not start an
665 identifier with an underscore. (ANSI C reserves these for use by the compiler
666 and system headers.) Do not use identifiers which are reserved in ANSI C++.
667 (E.g. template, class, true, false, ...). This is in case we ever decide to
668 port Privoxy to C++.
669
670 Example:
671
672 int load_some_file( struct client_state *csp )                                 
673
674 Instead of:
675
676 int loadsomefile( struct client_state *csp )                                   
677 int loadSomeFile( struct client_state *csp )                                   
678
679 -------------------------------------------------------------------------------
680
681 6.3.3. Header file prototypes
682
683 Explanation:
684
685 Use a descriptive parameter name in the function prototype in header files. Use
686 the same parameter name in the header file that you use in the c file.
687
688 Example:
689
690 (.h) extern int load_aclfile( struct client_state *csp );                      
691 (.c) int load_aclfile( struct client_state *csp )                              
692
693 Instead of:
694
695 (.h) extern int load_aclfile( struct client_state * ); or                      
696 (.h) extern int load_aclfile();                                                
697 (.c) int load_aclfile( struct client_state *csp )                              
698
699 -------------------------------------------------------------------------------
700
701 6.3.4. Enumerations, and #defines
702
703 Explanation:
704
705 Use all capital letters, with underscores between words. Do not start an
706 identifier with an underscore. (ANSI C reserves these for use by the compiler
707 and system headers.)
708
709 Example:
710
711 (enumeration) : enum Boolean { FALSE, TRUE };                                  
712 (#define) : #define DEFAULT_SIZE 100;                                          
713
714 Note: We have a standard naming scheme for #defines that toggle a feature in
715 the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word)
716 description.
717
718 Example:
719
720 #define FEATURE_FORCE 1                                                        
721                                                                                
722 #ifdef FEATURE_FORCE                                                           
723 #define FORCE_PREFIX blah                                                      
724 #endif /* def FEATURE_FORCE */                                                 
725
726 -------------------------------------------------------------------------------
727
728 6.3.5. Constants
729
730 Explanation:
731
732 Spell common words out entirely (do not remove vowels).
733
734 Use only widely-known domain acronyms and abbreviations. Capitalize all letters
735 of an acronym.
736
737 Use underscore (_) to separate adjacent acronyms and abbreviations. Never
738 terminate a name with an underscore.
739
740 Example:
741
742 #define USE_IMAGE_LIST 1                                                       
743
744 Instead of:
745
746 #define USE_IMG_LST 1 or                                                       
747 #define _USE_IMAGE_LIST 1 or                                                   
748 #define USE_IMAGE_LIST_ 1 or                                                   
749 #define use_image_list 1 or                                                    
750 #define UseImageList 1                                                         
751
752 -------------------------------------------------------------------------------
753
754 6.4. Using Space
755
756 6.4.1. Put braces on a line by themselves.
757
758 Explanation:
759
760 The brace needs to be on a line all by itself, not at the end of the statement.
761 Curly braces should line up with the construct that they're associated with.
762 This practice makes it easier to identify the opening and closing braces for a
763 block.
764
765 Example:
766
767 if ( this == that )                                                            
768 {                                                                              
769    ...                                                                         
770 }                                                                              
771
772 Instead of:
773
774 if ( this == that ) { ... }
775
776 or
777
778 if ( this == that ) { ... }
779
780 Note: In the special case that the if-statement is inside a loop, and it is
781 trivial, i.e. it tests for a condition that is obvious from the purpose of the
782 block, one-liners as above may optically preserve the loop structure and make
783 it easier to read.
784
785 Status: developer-discretion.
786
787 Example exception:
788
789 while ( more lines are read )                                                  
790 {                                                                              
791    /* Please document what is/is not a comment line here */                    
792    if ( it's a comment ) continue;                                             
793                                                                                
794    do_something( line );                                                       
795 }                                                                              
796
797 -------------------------------------------------------------------------------
798
799 6.4.2. ALL control statements should have a block
800
801 Explanation:
802
803 Using braces to make a block will make your code more readable and less prone
804 to error. All control statements should have a block defined.
805
806 Example:
807
808 if ( this == that )                                                            
809 {                                                                              
810    DoSomething();                                                              
811    DoSomethingElse();                                                          
812 }                                                                              
813
814 Instead of:
815
816 if ( this == that ) DoSomething(); DoSomethingElse();
817
818 or
819
820 if ( this == that ) DoSomething();
821
822 Note: The first example in "Instead of" will execute in a manner other than
823 that which the developer desired (per indentation). Using code braces would
824 have prevented this "feature". The "explanation" and "exception" from the point
825 above also applies.
826
827 -------------------------------------------------------------------------------
828
829 6.4.3. Do not belabor/blow-up boolean expressions
830
831 Example:
832
833 structure->flag = ( condition );                                               
834
835 Instead of:
836
837 if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }
838
839 Note: The former is readable and concise. The later is wordy and inefficient.
840 Please assume that any developer new to the project has at least a "good"
841 knowledge of C/C++. (Hope I do not offend by that last comment ... 8-)
842
843 -------------------------------------------------------------------------------
844
845 6.4.4. Use white space freely because it is free
846
847 Explanation:
848
849 Make it readable. The notable exception to using white space freely is listed
850 in the next guideline.
851
852 Example:
853
854 int firstValue   = 0;                                                          
855 int someValue    = 0;                                                          
856 int anotherValue = 0;                                                          
857 int thisVariable = 0;                                                          
858                                                                                
859 if ( thisVariable == thatVariable )                                            
860                                                                                
861 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )            
862
863 -------------------------------------------------------------------------------
864
865 6.4.5. Don't use white space around structure operators
866
867 Explanation:
868
869 - structure pointer operator ( "->" ) - member operator ( "." ) - functions and
870 parentheses
871
872 It is a general coding practice to put pointers, references, and function
873 parentheses next to names. With spaces, the connection between the object and
874 variable/function name is not as clear.
875
876 Example:
877
878 aStruct->aMember;                                                              
879 aStruct.aMember;                                                               
880 FunctionName();                                                                
881
882 Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
883
884 -------------------------------------------------------------------------------
885
886 6.4.6. Make the last brace of a function stand out
887
888 Example:
889
890 int function1( ... )                                                           
891 {                                                                              
892    ...code...                                                                  
893    return( retCode );                                                          
894                                                                                
895 }   /* -END- function1 */                                                      
896                                                                                
897                                                                                
898 int function2( ... )                                                           
899 {                                                                              
900 }   /* -END- function2 */                                                      
901
902 Instead of:
903
904 int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { }
905
906 Note: Use 1 blank line before the closing brace and 2 lines afterward. This
907 makes the end of function standout to the most casual viewer. Although function
908 comments help separate functions, this is still a good coding practice. In
909 fact, I follow these rules when using blocks in "for", "while", "do" loops, and
910 long if {} statements too. After all whitespace is free!
911
912 Status: developer-discretion on the number of blank lines. Enforced is the end
913 of function comments.
914
915 -------------------------------------------------------------------------------
916
917 6.4.7. Use 3 character indentions
918
919 Explanation:
920
921 If some use 8 character TABs and some use 3 character TABs, the code can look *
922 very* ragged. So use 3 character indentions only. If you like to use TABs, pass
923 your code through a filter such as "expand -t3" before checking in your code.
924
925 Example:
926
927 static const char * const url_code_map[256] =                                  
928 {                                                                              
929    NULL, ...                                                                   
930 };                                                                             
931                                                                                
932                                                                                
933 int function1( ... )                                                           
934 {                                                                              
935    if ( 1 )                                                                    
936    {                                                                           
937       return( ALWAYS_TRUE );                                                   
938    }                                                                           
939    else                                                                        
940    {                                                                           
941       return( HOW_DID_YOU_GET_HERE );                                          
942    }                                                                           
943                                                                                
944    return( NEVER_GETS_HERE );                                                  
945                                                                                
946 }                                                                              
947
948 -------------------------------------------------------------------------------
949
950 6.5. Initializing
951
952 6.5.1. Initialize all variables
953
954 Explanation:
955
956 Do not assume that the variables declared will not be used until after they
957 have been assigned a value somewhere else in the code. Remove the chance of
958 accidentally using an unassigned variable.
959
960 Example:
961
962 short anShort = 0;                                                             
963 float aFloat  = 0;                                                             
964 struct *ptr = NULL;                                                            
965
966 Note: It is much easier to debug a SIGSEGV if the message says you are trying
967 to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a
968 SIGSEV vs. arrayPtr[0].
969
970 Status: developer-discretion if and only if the variable is assigned a value
971 "shortly after" declaration.
972
973 -------------------------------------------------------------------------------
974
975 6.6. Functions
976
977 6.6.1. Name functions that return a boolean as a question.
978
979 Explanation:
980
981 Value should be phrased as a question that would logically be answered as a
982 true or false statement
983
984 Example:
985
986 ShouldWeBlockThis();                                                           
987 ContainsAnImage();                                                             
988 IsWebPageBlank();                                                              
989
990 -------------------------------------------------------------------------------
991
992 6.6.2. Always specify a return type for a function.
993
994 Explanation:
995
996 The default return for a function is an int. To avoid ambiguity, create a
997 return for a function when the return has a purpose, and create a void return
998 type if the function does not need to return anything.
999
1000 -------------------------------------------------------------------------------
1001
1002 6.6.3. Minimize function calls when iterating by using variables
1003
1004 Explanation:
1005
1006 It is easy to write the following code, and a clear argument can be made that
1007 the code is easy to understand:
1008
1009 Example:
1010
1011 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )                        
1012 {                                                                              
1013    ....                                                                        
1014 }                                                                              
1015
1016 Note: Unfortunately, this makes a function call for each and every iteration.
1017 This increases the overhead in the program, because the compiler has to look up
1018 the function each time, call it, and return a value. Depending on what occurs
1019 in the blockListLength() call, it might even be creating and destroying
1020 structures with each iteration, even though in each case it is comparing "cnt"
1021 to the same value, over and over. Remember too - even a call to blockListLength
1022 () is a function call, with the same overhead.
1023
1024 Instead of using a function call during the iterations, assign the value to a
1025 variable, and evaluate using the variable.
1026
1027 Example:
1028
1029 size_t len = blockListLength();                                                
1030                                                                                
1031 for ( size_t cnt = 0; cnt < len; cnt ++ )                                      
1032 {                                                                              
1033    ....                                                                        
1034 }                                                                              
1035
1036 Exceptions: if the value of blockListLength() *may* change or could *
1037 potentially* change, then you must code the function call in the for/while
1038 loop.
1039
1040 -------------------------------------------------------------------------------
1041
1042 6.6.4. Pass and Return by Const Reference
1043
1044 Explanation:
1045
1046 This allows a developer to define a const pointer and call your function. If
1047 your function does not have the const keyword, we may not be able to use your
1048 function. Consider strcmp, if it were defined as: extern int strcmp( char *s1,
1049 char *s2 );
1050
1051 I could then not use it to compare argv's in main: int main( int argc, const
1052 char *argv[] ) { strcmp( argv[0], "privoxy" ); }
1053
1054 Both these pointers are *const*! If the c runtime library maintainers do it, we
1055 should too.
1056
1057 -------------------------------------------------------------------------------
1058
1059 6.6.5. Pass and Return by Value
1060
1061 Explanation:
1062
1063 Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes
1064 or less). Aka, a function declaration like: int load_aclfile( struct
1065 client_state csp )
1066
1067 would not work. So, to be consistent, we should declare all prototypes with
1068 "pass by value": int load_aclfile( struct client_state *csp )
1069
1070 -------------------------------------------------------------------------------
1071
1072 6.6.6. Names of include files
1073
1074 Explanation:
1075
1076 Your include statements should contain the file name without a path. The path
1077 should be listed in the Makefile, using -I as processor directive to search the
1078 indicated paths. An exception to this would be for some proprietary software
1079 that utilizes a partial path to distinguish their header files from system or
1080 other header files.
1081
1082 Example:
1083
1084 #include      /* This is not a local include */                                
1085 #include "config.h"       /* This IS a local include */                        
1086
1087 Exception:
1088
1089 /* This is not a local include, but requires a path element. */                
1090 #include                                                                       
1091
1092 Note: Please! do not add "-I." to the Makefile without a _very_ good reason.
1093 This duplicates the #include "file.h" behavior.
1094
1095 -------------------------------------------------------------------------------
1096
1097 6.6.7. Provide multiple inclusion protection
1098
1099 Explanation:
1100
1101 Prevents compiler and linker errors resulting from redefinition of items.
1102
1103 Wrap each header file with the following syntax to prevent multiple inclusions
1104 of the file. Of course, replace PROJECT_H with your file name, with "." Changed
1105 to "_", and make it uppercase.
1106
1107 Example:
1108
1109 #ifndef PROJECT_H_INCLUDED                                                     
1110 #define PROJECT_H_INCLUDED                                                     
1111  ...                                                                           
1112 #endif /* ndef PROJECT_H_INCLUDED */                                           
1113
1114 -------------------------------------------------------------------------------
1115
1116 6.6.8. Use `extern "C"` when appropriate
1117
1118 Explanation:
1119
1120 If our headers are included from C++, they must declare our functions as
1121 `extern "C"`. This has no cost in C, but increases the potential re-usability
1122 of our code.
1123
1124 Example:
1125
1126 #ifdef __cplusplus                                                             
1127 extern "C"                                                                     
1128 {                                                                              
1129 #endif /* def __cplusplus */                                                   
1130                                                                                
1131 ... function definitions here ...                                              
1132                                                                                
1133 #ifdef __cplusplus                                                             
1134 }                                                                              
1135 #endif /* def __cplusplus */                                                   
1136
1137 -------------------------------------------------------------------------------
1138
1139 6.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
1140
1141 Explanation:
1142
1143 Useful in headers that include pointers to other struct's. Modifications to
1144 excess header files may cause needless compiles.
1145
1146 Example:
1147
1148 /*********************************************************************         
1149  * We're avoiding an include statement here!                                   
1150  *********************************************************************/        
1151 struct file_list;                                                              
1152 extern file_list *xyz;                                                         
1153
1154 Note: If you declare "file_list xyz;" (without the pointer), then including the
1155 proper header file is necessary. If you only want to prototype a pointer,
1156 however, the header file is unnecessary.
1157
1158 Status: Use with discretion.
1159
1160 -------------------------------------------------------------------------------
1161
1162 6.7. General Coding Practices
1163
1164 6.7.1. Turn on warnings
1165
1166 Explanation
1167
1168 Compiler warnings are meant to help you find bugs. You should turn on as many
1169 as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as
1170 possible.
1171
1172 -------------------------------------------------------------------------------
1173
1174 6.7.2. Provide a default case for all switch statements
1175
1176 Explanation:
1177
1178 What you think is guaranteed is never really guaranteed. The value that you
1179 don't think you need to check is the one that someday will be passed. So, to
1180 protect yourself from the unknown, always have a default step in a switch
1181 statement.
1182
1183 Example:
1184
1185 switch( hash_string( cmd ) )                                                   
1186 {                                                                              
1187    case hash_actions_file :                                                    
1188       ... code ...                                                             
1189       break;                                                                   
1190                                                                                
1191    case hash_confdir :                                                         
1192       ... code ...                                                             
1193       break;                                                                   
1194                                                                                
1195    default :                                                                   
1196       log_error( ... );                                                        
1197       ... anomaly code goes here ...                                           
1198       continue; / break; / exit( 1 ); / etc ...                                
1199                                                                                
1200 } /* end switch( hash_string( cmd ) ) */                                       
1201
1202 Note: If you already have a default condition, you are obviously exempt from
1203 this point. Of note, most of the WIN32 code calls `DefWindowProc' after the
1204 switch statement. This API call *should* be included in a default statement.
1205
1206 Another Note: This is not so much a readability issue as a robust programming
1207 issue. The "anomaly code goes here" may be no more than a print to the STDERR
1208 stream (as in load_config). Or it may really be an ABEND condition.
1209
1210 Status: Programmer discretion is advised.
1211
1212 -------------------------------------------------------------------------------
1213
1214 6.7.3. Try to avoid falling through cases in a switch statement.
1215
1216 Explanation:
1217
1218 In general, you will want to have a 'break' statement within each 'case' of a
1219 switch statement. This allows for the code to be more readable and
1220 understandable, and furthermore can prevent unwanted surprises if someone else
1221 later gets creative and moves the code around.
1222
1223 The language allows you to plan the fall through from one case statement to
1224 another simply by omitting the break statement within the case statement. This
1225 feature does have benefits, but should only be used in rare cases. In general,
1226 use a break statement for each case statement.
1227
1228 If you choose to allow fall through, you should comment both the fact of the
1229 fall through and reason why you felt it was necessary.
1230
1231 -------------------------------------------------------------------------------
1232
1233 6.7.4. Use 'long' or 'short' Instead of 'int'
1234
1235 Explanation:
1236
1237 On 32-bit platforms, int usually has the range of long. On 16-bit platforms,
1238 int has the range of short.
1239
1240 Status: open-to-debate. In the case of most FSF projects (including X/
1241 GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I
1242 forget the exact typedefs now). Should we add these to IJB now that we have a
1243 "configure" script?
1244
1245 -------------------------------------------------------------------------------
1246
1247 6.7.5. Don't mix size_t and other types
1248
1249 Explanation:
1250
1251 The type of size_t varies across platforms. Do not make assumptions about
1252 whether it is signed or unsigned, or about how long it is. Do not compare a
1253 size_t against another variable of a different type (or even against a
1254 constant) without casting one of the values. Try to avoid using size_t if you
1255 can.
1256
1257 -------------------------------------------------------------------------------
1258
1259 6.7.6. Declare each variable and struct on its own line.
1260
1261 Explanation:
1262
1263 It can be tempting to declare a series of variables all on one line. Don't.
1264
1265 Example:
1266
1267 long a = 0;                                                                    
1268 long b = 0;                                                                    
1269 long c = 0;                                                                    
1270
1271 Instead of:
1272
1273 long a, b, c;
1274
1275 Explanation: - there is more room for comments on the individual variables -
1276 easier to add new variables without messing up the original ones - when
1277 searching on a variable to find its type, there is less clutter to "visually"
1278 eliminate
1279
1280 Exceptions: when you want to declare a bunch of loop variables or other trivial
1281 variables; feel free to declare them on 1 line. You should, although, provide a
1282 good comment on their functions.
1283
1284 Status: developer-discretion.
1285
1286 -------------------------------------------------------------------------------
1287
1288 6.7.7. Use malloc/zalloc sparingly
1289
1290 Explanation:
1291
1292 Create a local struct (on the stack) if the variable will live and die within
1293 the context of one function call.
1294
1295 Only "malloc" a struct (on the heap) if the variable's life will extend beyond
1296 the context of one function call.
1297
1298 Example:
1299
1300 If a function creates a struct and stores a pointer to it in a                 
1301 list, then it should definitely be allocated via `malloc'.                     
1302
1303 -------------------------------------------------------------------------------
1304
1305 6.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
1306
1307 Explanation:
1308
1309 If you have to "malloc" an instance, you are responsible for insuring that the
1310 instance is `free'd, even if the deallocation event falls within some other
1311 programmer's code. You are also responsible for ensuring that deletion is
1312 timely (i.e. not too soon, not too late). This is known as "low-coupling" and
1313 is a "good thing (tm)". You may need to offer a free/unload/destuctor type
1314 function to accommodate this.
1315
1316 Example:
1317
1318 int load_re_filterfile( struct client_state *csp ) { ... }                     
1319 static void unload_re_filterfile( void *f ) { ... }                            
1320
1321 Exceptions:
1322
1323 The developer cannot be expected to provide `free'ing functions for C run-time
1324 library functions ... such as `strdup'.
1325
1326 Status: developer-discretion. The "main" use of this standard is for allocating
1327 and freeing data structures (complex or nested).
1328
1329 -------------------------------------------------------------------------------
1330
1331 6.7.9. Add loaders to the `file_list' structure and in order
1332
1333 Explanation:
1334
1335 I have ordered all of the "blocker" file code to be in alpha order. It is
1336 easier to add/read new blockers when you expect a certain order.
1337
1338 Note: It may appear that the alpha order is broken in places by POPUP tests
1339 coming before PCRS tests. But since POPUPs can also be referred to as
1340 KILLPOPUPs, it is clear that it should come first.
1341
1342 -------------------------------------------------------------------------------
1343
1344 6.7.10. "Uncertain" new code and/or changes to existing code, use FIXME
1345
1346 Explanation:
1347
1348 If you have enough confidence in new code or confidence in your changes, but
1349 are not *quite* sure of the repercussions, add this:
1350
1351 /* FIXME: this code has a logic error on platform XYZ, * attempting to fix */ #
1352 ifdef PLATFORM ...changed code here... #endif
1353
1354 or:
1355
1356 /* FIXME: I think the original author really meant this... */ ...changed code
1357 here...
1358
1359 or:
1360
1361 /* FIXME: new code that *may* break something else... */ ...new code here...
1362
1363 Note: If you make it clear that this may or may not be a "good thing (tm)", it
1364 will be easier to identify and include in the project (or conversely exclude
1365 from the project).
1366
1367 -------------------------------------------------------------------------------
1368
1369 6.8. Addendum: Template for files and function comment blocks:
1370
1371 Example for file comments:
1372
1373 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $"; 
1374 /*********************************************************************                         
1375  *                                                                                             
1376  * File        :  $Source$                                                                     
1377  *                                                                                             
1378  * Purpose     :  (Fill me in with a good description!)                                        
1379  *                                                                                             
1380  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge                            
1381  *                Privoxy team. http://www.privoxy.org/                                        
1382  *                                                                                             
1383  *                Based on the Internet Junkbuster originally written                          
1384  *                by and Copyright (C) 1997 Anonymous Coders and                               
1385  *                Junkbusters Corporation.  http://www.junkbusters.com                         
1386  *                                                                                             
1387  *                This program is free software; you can redistribute it                       
1388  *                and/or modify it under the terms of the GNU General                          
1389  *                Public License as published by the Free Software                             
1390  *                Foundation; either version 2 of the License, or (at                          
1391  *                your option) any later version.                                              
1392  *                                                                                             
1393  *                This program is distributed in the hope that it will                         
1394  *                be useful, but WITHOUT ANY WARRANTY; without even the                        
1395  *                implied warranty of MERCHANTABILITY or FITNESS FOR A                         
1396  *                PARTICULAR PURPOSE.  See the GNU General Public                              
1397  *                License for more details.                                                    
1398  *                                                                                             
1399  *                The GNU General Public License should be included with                       
1400  *                this file.  If not, you can view it at                                       
1401  *                http://www.gnu.org/copyleft/gpl.html                                         
1402  *                or write to the Free Software Foundation, Inc., 59                           
1403  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.                       
1404  *                                                                                             
1405  * Revisions   :                                                                               
1406  *    $Log$                                                                                    
1407  *                                                                                             
1408  *********************************************************************/                        
1409                                                                                                
1410                                                                                                
1411 #include "config.h"                                                                            
1412                                                                                                
1413    ...necessary include files for us to do our work...                                         
1414                                                                                                
1415 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;                                              
1416
1417 Note: This declares the rcs variables that should be added to the
1418 "show-proxy-args" page. If this is a brand new creation by you, you are free to
1419 change the "Copyright" section to represent the rights you wish to maintain.
1420
1421 Note: The formfeed character that is present right after the comment flower box
1422 is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of
1423 the code (via `forward-page' and `backward-page'). Please include it if you
1424 can.
1425
1426 Example for file header comments:
1427
1428 #ifndef _FILENAME_H                                                                          
1429 #define _FILENAME_H                                                                          
1430 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.37 2002/04/26 17:23:29 swa Exp $" 
1431 /*********************************************************************                       
1432  *                                                                                           
1433  * File        :  $Source$                                                                   
1434  *                                                                                           
1435  * Purpose     :  (Fill me in with a good description!)                                      
1436  *                                                                                           
1437  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge                          
1438  *                Privoxy team. http://www.privoxy.org/                                      
1439  *                                                                                           
1440  *                Based on the Internet Junkbuster originally written                        
1441  *                by and Copyright (C) 1997 Anonymous Coders and                             
1442  *                Junkbusters Corporation.  http://www.junkbusters.com                       
1443  *                                                                                           
1444  *                This program is free software; you can redistribute it                     
1445  *                and/or modify it under the terms of the GNU General                        
1446  *                Public License as published by the Free Software                           
1447  *                Foundation; either version 2 of the License, or (at                        
1448  *                your option) any later version.                                            
1449  *                                                                                           
1450  *                This program is distributed in the hope that it will                       
1451  *                be useful, but WITHOUT ANY WARRANTY; without even the                      
1452  *                implied warranty of MERCHANTABILITY or FITNESS FOR A                       
1453  *                PARTICULAR PURPOSE.  See the GNU General Public                            
1454  *                License for more details.                                                  
1455  *                                                                                           
1456  *                The GNU General Public License should be included with                     
1457  *                this file.  If not, you can view it at                                     
1458  *                http://www.gnu.org/copyleft/gpl.html                                       
1459  *                or write to the Free Software Foundation, Inc., 59                         
1460  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.                     
1461  *                                                                                           
1462  * Revisions   :                                                                             
1463  *    $Log$                                                                                  
1464  *                                                                                           
1465  *********************************************************************/                      
1466                                                                                              
1467                                                                                              
1468 #include "project.h"                                                                         
1469                                                                                              
1470 #ifdef __cplusplus                                                                           
1471 extern "C" {                                                                                 
1472 #endif                                                                                       
1473                                                                                              
1474    ... function headers here ...                                                             
1475                                                                                              
1476                                                                                              
1477 /* Revision control strings from this header and associated .c file */                       
1478 extern const char FILENAME_rcs[];                                                            
1479 extern const char FILENAME_h_rcs[];                                                          
1480                                                                                              
1481                                                                                              
1482 #ifdef __cplusplus                                                                           
1483 } /* extern "C" */                                                                           
1484 #endif                                                                                       
1485                                                                                              
1486 #endif /* ndef _FILENAME_H */                                                                
1487                                                                                              
1488 /*                                                                                           
1489   Local Variables:                                                                           
1490   tab-width: 3                                                                               
1491   end:                                                                                       
1492 */                                                                                           
1493
1494 Example for function comments:
1495
1496 /*********************************************************************         
1497  *                                                                             
1498  * Function    :  FUNCTION_NAME                                                
1499  *                                                                             
1500  * Description :  (Fill me in with a good description!)                        
1501  *                                                                             
1502  * parameters  :                                                               
1503  *          1  :  param1 = pointer to an important thing                       
1504  *          2  :  x      = pointer to something else                           
1505  *                                                                             
1506  * Returns     :  0 => Ok, everything else is an error.                        
1507  *                                                                             
1508  *********************************************************************/        
1509 int FUNCTION_NAME( void *param1, const char *x )                               
1510 {                                                                              
1511    ...                                                                         
1512    return( 0 );                                                                
1513                                                                                
1514 }                                                                              
1515
1516 Note: If we all follow this practice, we should be able to parse our code to
1517 create a "self-documenting" web page.
1518
1519 -------------------------------------------------------------------------------
1520
1521 7. Testing Guidelines
1522
1523 To be filled.
1524
1525 -------------------------------------------------------------------------------
1526
1527 7.1. Testplan for releases
1528
1529 Explain release numbers. major, minor. developer releases. etc.
1530
1531  1. Remove any existing rpm with rpm -e
1532    
1533  2. Remove any file that was left over. This includes (but is not limited to)
1534    
1535       + /var/log/privoxy
1536        
1537       + /etc/privoxy
1538        
1539       + /usr/sbin/privoxy
1540        
1541       + /etc/init.d/privoxy
1542        
1543       + /usr/doc/privoxy*
1544        
1545  3. Install the rpm. Any error messages?
1546    
1547  4. start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/
1548     privoxy stop). Reboot your machine. Does autostart work?
1549    
1550  5. Start browsing. Does Privoxy work? Logfile written?
1551    
1552  6. Remove the rpm. Any error messages? All files removed?
1553    
1554 -------------------------------------------------------------------------------
1555
1556 7.2. Test reports
1557
1558 Please submit test reports only with the test form at sourceforge. Three simple
1559 steps:
1560
1561   * Select category: the distribution you test on.
1562    
1563   * Select group: the version of Privoxy that we are about to release.
1564    
1565   * Fill the Summary and Detailed Description with something intelligent (keep
1566     it short and precise).
1567    
1568 Do not mail to the mailinglist (we cannot keep track on issues there).
1569
1570 -------------------------------------------------------------------------------
1571
1572 8. Releasing a New Version
1573
1574 When we release versions of Privoxy, our work leaves our cozy secret lab and
1575 has to work in the cold RealWorld[tm]. Once it is released, there is no way to
1576 call it back, so it is very important that great care is taken to ensure that
1577 everything runs fine, and not to introduce problems in the very last minute.
1578
1579 So when releasing a new version, please adhere exactly to the procedure
1580 outlined in this chapter.
1581
1582 The following programs are required to follow this process: ncftpput (ncftp),
1583 scp, ssh (ssh), gmake (GNU's version of make), autoconf, cvs.
1584
1585 In the following text, replace X, Y and Z with the actual version number (X =
1586 major, Y = minor, Z = point):
1587
1588 -------------------------------------------------------------------------------
1589
1590 8.1. Before the Release
1591
1592 The following must be done by one of the developers prior to each new release.
1593
1594   * Make sure that everybody who has worked on the code in the last couple of
1595     days has had a chance to yell "no!" in case they have pending changes/fixes
1596     in their pipelines.
1597    
1598   * Increment the version number and increase or reset the RPM release number
1599     in configure.in as appropriate.
1600    
1601   * If the default actionsfile has changed since last release, bump up its
1602     version info in this line:
1603    
1604       {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}    
1605    
1606     Then change the version info in doc/webserver/actions/index.php, line:
1607     '$required_actions_file_version = "A.B";'
1608    
1609   * If the HTML documentation is not in sync with the SGML sources you need to
1610     regenerate it. (If in doubt, just do it.) See the Section "Updating the
1611     webserver" in this manual for details.
1612    
1613   * Commit all files that were changed in the above steps!
1614    
1615   * Tag all files in CVS with the version number with "cvs tag v_X_Y_Z". Don't
1616     use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1617    
1618 -------------------------------------------------------------------------------
1619
1620 8.2. Building and Releasing the Packages
1621
1622 Now the individual packages can be built and released. Note that for GPL
1623 reasons the first package to be released is always the source tarball.
1624
1625 For all types of packages, including the source tarball, you must make sure
1626 that you build from clean sources by exporting the right version from CVS into
1627 an empty directory:.
1628
1629   mkdir dist # delete or choose different name if it already exists                                
1630   cd dist                                                                                          
1631   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login                        
1632   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
1633
1634 Do NOT change a single bit, including, but not limited to version information
1635 after export from CVS. This is to make sure that all release packages, and with
1636 them, all future bug reports, are based on exactly the same code.
1637
1638 Please find additional instructions for the source tarball and the individual
1639 platform dependent binary packages below.
1640
1641 -------------------------------------------------------------------------------
1642
1643 8.2.1. Source Tarball
1644
1645 First, make sure that you have freshly exported the right version into an empty
1646 directory. (See "Building and releasing packages" above). Then run:
1647
1648   cd current                                                                   
1649   autoheader && autoconf && ./configure                                        
1650
1651 Then do:
1652
1653   make tarball-dist                                                            
1654
1655 To upload the package to Sourceforge, simply issue
1656
1657   make tarball-upload                                                          
1658
1659 Go to the displayed URL and release the file publicly on Sourceforge. For the
1660 change log field, use the relevant section of the ChangeLog file.
1661
1662 -------------------------------------------------------------------------------
1663
1664 8.2.2. SuSE or Red Hat
1665
1666 First, make sure that you have freshly exported the right version into an empty
1667 directory. (See "Building and releasing packages" above). Then run:
1668
1669   cd current                                                                   
1670   autoheader && autoconf && ./configure                                        
1671
1672 Then do
1673
1674   make suse-dist (or make redhat-dist)                                         
1675
1676 To upload the package to Sourceforge, simply issue
1677
1678   make suse-upload (or make redhat-upload)                                     
1679
1680 Go to the displayed URL and release the file publicly on Sourceforge. Use the
1681 release notes and Ã§hange log from the source tarball package.
1682
1683 -------------------------------------------------------------------------------
1684
1685 8.2.3. OS/2
1686
1687 First, make sure that you have freshly exported the right version into an empty
1688 directory. (See "Building and releasing packages" above). Then get the OS/2
1689 Setup module:
1690
1691   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
1692
1693 You will need a mix of development tools. The main compilation takes place with
1694 IBM Visual Age C++. Some ancillary work takes place with GNU tools, available
1695 from various sources like hobbes.nmsu.edu. Specificially, you will need
1696 autoheader, autoconf and sh tools. The packaging takes place with WarpIN,
1697 available from various sources, including its home page: xworkplace.
1698
1699 Change directory to the os2setup directory. Edit the os2build.cmd file to set
1700 the final executable filename. For example,
1701
1702   installExeName='privoxyos2_setup_X.Y.Z.exe'                                  
1703
1704 Next, edit the IJB.wis file so the release number matches in the PACKAGEID
1705 section:
1706
1707   PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"                       
1708
1709 You're now ready to build. Run:
1710
1711   os2build                                                                     
1712
1713 You will find the WarpIN-installable executable in the ./files directory.
1714 Upload this anonymously to uploads.sourceforge.net/incoming, create a release
1715 for it, and you're done. Use the release notes and Change Log from the source
1716 tarball package.
1717
1718 -------------------------------------------------------------------------------
1719
1720 8.2.4. Solaris
1721
1722 Login to Sourceforge's compilefarm via ssh:
1723
1724   ssh cf.sourceforge.net                                                       
1725
1726 Choose the right operating system (not the Debian one). When logged in, make
1727 sure that you have freshly exported the right version into an empty directory.
1728 (See "Building and releasing packages" above). Then run:
1729
1730   cd current                                                                   
1731   autoheader && autoconf && ./configure                                        
1732
1733 Then run
1734
1735   gmake solaris-dist                                                           
1736
1737 which creates a gzip'ed tar archive. Sadly, you cannot use make solaris-upload
1738 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1739 archive to Sourceforge's ftp server and release the file publicly. Use the
1740 release notes and Change Log from the source tarball package.
1741
1742 -------------------------------------------------------------------------------
1743
1744 8.2.5. Windows
1745
1746 You should ensure you have the latest version of Cygwin (from http://
1747 www.cygwin.com/). Run the following commands from within a Cygwin bash shell.
1748
1749 First, make sure that you have freshly exported the right version into an empty
1750 directory. (See "Building and releasing packages" above). Then get the Windows
1751 setup module:
1752
1753         cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
1754
1755 Then you can build the package. This is fully automated, and is controlled by
1756 winsetup/GNUmakefile. All you need to do is:
1757
1758         cd winsetup                                                            
1759         make                                                                   
1760
1761 Now you can manually rename privoxy_setup.exe to privoxy_setup_X_Y_Z.exe, and
1762 upload it to SourceForge. When releasing the package on SourceForge, use the
1763 release notes and Change Log from the source tarball package.
1764
1765 -------------------------------------------------------------------------------
1766
1767 8.2.6. Debian
1768
1769 First, make sure that you have freshly exported the right version into an empty
1770 directory. (See "Building and releasing packages" above). Then, run:
1771
1772   cd current                                                                   
1773   autoheader && autoconf && ./configure                                        
1774
1775 Then do FIXME.
1776
1777 -------------------------------------------------------------------------------
1778
1779 8.2.7. Mac OSX
1780
1781 First, make sure that you have freshly exported the right version into an empty
1782 directory. (See "Building and releasing packages" above). Then get the Mac OSX
1783 setup module:
1784
1785   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
1786
1787 Then run:
1788
1789   cd osxsetup                                                                  
1790   build                                                                        
1791
1792 This will run autoheader, autoconf and configure as well as make. Finally, it
1793 will copy over the necessary files to the ./osxsetup/files directory for
1794 further processing by PackageMaker.
1795
1796 Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the
1797 package name to match the release, and hit the "Create package" button. If you
1798 specify ./Privoxy.pkg as the output package name, you can then create the
1799 distributable zip file with the command:
1800
1801 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg                                  
1802
1803 You can then upload privoxyosx_setup_x.y.z.zip anonymously to
1804 uploads.sourceforge.net/incoming, create a release for it, and you're done. Use
1805 the release notes and Change Log from the source tarball package.
1806
1807 -------------------------------------------------------------------------------
1808
1809 8.2.8. FreeBSD
1810
1811 Login to Sourceforge's compilefarm via ssh:
1812
1813   ssh cf.sourceforge.net                                                       
1814
1815 Choose the right operating system. When logged in, make sure that you have
1816 freshly exported the right version into an empty directory. (See "Building and
1817 releasing packages" above). Then run:
1818
1819   cd current                                                                   
1820   autoheader && autoconf && ./configure                                        
1821
1822 Then run:
1823
1824   gmake freebsd-dist                                                           
1825
1826 which creates a gzip'ed tar archive. Sadly, you cannot use make freebsd-upload
1827 on the Sourceforge machine (no ncftpput). You now have to manually upload the
1828 archive to Sourceforge's ftp server and release the file publicly. Use the
1829 release notes and Change Log from the source tarball package.
1830
1831 -------------------------------------------------------------------------------
1832
1833 8.2.9. HP-UX 11
1834
1835 First, make sure that you have freshly exported the right version into an empty
1836 directory. (See "Building and releasing packages" above). Then run:
1837
1838   cd current                                                                   
1839   autoheader && autoconf && ./configure                                        
1840
1841 Then do FIXME.
1842
1843 -------------------------------------------------------------------------------
1844
1845 8.2.10. Amiga OS
1846
1847 First, make sure that you have freshly exported the right version into an empty
1848 directory. (See "Building and releasing packages" above). Then run:
1849
1850   cd current                                                                   
1851   autoheader && autoconf && ./configure                                        
1852
1853 Then do FIXME.
1854
1855 -------------------------------------------------------------------------------
1856
1857 8.2.11. AIX
1858
1859 Login to Sourceforge's compilefarm via ssh:
1860
1861   ssh cf.sourceforge.net                                                       
1862
1863 Choose the right operating system. When logged in, make sure that you have
1864 freshly exported the right version into an empty directory. (See "Building and
1865 releasing packages" above). Then run:
1866
1867   cd current                                                                   
1868   autoheader && autoconf && ./configure                                        
1869
1870 Then run:
1871
1872   make aix-dist                                                                
1873
1874 which creates a gzip'ed tar archive. Sadly, you cannot use make aix-upload on
1875 the Sourceforge machine (no ncftpput). You now have to manually upload the
1876 archive to Sourceforge's ftp server and release the file publicly. Use the
1877 release notes and Change Log from the source tarball package.
1878
1879 -------------------------------------------------------------------------------
1880
1881 8.3. After the Release
1882
1883 When all (or: most of the) packages have been uploaded and made available, send
1884 an email to the announce mailing list, Subject: "Version X.Y.Z available for
1885 download". Be sure to include the download location, the release notes and the
1886 change log.
1887
1888 -------------------------------------------------------------------------------
1889
1890 9. Update the Webserver
1891
1892 When updating the webserver, please follow these steps to make sure that no
1893 broken links, incosistent contents or permission problems will occur:
1894
1895 If you have changed anything in the documentation source SGML files, do:
1896
1897   make dok # (or make redkat-dok if make dok doesn't work for you)             
1898
1899 That will generate doc/webserver/user-manual, doc/webserver/developer-manual,
1900 doc/webserver/faq and doc/webserver/index.html automatically.
1901
1902 If you changed the manual page source, generate doc/webserver/man-page/
1903 privoxy-man-page.html by running "make man". (This is a separate target due to
1904 dependencies on some obscure perl scripts. See comments in GNUmakefile.)
1905
1906 If you want to add new files to the webserver, create them locally in the doc/
1907 webserver/* directory (or create new directories under doc/webserver).
1908
1909 Next, commit any changes from the above steps to CVS. All set? Then do
1910
1911   make webserver                                                               
1912
1913 This will do the upload to the webserver (www.privoxy.org) and ensure all files
1914 and directories there are group writable.
1915
1916 Please do NOT use any other means of transferring files to the webserver to
1917 avoid permission problems.
1918
1919 -------------------------------------------------------------------------------
1920
1921 10. Contacting the developers, Bug Reporting and Feature Requests
1922
1923 We value your feedback. However, to provide you with the best support, please
1924 note the following sections.
1925
1926 -------------------------------------------------------------------------------
1927
1928 10.1. Get Support
1929
1930 To get support, use the Sourceforge Support Forum:
1931
1932     http://sourceforge.net/tracker/?group_id=11118&atid=211118
1933    
1934
1935 -------------------------------------------------------------------------------
1936
1937 10.2. Report bugs
1938
1939 To submit bugs, use the Sourceforge Bug Forum:
1940
1941     http://sourceforge.net/tracker/?group_id=11118&atid=111118. 
1942     
1943
1944 Make sure that the bug has not already been submitted. Please try to verify
1945 that it is a Privoxy bug, and not a browser or site bug first. If you are using
1946 your own custom configuration, please try the stock configs to see if the
1947 problem is a configuration related bug. And if not using the latest development
1948 snapshot, please try the latest one. Or even better, CVS sources. Please be
1949 sure to include the Privoxy version, platform, browser, any pertinent log data,
1950 any other relevant details (please be specific) and, if possible, some way to
1951 reproduce the bug.
1952
1953 -------------------------------------------------------------------------------
1954
1955 10.3. Request new features
1956
1957 To submit ideas on new features, use the Sourceforge feature request forum:
1958
1959     http://sourceforge.net/tracker/?atid=361118&group_id=11118&func=browse.
1960    
1961
1962 -------------------------------------------------------------------------------
1963
1964 10.4. Report ads or other filter problems
1965
1966 You can also send feedback on websites that Privoxy has problems with. Please
1967 bookmark the following link: "Privoxy - Submit Filter Feedback". Once you surf
1968 to a page with problems, use the bookmark to send us feedback. We will look
1969 into the issue as soon as possible.
1970
1971 New, improved default.action files will occasionally be made available based on
1972 your feedback. These will be announced on the ijbswa-announce list.
1973
1974 -------------------------------------------------------------------------------
1975
1976 10.5. Other
1977
1978 For any other issues, feel free to use the mailing lists:
1979  
1980     http://sourceforge.net/mail/?group_id=11118.
1981  
1982
1983 Anyone interested in actively participating in development and related
1984 discussions can also join the appropriate mailing list. Archives are available,
1985 too. See the page on Sourceforge.
1986
1987 -------------------------------------------------------------------------------
1988
1989 11. Copyright and History
1990
1991 11.1. Copyright
1992
1993 Privoxy is free software; you can redistribute it and/or modify it under the
1994 terms of the GNU General Public License as published by the Free Software
1995 Foundation; either version 2 of the License, or (at your option) any later
1996 version.
1997
1998 This program is distributed in the hope that it will be useful, but WITHOUT ANY
1999 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
2000 PARTICULAR PURPOSE. See the GNU General Public License for more details, which
2001 is available from the Free Software Foundation, Inc, 59 Temple Place - Suite
2002 330, Boston, MA 02111-1307, USA.
2003
2004 You should have received a copy of the GNU General Public License along with
2005 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
2006 Place, Suite 330, Boston, MA 02111-1307 USA.
2007
2008 -------------------------------------------------------------------------------
2009
2010 11.2. History
2011
2012 Privoxy is evolved, and derived from, the Internet Junkbuster, with many
2013 improvments and enhancements over the original.
2014
2015 Junkbuster was originally written by Anonymous Coders and Junkbusters
2016 Corporation, and was released as free open-source software under the GNU GPL. 
2017 Stefan Waldherr made many improvements, and started the SourceForge project
2018 Privoxy to rekindle development. There are now several active developers
2019 contributing. The last stable release of Junkbuster was v2.0.2, which has now
2020 grown whiskers ;-).
2021
2022 -------------------------------------------------------------------------------
2023
2024 12. See also
2025
2026 Other references and sites of interest to Privoxy users:
2027
2028 http://www.privoxy.org/, The Privoxy Home page.
2029
2030 http://sourceforge.net/projects/ijbswa, the Project Page for Privoxy on        
2031 Sourceforge.                                                                   
2032
2033 http://p.p/, access Privoxy from your browser. Alternately, http://            
2034 config.privoxy.org may work in some situations where the first does not.       
2035
2036 http://p.p/, and select "actions file feedback system" to submit "misses" to   
2037 the developers.                                                                
2038
2039 http://www.junkbusters.com/ht/en/cookies.html
2040
2041 http://www.waldherr.org/junkbuster/
2042
2043 http://privacy.net/analyze/
2044
2045 http://www.squid-cache.org/
2046
2047  
2048