X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=fd1e65bb089f5624f29c8f1e39fc99406d041e0f;hb=4cb100b1eb7a5ea7e9583e85e89b972480a2621b;hp=7b64286756849fa7d5c9e1e43bb2cdb0388a77b2;hpb=c8e80224f4150b046d1b36fa9a22d8219a7c7043;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 7b642867..fd1e65bb 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -1,16 +1,15 @@ - + + + + @@ -57,55 +77,73 @@ Please see the Contact section in the user-manual if you want to contact the dev - Quickstart to Junkbuster Development - To be filled. - - - + Quickstart to Privoxy Development + +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 + + + A bugfix / clean-up / cosmetic thing: shoot + + + A new feature that can be turned off: shoot + + + A clear improvement w/o side effects on other parts of the code: shoot + + + A matter of taste: ask the list + + + A major redesign of some part of the code: ask the list + + + + + 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)? + + + 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. + + + Run make webserver which copies all files from +doc/webserver to the sourceforge webserver +via scp. + + - + + + + Coding Guidelines Introduction - 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 easier and increasing chances of success of - the project. + 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 + 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 our development and product efficiencies then we - can solve more of the request for changes/improvements and in - general feel good about ourselves. ;-> + And that of course comes back to us as individuals. If we can + increase our development and product efficiencies then we can solve more + of the request for changes/improvements and in general feel good about + ourselves. ;-> @@ -114,7 +152,7 @@ write them manually), or Comment, Comment, Comment - Explanation: + Explanation: Comment as much as possible without commenting the obvious. For example do not comment "aVariable is equal to bVariable". @@ -129,7 +167,7 @@ write them manually), or If the comment describes something different than what the code is doing then maybe a programming error is occurring. - Example: + Example: /* if page size greater than 1k ... */ if ( PageLength() > 1024 ) @@ -153,7 +191,7 @@ is actually being done. Use blocks for comments - Explanation: + Explanation: Comments can help or they can clutter. They help when they are differentiated from the code they describe. One line @@ -161,7 +199,7 @@ is actually being done. and the code. Block identifiers do, by surrounding the code with a clear, definable pattern. - Example: + Example: /********************************************************************* * This will stand out clearly in your code! @@ -184,7 +222,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ DoSomethingVeryImportant(); } - Exception: + Exception: If you are trying to add a small logic comment and do not wish to "disrubt" the flow of the code, feel free to use a 1 @@ -196,7 +234,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ Keep Comments on their own line - Explanation: + Explanation: It goes back to the question of readability. If the comment is on the same line as the code it will be harder to read than @@ -207,7 +245,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ at the end of closing braces, when used to comment parameters. - Example: + Example: /********************************************************************* * This will stand out clearly in your code, @@ -237,8 +275,8 @@ if ( 1 == X ) short DoSomethingVeryImportant( - short firstParam, /* represents something */ - short nextParam /* represents something else */ ) + short firstparam, /* represents something */ + short nextparam /* represents something else */ ) { ...code here... @@ -249,7 +287,7 @@ short DoSomethingVeryImportant( Comment each logical step - Explanation: + Explanation: Logical steps should be commented to help others follow the intent of the written code and comments will make the code more @@ -269,7 +307,7 @@ short DoSomethingVeryImportant( Comment All Functions Thoroughly - Explanation: + Explanation: A reader of the code should be able to look at the comments just prior to the beginning of a function and discern the @@ -291,7 +329,7 @@ short DoSomethingVeryImportant( Comment at the end of braces if the content is more than one screen length - Explanation: + Explanation: Each closing brace should be followed on the same line by a comment that describes the origination of the brace if the @@ -305,7 +343,7 @@ short DoSomethingVeryImportant( use following a closing brace: } /* -END- if() or while () or etc... */ - Example: + Example: if ( 1 == X ) { @@ -331,20 +369,20 @@ if ( 1 == X ) Variable Names - Explanation: + Explanation: Use all lowercase, and seperate words via an underscore ('_'). Do not 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++. + decide to port Privoxy to C++. - Example: + Example: int ms_iis5_hack = 0; - Instead of: + Instead of: @@ -358,20 +396,20 @@ int msiis5hack = 0; int msIis5Hack = 0; Function Names - Explanation: + Explanation: Use all lowercase, and seperate words via an underscore ('_'). Do not 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++. + decide to port Privoxy to C++. - Example: + Example: int load_some_file( struct client_state *csp ) - Instead of: + Instead of: @@ -386,18 +424,18 @@ int loadSomeFile( struct client_state *csp ) Header file prototypes - Explanation: + Explanation: Use a descriptive parameter name in the function prototype in header files. Use the same parameter name in the header file that you use in the c file. - Example: + Example: (.h) extern int load_aclfile( struct client_state *csp ); (.c) int load_aclfile( struct client_state *csp ) - Instead of: + Instead of: (.h) extern int load_aclfile( struct client_state * ); or (.h) extern int load_aclfile(); @@ -411,22 +449,22 @@ int loadSomeFile( struct client_state *csp ) Enumerations, and #defines - Explanation: + Explanation: Use all capital letters, with underscores between words. Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) - Example: + Example: (enumeration) : enum Boolean { FALSE, TRUE }; (#define) : #define DEFAULT_SIZE 100; - Note: We have a standard naming scheme for #defines + Note: We have a standard naming scheme for #defines that toggle a feature in the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word) description. - Example: + Example: #define FEATURE_FORCE 1 @@ -439,7 +477,7 @@ int loadSomeFile( struct client_state *csp ) Constants - Explanation: + Explanation: Spell common words out entirely (do not remove vowels). @@ -449,11 +487,11 @@ int loadSomeFile( struct client_state *csp ) Use underscore (_) to separate adjacent acronyms and abbreviations. Never terminate a name with an underscore. - Example: + Example: #define USE_IMAGE_LIST 1 - Instead of: + Instead of: @@ -477,7 +515,7 @@ int loadSomeFile( struct client_state *csp ) Put braces on a line by themselves. - Explanation: + Explanation: The brace needs to be on a line all by itself, not at the end of the statement. Curly braces should line up with the @@ -485,14 +523,14 @@ int loadSomeFile( struct client_state *csp ) easier to identify the opening and closing braces for a block. - Example: + Example: if ( this == that ) { ... } - Instead of: + Instead of: if ( this == that ) { ... } @@ -500,15 +538,15 @@ if ( this == that ) if ( this == that ) { ... } - Note: In the special case that the if-statement is + Note: In the special case that the if-statement is inside a loop, and it is trivial, i.e. it tests for a condidtion that is obvious from the purpose of the block, one-liners as above may optically preserve the loop structure and make it easier to read. - Status: developer-discrection. + Status: developer-discrection. - Example exception: + Example exception: while ( more lines are read ) { @@ -524,13 +562,13 @@ while ( more lines are read ) ALL control statements should have a block - Explanation: + Explanation: Using braces to make a block will make your code more readable and less prone to error. All control statements should have a block defined. - Example: + Example: if ( this == that ) { @@ -538,7 +576,7 @@ if ( this == that ) DoSomethingElse(); } - Instead of: + Instead of: if ( this == that ) DoSomething(); DoSomethingElse(); @@ -546,7 +584,7 @@ if ( this == that ) if ( this == that ) DoSomething(); - Note: The first example in "Instead of" will execute + Note: The first example in "Instead of" will execute in a manner other than that which the developer desired (per indentation). Using code braces would have prevented this "feature". The "explanation" and "exception" from the point @@ -559,16 +597,16 @@ if ( this == that ) Do not belabor/blow-up boolean expressions - Example: + Example: structure->flag = ( condition ); - Instead of: + Instead of: if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } - Note: The former is readable and consice. The later + Note: The former is readable and consice. The later is wordy and inefficient. Please assume that any developer new to the project has at least a "good" knowledge of C/C++. (Hope I do not offend by that last comment ... 8-) @@ -580,12 +618,12 @@ structure->flag = ( condition ); Use white space freely because it is free - Explanation: + Explanation: Make it readable. The notable exception to using white space freely is listed in the next guideline. - Example: + Example: int firstValue = 0; int someValue = 0; @@ -602,7 +640,7 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) Don't use white space around structure operators - Explanation: + Explanation: - structure pointer operator ( "->" ) - member operator ( "." ) - functions and parentheses @@ -612,13 +650,13 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) connection between the object and variable/function name is not as clear. - Example: + Example: aStruct->aMember; aStruct.aMember; FunctionName(); - Instead of: aStruct -> aMember; aStruct . aMember; + Instead of: aStruct -> aMember; aStruct . aMember; FunctionName (); @@ -628,7 +666,7 @@ FunctionName(); Make the last brace of a function stand out - Example: + Example: int function1( ... ) { @@ -643,12 +681,12 @@ int function2( ... ) } /* -END- function2 */ - Instead of: + Instead of: int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { } - Note: Use 1 blank line before the closing brace and 2 + Note: Use 1 blank line before the closing brace and 2 lines afterwards. This makes the end of function standout to the most casual viewer. Although function comments help seperate functions, this is still a good coding practice. In @@ -656,7 +694,7 @@ int function2( ... ) "do" loops, and long if {} statements too. After all whitespace is free! - Status: developer-discrection on the number of blank + Status: developer-discrection on the number of blank lines. Enforced is the end of function comments. @@ -665,14 +703,14 @@ int function2( ... ) Use 3 character indentions - Explanation: + Explanation: If some use 8 character TABs and some use 3 character TABs, the code can look *very* ragged. So use 3 character indentions only. If you like to use TABs, pass your code through a filter such as "expand -t3" before checking in your code. - Example: + Example: static const char * const url_code_map[256] = { @@ -706,25 +744,25 @@ int function1( ... ) Initialize all variables - Explanation: + Explanation: Do not assume that the variables declared will not be used until after they have been assigned a value somewhere else in the code. Remove the chance of accidentally using an unassigned variable. - Example: + Example: short anShort = 0; float aFloat = 0; struct *ptr = NULL; - Note: It is much easier to debug a SIGSEGV if the + Note: It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. arrayPtr[0]. - Status: developer-discrection if and only if the + Status: developer-discrection if and only if the variable is assigned a value "shortly after" declaration. @@ -738,12 +776,12 @@ struct *ptr = NULL; Name functions that return a boolean as a question. - Explanation: + Explanation: Value should be phrased as a question that would logically be answered as a true or false statement - Example: + Example: ShouldWeBlockThis(); ContainsAnImage(); @@ -755,7 +793,7 @@ IsWebPageBlank(); Always specify a return type for a function. - Explanation: + Explanation: The default return for a function is an int. To avoid ambiguity, create a return for a function when the return has a @@ -769,19 +807,19 @@ IsWebPageBlank(); Minimize function calls when iterating by using variables - Explanation: + Explanation: It is easy to write the following code, and a clear argument can be made that the code is easy to understand: - Example: + Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) { .... } - Note: Unfortunately, this makes a function call for + Note: Unfortunately, this makes a function call for each and every iteration. This increases the overhead in the program, because the compiler has to look up the function each time, call it, and return a value. Depending on what occurs in @@ -795,16 +833,16 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) assign the value to a variable, and evaluate using the variable. - Example: + Example: size_t len = blockListLength(); -for ( size_t cnt = 0; cnt < len; cnt ++ ) +for ( size_t cnt = 0; cnt < len; cnt ++ ) { .... } - Exceptions: if the value of blockListLength() *may* + Exceptions: if the value of blockListLength() *may* change or could *potentially* change, then you must code the function call in the for/while loop. @@ -814,7 +852,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Pass and Return by Const Reference - Explanation: + Explanation: This allows a developer to define a const pointer and call your function. If your function does not have the const @@ -823,7 +861,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) 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" + int argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); } Both these pointers are *const*! If the c runtime library @@ -835,7 +873,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Pass and Return by Value - Explanation: + Explanation: Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes or less). Aka, a function declaration @@ -851,7 +889,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Names of include files - Explanation: + Explanation: Your include statements should contain the file name without a path. The path should be listed in the Makefile, using -I as @@ -860,13 +898,13 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) partial path to distinguish their header files from system or other header files. - Example: + Example: #include <iostream.h> /* This is not a local include */ #include "config.h" /* This IS a local include */ - Exception: + Exception: @@ -875,7 +913,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) - Note: Please! do not add "-I." to the Makefile + Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include "file.h" behaviour. @@ -886,7 +924,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Provide multiple inclusion protection - Explanation: + Explanation: Prevents compiler and linker errors resulting from redefinition of items. @@ -896,7 +934,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) with your file name, with "." Changed to "_", and make it uppercase. - Example: + Example: #ifndef PROJECT_H_INCLUDED #define PROJECT_H_INCLUDED @@ -908,13 +946,13 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Use `extern "C"` when appropriate - Explanation: + Explanation: If our headers are included from C++, they must declare our functions as `extern "C"`. This has no cost in C, but increases the potential re-usability of our code. - Example: + Example: #ifdef __cplusplus extern "C" @@ -933,13 +971,13 @@ extern "C" Where Possible, Use Forward Struct Declaration Instead of Includes - Explanation: + Explanation: Useful in headers that include pointers to other struct's. Modifications to excess header files may cause needless compiles. - Example: + Example: /********************************************************************* * We're avoiding an include statement here! @@ -947,12 +985,12 @@ extern "C" struct file_list; extern file_list *xyz; - Note: If you declare "file_list xyz;" (without the + Note: If you declare "file_list xyz;" (without the pointer), then including the proper header file is necessary. If you only want to prototype a pointer, however, the header file is unneccessary. - Status: Use with discrection. + Status: Use with discrection. @@ -964,7 +1002,7 @@ extern file_list *xyz; Turn on warnings - Explanation + Explanation Compiler warnings are meant to help you find bugs. You should turn on as many as possible. With GCC, the switch is @@ -977,14 +1015,14 @@ extern file_list *xyz; Provide a default case for all switch statements - Explanation: + Explanation: What you think is guaranteed is never really guaranteed. The value that you don't think you need to check is the one that someday will be passed. So, to protect yourself from the unknown, always have a default step in a switch statement. - Example: + Example: switch( hash_string( cmd ) ) { @@ -1003,17 +1041,17 @@ switch( hash_string( cmd ) ) } /* end switch( hash_string( cmd ) ) */ - Note: If you already have a default condition, you + Note: If you already have a default condition, you are obviously exempt from this point. Of note, most of the WIN32 code calls `DefWindowProc' after the switch statement. This API call *should* be included in a default statement. - Another Note: This is not so much a readability issue + Another Note: This is not so much a readability issue as a robust programming issue. The "anomly code goes here" may be no more than a print to the STDERR stream (as in load_config). Or it may really be an ABEND condition. - Status: Programmer discretion is advised. + Status: Programmer discretion is advised. @@ -1022,7 +1060,7 @@ switch( hash_string( cmd ) ) Try to avoid falling through cases in a switch statement. - Explanation: + Explanation: In general, you will want to have a 'break' statement within each 'case' of a switch statement. This allows for the code to @@ -1047,12 +1085,12 @@ switch( hash_string( cmd ) ) Use 'long' or 'short' Instead of 'int' - Explanation: + Explanation: On 32-bit platforms, int usually has the range of long. On 16-bit platforms, int has the range of short. - Status: open-to-debate. In the case of most FSF + Status: open-to-debate. In the case of most FSF projects (including X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I forget the exact typedefs now). Should we add these to IJB now that we have a "configure" @@ -1064,7 +1102,7 @@ switch( hash_string( cmd ) ) Don't mix size_t and other types - Explanation: + Explanation: The type of size_t varies across platforms. Do not make assumptions about whether it is signed or unsigned, or about @@ -1080,33 +1118,33 @@ switch( hash_string( cmd ) ) Declare each variable and struct on its own line. - Explanation: + Explanation: It can be tempting to declare a series of variables all on one line. Don't. - Example: + Example: long a = 0; long b = 0; long c = 0; - Instead of: + Instead of: long a, b, c; - Explanation: - there is more room for comments on the + Explanation: - there is more room for comments on the individual variables - easier to add new variables without messing up the original ones - when searching on a variable to find its type, there is less clutter to "visually" eliminate - Exceptions: when you want to declare a bunch of loop + Exceptions: when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them on 1 line. You should, although, provide a good comment on their functions. - Status: developer-discrection. + Status: developer-discrection. @@ -1114,7 +1152,7 @@ long c = 0; Use malloc/zalloc sparingly - Explanation: + Explanation: Create a local stuct (on the stack) if the variable will live and die within the context of one function call. @@ -1122,7 +1160,7 @@ long c = 0; Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function call. - Example: + Example: If a function creates a struct and stores a pointer to it in a list, then it should definately be allocated via `malloc'. @@ -1133,7 +1171,7 @@ list, then it should definately be allocated via `malloc'. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free' - Explanation: + Explanation: If you have to "malloc" an instance, you are responsible for insuring that the instance is `free'd, even if the deallocation @@ -1143,18 +1181,18 @@ list, then it should definately be allocated via `malloc'. "good thing (tm)". You may need to offer a free/unload/destuctor type function to accomodate this. - Example: + Example: int load_re_filterfile( struct client_state *csp ) { ... } static void unload_re_filterfile( void *f ) { ... } - Exceptions: + Exceptions: The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as `strdup'. - Status: developer-discrection. The "main" use of this + Status: developer-discrection. The "main" use of this standard is for allocating and freeing data structures (complex or nested). @@ -1165,13 +1203,13 @@ static void unload_re_filterfile( void *f ) { ... } Add loaders to the `file_list' structure and in order - Explanation: + Explanation: I have ordered all of the "blocker" file code to be in alpha order. It is easier to add/read new blockers when you expect a certain order. - Note: It may appear that the alpha order is broken in + Note: It may appear that the alpha order is broken in places by POPUP tests coming before PCRS tests. But since POPUPs can also be referred to as KILLPOPUPs, it is clear that it should come first. @@ -1183,7 +1221,7 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to exitinst code, use FIXME - Explanation: + Explanation: If you have enough confidence in new code or confidence in your changes, but are not *quite* sure of the reprocussions, @@ -1203,7 +1241,7 @@ static void unload_re_filterfile( void *f ) { ... } /* FIXME: new code that *may* break something else... */ ...new code here... - Note: If you make it clear that this may or may not + Note: If you make it clear that this may or may not be a "good thing (tm)", it will be easier to identify and include in the project (or conversly exclude from the project). @@ -1216,9 +1254,9 @@ static void unload_re_filterfile( void *f ) { ... } Addendum: Template for files and function comment blocks: - Example for file comments: + Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:17 swa Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $"; /********************************************************************* * * File : $Source$ @@ -1226,7 +1264,7 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:1 * 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://www.privoxy.org/ * * Based on the Internet Junkbuster originally written * by and Copyright (C) 1997 Anonymous Coders and @@ -1263,22 +1301,22 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:1 const char FILENAME_h_rcs[] = FILENAME_H_VERSION; - Note: This declares the rcs variables that should be + Note: This declares the rcs variables that should be added to the "show-proxy-args" page. If this is a brand new creation by you, you are free to change the "Copyright" section to represent the rights you wish to maintain. - Note: The formfeed character that is present right + Note: The formfeed character that is present right after the comment flower box is handy for (X|GNU)Emacs users to skip the verbige and get to the heart of the code (via `forward-page' and `backward-page'). Please include it if you can. - Example for file header comments: + Example for file header comments: #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:17 swa Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $" /********************************************************************* * * File : $Source$ @@ -1286,7 +1324,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; * 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://www.privoxy.org/ * * Based on the Internet Junkbuster originally written * by and Copyright (C) 1997 Anonymous Coders and @@ -1343,7 +1381,7 @@ extern const char FILENAME_h_rcs[]; */ - Example for function comments: + Example for function comments: /********************************************************************* * @@ -1351,7 +1389,7 @@ extern const char FILENAME_h_rcs[]; * * Description : (Fill me in with a good description!) * - * Parameters : + * parameters : * 1 : param1 = pointer to an important thing * 2 : x = pointer to something else * @@ -1366,7 +1404,7 @@ int FUNCTION_NAME( void *param1, const char *x ) } - Note: If we all follow this practice, we should be + Note: If we all follow this practice, we should be able to parse our code to create a "self-documenting" web page. @@ -1391,29 +1429,29 @@ why you did it. Explain release numbers. major, minor. developer releases. etc. - - + + Remove any existing rpm with rpm -e - - + + 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* + + + Install the rpm. Any error messages? - - start,stop,status junkbuster with the specific script - (e.g. /etc/rc.d/init/junkbuster stop). Reboot your machine. Does - autostart work? - Start browsing. Does the junkbuster work? Logfile written? - Remove the rpm. Any error messages? All files removed? - + + start,stop,status Privoxy with the specific script + (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does + autostart work? + Start browsing. Does Privoxy work? Logfile written? + Remove the rpm. Any error messages? All files removed? + @@ -1422,19 +1460,455 @@ Install the rpm. Any error messages? Please submit test reports only with the 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. - Fill the Summary and Detailed Description with something - intelligent (keep it short and precise). - - - Do not mail to the mailinglist (we cannot keep track on issues there). + + + Select category: the distribution you test on. + 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). + + + Do not mail to the mailinglist (we cannot keep track on issues there). + + + Releasing a new version + + To minimize trouble with distribution contents, webpage + errors and the like, I (Stefan) strongly encourage you + to follow this section if you prepare a new release of + code or new pages on the webserver. + + + The following programs are required to follow this process: + ncftpput (ncftp), scp (ssh), +gmake (GNU's version of make), ???. + + Update the webserver + + All files must be group-readable and group-writable (or no one else + will be able to change them). To update the webserver, create any + pages locally in the doc/webserver directory (or + create new directories under doc/webserver), then do + + + + make webserver + + + + Note that make dok creates + doc/webserver/user-manual, + doc/webserver/developer-manual, + doc/webserver/faq and + doc/webserver/man-page automatically. + + + Verify on the webserver that the permissions are set correctly. Do + NOT use any other means of transferring files to the webserver. + + + + SuSE or RedHat + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Update the release number + directly in the specific spec file (particularly, set the release + number to 1 if you have increased the version + number before). Run + + + + autoheader && autoconf && ./configure + + + + Then do + + + + make suse-dist or make redhat-dist + + + + To upload the package to Sourceforge, simply issue + + + + make suse-upload or make redhat-upload + + + + Goto the displayed URL and release the file publically on Sourceforge. + + + + OS/2 + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + Solaris + + Login to Sourceforge's compilefarm via ssh + + + + ssh cf.sourceforge.net + + + + Choose the right operating system (not the Debian one). If you have + downloaded Privoxy before, + + + + cd current && cvs update . + + + + If not, please checkout + Privoxy via CVS first. Verify the version number in + configure.in. If necessary, change the version + number. Run + + + + autoheader && autoconf && ./configure + + + + Then run + + + + gmake solaris-dist + + + + which creates a gzip'ed tar archive. Sadly, you cannot use make + solaris-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publically + + + + Windows + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + Debian + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + Mac OSX + + Login to Sourceforge's compilefarm via ssh + + + + ssh cf.sourceforge.net + + + + Choose the right operating system. If you have downloaded Privoxy + before, + + + + cd current && cvs update . + + + + If not, please checkout + Privoxy via CVS first. Verify the version number in + configure.in. If necessary, change the version + number. Run + + + + autoheader && autoconf && ./configure + + + + Then run + + + + make macosx-dist + + + + which creates a gzip'ed tar archive. Sadly, you cannot use make + macosx-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publically + + + + FreeBSD + + Change the version number of Privoxy in the + configure.in file. Run + + autoheader && autoconf && ./configure + + Then ... + + + Login to Sourceforge's compilefarm via ssh + + + + ssh cf.sourceforge.net + + + + Choose the right operating system. If you have downloaded Privoxy + before, + + + + cd current && cvs update . + + + + If not, please checkout + Privoxy via CVS first. Verify the version number in + configure.in. If necessary, change the version + number. Run + + + + autoheader && autoconf && ./configure + + + + Then run + + + + gmake freebsd-dist + + + + which creates a gzip'ed tar archive. Sadly, you cannot use make + freebsd-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publically + + + + Tarball + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + make clobber + autoheader && autoconf && ./configure + + + + Then do + + + + make tarball-dist + + + + To upload the package to Sourceforge, simply issue + + + + make tarball-upload + + + + Goto the displayed URL and release the file publically on Sourceforge. + + + + HP-UX 11 + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + Amiga OS + + Ensure that you have the latest code version. Hence run + + + + cvs update . + + + + first. If necessary, change the version number of + Privoxy in the + configure.in file. Run + + + + autoheader && autoconf && ./configure + + + + Then do FIXME. + + + + AIX + + Login to Sourceforge's compilefarm via ssh + + + + ssh cf.sourceforge.net + + + + Choose the right operating system. If you have downloaded Privoxy + before, + + + + cd current && cvs update . + + + + If not, please checkout + Privoxy via CVS first. Verify the version number in + configure.in. If necessary, change the version + number. Run + + + + autoheader && autoconf && ./configure + + + + Then run + + + + make aix-dist + + + + which creates a gzip'ed tar archive. Sadly, you cannot use make + aix-upload on the Sourceforge machine (no ncftpput). You now have + to manually upload the archive to Sourceforge's ftp server and release + the file publically + + + + Contact the developers @@ -1475,6 +1949,50 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 1.14 2002/03/30 19:04:08 swa + people release differently. no good. + I want to make parts of the docs only. + + Revision 1.13 2002/03/27 01:16:41 hal9 + ditto + + Revision 1.12 2002/03/27 01:02:51 hal9 + Touch up on name change... + + Revision 1.11 2002/03/26 22:29:55 swa + we have a new homepage! + + Revision 1.10 2002/03/24 12:33:01 swa + more additions. + + Revision 1.9 2002/03/24 11:01:05 swa + name change + + Revision 1.8 2002/03/23 15:13:11 swa + renamed every reference to the old name with foobar. + fixed "application foobar application" tag, fixed + "the foobar" with "foobar". left junkbustser in cvs + comments and remarks to history untouched. + + Revision 1.7 2002/03/11 13:13:27 swa + correct feedback channels + + Revision 1.6 2002/02/24 14:25:06 jongfoster + Formatting changes. Now changing the doctype to DocBook XML 4.1 + will work - no other changes are needed. + + Revision 1.5 2001/10/31 18:16:51 swa + documentation added: howto generate docs in text and html + format, howto move stuff to the webserver. + + Revision 1.4 2001/09/23 10:13:48 swa + upload process established. run make webserver and + the documentation is moved to the webserver. documents + are now linked correctly. + + Revision 1.3 2001/09/13 15:27:40 swa + cosmetics + Revision 1.2 2001/09/13 15:20:17 swa merged standards into developer manual