-Junkbuster Developer Manual
+Privoxy Developer Manual
- By: Junkbuster Developers
+ By: Privoxy Developers
- $Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:48 swa Exp $
+ $Id: developer-manual.sgml,v 1.9 2002/03/24 11:01:05 swa Exp $
The developer manual gives the users information on how to help the
developer team. It provides guidance on coding, testing, documentation
- and other issues. The Internet Junkbuster is an application that
- provides privacy and security to the user of the world wide web.
+ and other issues. Privoxy is a web proxy with advanced filtering
+ capabilities for protecting privacy, filtering web page content,
+ managing cookies, controlling access, and removing ads, banners,
+ pop-ups and other obnoxious Internet Junk. Privoxy has a very flexible
+ configuration and can be customized to suit individual needs and
+ tastes. Privoxy has application for both stand-alone systems and
+ multi-user networks.
You can find the latest version of the user manual at
[1]http://ijbswa.sourceforge.net/developer-manual/. Please see the
Contact section in the user-manual if you want to contact the
developers.
-
- Feel free to send a note to the developers at
- <[2]ijbswa-developers@lists.sourceforge.net>.
_________________________________________________________________
Table of Contents
- 1. [3]Introduction
- 2. [4]Quickstart to Junkbuster Development
- 3. [5]Documentation Guidelines
- 4. [6]Coding Guidelines
+ 1. [2]Introduction
+ 2. [3]Quickstart to Privoxy Development
+ 3. [4]Documentation Guidelines
+ 4. [5]Coding Guidelines
- 4.1. [7]Introduction
- 4.2. [8]Using Comments
- 4.3. [9]Naming Conventions
- 4.4. [10]Using Space
- 4.5. [11]Initializing
- 4.6. [12]Functions
- 4.7. [13]General Coding Practices
- 4.8. [14]Addendum: Template for files and function comment
+ 4.1. [6]Introduction
+ 4.2. [7]Using Comments
+
+ 4.2.1. [8]Comment, Comment, Comment
+ 4.2.2. [9]Use blocks for comments
+ 4.2.3. [10]Keep Comments on their own line
+ 4.2.4. [11]Comment each logical step
+ 4.2.5. [12]Comment All Functions Thoroughly
+ 4.2.6. [13]Comment at the end of braces if the content is
+ more than one screen length
+
+ 4.3. [14]Naming Conventions
+
+ 4.3.1. [15]Variable Names
+ 4.3.2. [16]Function Names
+ 4.3.3. [17]Header file prototypes
+ 4.3.4. [18]Enumerations, and #defines
+ 4.3.5. [19]Constants
+
+ 4.4. [20]Using Space
+
+ 4.4.1. [21]Put braces on a line by themselves.
+ 4.4.2. [22]ALL control statements should have a block
+ 4.4.3. [23]Do not belabor/blow-up boolean expressions
+ 4.4.4. [24]Use white space freely because it is free
+ 4.4.5. [25]Don't use white space around structure operators
+ 4.4.6. [26]Make the last brace of a function stand out
+ 4.4.7. [27]Use 3 character indentions
+
+ 4.5. [28]Initializing
+
+ 4.5.1. [29]Initialize all variables
+
+ 4.6. [30]Functions
+
+ 4.6.1. [31]Name functions that return a boolean as a
+ question.
+
+ 4.6.2. [32]Always specify a return type for a function.
+ 4.6.3. [33]Minimize function calls when iterating by using
+ variables
+
+ 4.6.4. [34]Pass and Return by Const Reference
+ 4.6.5. [35]Pass and Return by Value
+ 4.6.6. [36]Names of include files
+ 4.6.7. [37]Provide multiple inclusion protection
+ 4.6.8. [38]Use `extern "C"` when appropriate
+ 4.6.9. [39]Where Possible, Use Forward Struct Declaration
+ Instead of Includes
+
+ 4.7. [40]General Coding Practices
+
+ 4.7.1. [41]Turn on warnings
+ 4.7.2. [42]Provide a default case for all switch statements
+ 4.7.3. [43]Try to avoid falling through cases in a switch
+ statement.
+
+ 4.7.4. [44]Use 'long' or 'short' Instead of 'int'
+ 4.7.5. [45]Don't mix size_t and other types
+ 4.7.6. [46]Declare each variable and struct on its own
+ line.
+
+ 4.7.7. [47]Use malloc/zalloc sparingly
+ 4.7.8. [48]The Programmer Who Uses 'malloc' is Responsible
+ for Ensuring 'free'
+
+ 4.7.9. [49]Add loaders to the `file_list' structure and in
+ order
+
+ 4.7.10. [50]"Uncertain" new code and/or changes to exitinst
+ code, use FIXME
+
+ 4.8. [51]Addendum: Template for files and function comment
blocks:
- 5. [15]Version Control Guidelines
- 6. [16]Testing Guidelines
+ 5. [52]Version Control Guidelines
+ 6. [53]Testing Guidelines
- 6.1. [17]Testplan for releases
- 6.2. [18]Test reports
+ 6.1. [54]Testplan for releases
+ 6.2. [55]Test reports
- 7. [19]Contact the developers
- 8. [20]Copyright and History
- 9. [21]See also
+ 7. [56]Contact the developers
+ 8. [57]Copyright and History
+ 9. [58]See also
1. Introduction
To be filled.
_________________________________________________________________
-2. Quickstart to Junkbuster Development
+2. Quickstart to Privoxy Development
- To be filled.
+ You'll need an account on Sourceforge to support our development. Mail
+ you ID to the list and wait until a project manager has added you. For
+ the time beeing (read, this section is under construction), please
+ note the following guidelines for changing stuff in the code. If it is
+
+ 1. A bugfix / clean-up / cosmetic thing: shoot
+ 2. A new feature that can be turned off: shoot
+ 3. A clear improvement w/o side effects on other parts of the code:
+ shoot
+ 4. A matter of taste: ask the list
+ 5. A major redesign of some part of the code: ask the list
_________________________________________________________________
3. Documentation Guidelines
- All docs should be ...
-
- * in a format that is widely used. I propose HTML.
- * we either
- + generate man pages from the documentation (let's _NOT_ write
- them manually), or
- + we have a man page that points to the documentation (I
- propose this option)
- * have a consistent layout
- * have a link to the latest version of the document (i.e. point to a
- URL at sf)
- * be consistent with the redirect script (i.e. the junkbuster
- program points via the redirect URL at sf to valid end-points in
- the document)
- * started from scratch but recycle parts from the original
- junkbuster documents
+ All docs are in SGML format and located in the doc/source directory.
+
+ How do you update the webserver (i.e. the pages on sourceforge)?
+
+ 1. Run make dok (which uses the documents in doc/source to update all
+ text files in doc/text and to update all web documents in
+ doc/webserver.
+ 2. Run make webserver which copies all files from doc/webserver to
+ the sourceforge webserver via scp.
_________________________________________________________________
4. Coding Guidelines
This set of standards is designed to make our lives easier. It is
developed with the simple goal of helping us keep the "new and
- improved Junkbusters" consistent and reliable. Thus making maintenance
+ improved Privoxy" consistent and reliable. Thus making maintenance
easier and increasing chances of success of the project.
And that of course comes back to us as individuals. If we can increase
short DoSomethingVeryImportant(
- short firstParam, /* represents something */
- short nextParam /* represents something else */ )
+ short firstparam, /* represents something */
+ short nextparam /* represents something else */ )
{
...code here...
start an identifier with an underscore. (ANSI C reserves these for use
by the compiler and system headers.) Do not use identifiers which are
reserved in ANSI C++. (E.g. template, class, true, false, ...). This
- is in case we ever decide to port JunkBuster to C++.
+ is in case we ever decide to port Privoxy to C++.
Example:
int ms_iis5_hack = 0;
start an identifier with an underscore. (ANSI C reserves these for use
by the compiler and system headers.) Do not use identifiers which are
reserved in ANSI C++. (E.g. template, class, true, false, ...). This
- is in case we ever decide to port JunkBuster to C++.
+ is in case we ever decide to port Privoxy to C++.
Example:
int load_some_file( struct client_state *csp )
extern int strcmp( char *s1, char *s2 );
I could then not use it to compare argv's in main: int main( int argc,
- const char *argv[] ) { strcmp( argv[0], "junkbusters" ); }
+ const char *argv[] ) { strcmp( argv[0], "privoxy" ); }
Both these pointers are *const*! If the c runtime library maintainers
do it, we should too.
4.8. Addendum: Template for files and function comment blocks:
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:
-48 swa Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.9 2002/03/24 11:01:
+05 swa Exp $";
/*********************************************************************
*
* File : $Source$
* Purpose : (Fill me in with a good description!)
*
* Copyright : Written by and Copyright (C) 2001 the SourceForge
- * IJBSWA team. http://ijbswa.sourceforge.net
+ * PRIVOXY team. http://ijbswa.sourceforge.net
*
* Based on the Internet Junkbuster originally written
* by and Copyright (C) 1997 Anonymous Coders and
Example for file header comments:
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:4
-8 swa Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.9 2002/03/24 11:01:0
+5 swa Exp $"
/*********************************************************************
*
* File : $Source$
* Purpose : (Fill me in with a good description!)
*
* Copyright : Written by and Copyright (C) 2001 the SourceForge
- * IJBSWA team. http://ijbswa.sourceforge.net
+ * PRIVOXY team. http://ijbswa.sourceforge.net
*
* Based on the Internet Junkbuster originally written
* by and Copyright (C) 1997 Anonymous Coders and
*
* Description : (Fill me in with a good description!)
*
- * Parameters :
+ * parameters :
* 1 : param1 = pointer to an important thing
* 2 : x = pointer to something else
*
1. Remove any existing rpm with rpm -e
2. Remove any file that was left over. This includes (but is not
limited to)
- + /var/log/junkbuster
- + /etc/junkbuster
- + /usr/sbin/junkbuster
- + /etc/init.d/junkbuster
- + /usr/doc/junkbuster*
+ + /var/log/privoxy
+ + /etc/privoxy
+ + /usr/sbin/privoxy
+ + /etc/init.d/privoxy
+ + /usr/doc/privoxy*
3. Install the rpm. Any error messages?
- 4. start,stop,status junkbuster with the specific script (e.g.
- /etc/rc.d/init/junkbuster stop). Reboot your machine. Does
- autostart work?
- 5. Start browsing. Does the junkbuster work? Logfile written?
+ 4. start,stop,status Privoxy with the specific script (e.g.
+ /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart
+ work?
+ 5. Start browsing. Does Privoxy work? Logfile written?
6. Remove the rpm. Any error messages? All files removed?
_________________________________________________________________
6.2. Test reports
- Please submit test reports only with the [22]test form at sourceforge.
+ Please submit test reports only with the [59]test form at sourceforge.
Three simple steps:
* Select category: the distribution you test on.
- * Select group: the version of Junkbuster that we are about to
- release.
+ * Select group: the version of Privoxy that we are about to release.
* Fill the Summary and Detailed Description with something
intelligent (keep it short and precise).
References
1. http://ijbswa.sourceforge.net/developer-manual/
- 2. mailto:ijbswa-developers@lists.sourceforge.net
- 3. file://localhost/home/swa/sf/current/doc/source/tmp.html#INTRODUCTION
- 4. file://localhost/home/swa/sf/current/doc/source/tmp.html#QUICKSTART
- 5. file://localhost/home/swa/sf/current/doc/source/tmp.html#DOCUMENTATION
- 6. file://localhost/home/swa/sf/current/doc/source/tmp.html#CODING
- 7. file://localhost/home/swa/sf/current/doc/source/tmp.html#S1
- 8. file://localhost/home/swa/sf/current/doc/source/tmp.html#S2
- 9. file://localhost/home/swa/sf/current/doc/source/tmp.html#S9
- 10. file://localhost/home/swa/sf/current/doc/source/tmp.html#S15
- 11. file://localhost/home/swa/sf/current/doc/source/tmp.html#S23
- 12. file://localhost/home/swa/sf/current/doc/source/tmp.html#S25
- 13. file://localhost/home/swa/sf/current/doc/source/tmp.html#S35
- 14. file://localhost/home/swa/sf/current/doc/source/tmp.html#S46
- 15. file://localhost/home/swa/sf/current/doc/source/tmp.html#CVS
- 16. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING
- 17. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-PLAN
- 18. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-REPORT
- 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONTACT
- 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#COPYRIGHT
- 21. file://localhost/home/swa/sf/current/doc/source/tmp.html#SEEALSO
- 22. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005
+ 2. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#INTRODUCTION
+ 3. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#QUICKSTART
+ 4. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#DOCUMENTATION
+ 5. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CODING
+ 6. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S1
+ 7. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S2
+ 8. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S3
+ 9. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S4
+ 10. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S5
+ 11. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S6
+ 12. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S7
+ 13. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S8
+ 14. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S9
+ 15. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S10
+ 16. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S11
+ 17. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S12
+ 18. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S13
+ 19. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S14
+ 20. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S15
+ 21. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S16
+ 22. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S17
+ 23. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S18
+ 24. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S19
+ 25. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S20
+ 26. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S21
+ 27. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S22
+ 28. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S23
+ 29. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S24
+ 30. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S25
+ 31. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S26
+ 32. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S27
+ 33. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S28
+ 34. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S29
+ 35. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S30
+ 36. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S31
+ 37. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S32
+ 38. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S33
+ 39. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S34
+ 40. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S35
+ 41. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S36
+ 42. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S37
+ 43. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S38
+ 44. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S39
+ 45. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S40
+ 46. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S41
+ 47. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S42
+ 48. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S43
+ 49. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S44
+ 50. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S45
+ 51. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S46
+ 52. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CVS
+ 53. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING
+ 54. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-PLAN
+ 55. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-REPORT
+ 56. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CONTACT
+ 57. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#COPYRIGHT
+ 58. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#SEEALSO
+ 59. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005
projects / privoxy.git / blobdiff