X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=8323f9f60d5edaf56ebffcf99df9d562befe5656;hp=ecb329b3edede926d9033d302e9f3be3877b9b89;hb=60b20d7161793595eeba33187d8d0221d0faf147;hpb=86062c9ff866c6dbcd8e2826093719ce1a1e9809
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index ecb329b3..8323f9f6 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -1,4 +1,9 @@
-
+
+
+
+
+]>
+&p-intro;
+
+
+ You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/.
+ Please see the Contact section of the User Manual on how to contact the
+ developers.
+
@@ -57,28 +72,106 @@ Please see the Contact section in the user-manual if you want to contact the dev
Introduction
- To be filled.
-
+
+
+ Privoxy, as an heir to
+ Junkbuster, is an Open Source project
+ and licensed under the GPL. As such, Privoxy
+ development is potentially open to anyone who has the time, knowledge,
+ and desire to contribute in any capacity. Our goals are simply to
+ continue the mission, to improve Privoxy, and
+ to make it available to as wide an audience as possible.
+
+
+ One does not have to be a programmer to contribute. Packaging, testing,
+ and porting, are all important jobs as well.
+
Quickstart to Privoxy Development
- To be filled.
+
+You'll need an account on Sourceforge to support our development.
+Mail your ID to the list and wait until a project manager has added you.
-
+
+For the time being (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 are in SGML format and located in the doc/source directory.
+ All formal documents are maintained in docbook SGML and located
+ in the doc/source directory. You will
+ need docbook and the
+ docbook stylesheets (or comparable alternatives), and either
+ jade or openjade
+ installed in order to build docs from source. Currently there is
+ user-manual,
+ FAQ,
+ and, of course this, the developer-manual in
+ this format.
+
+
+ Other, less formal documents (e.g. README, LICENSE) are
+ maintained as plain text files in the toplevel source
+ directory.
+
+
+ Packagers are encouraged to include this documentation. For those
+ without the ability to build the docs locally, text versions of
+ each are kept in CVS. Or HTML versions can be downloaded from the www.privoxy.org website, which
+ should be fairly current.
+
+
+ Formal documents are built with the Makefile targets of
+ make dok, or alternately
+ make redhat-dok. If you
+ have problems, try both. The build process uses the document
+ SGML sources in doc/source to
+ update all text files in doc/text
+ and to update all HTML documents in
+ doc/webserver.
- How do you update the webserver (i.e. the pages on sourceforge)?
+ Documentation writers should please make sure documents build
+ successfully before committing to CVS.
+
+
+ How do you update the webserver (i.e. the pages on privoxy.org)?
- 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.
+ First, build the docs by running make
+ dok (or alternately make
+ redhat-dok).
Run make webserver which copies all files from
@@ -1219,7 +1312,7 @@ static void unload_re_filterfile( void *f ) { ... }
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.8 2002/03/23 15:13:11 swa Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
@@ -1227,7 +1320,7 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.8 2002/03/23 15:13:1
* Purpose : (Fill me in with a good description!)
*
* Copyright : Written by and Copyright (C) 2001 the SourceForge
- * PRIVOXY 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
@@ -1279,7 +1372,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.8 2002/03/23 15:13:11 swa Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
@@ -1287,7 +1380,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
- * PRIVOXY 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
@@ -1377,8 +1470,8 @@ int FUNCTION_NAME( void *param1, const char *x )
Version Control Guidelines
- To be filled. note on cvs comments. don't comment what you did, comment
-why you did it.
+ To be filled. note on cvs comments. Don't only comment what you did,
+ but also why you did it!
@@ -1390,7 +1483,7 @@ why you did it.
Testplan for releases
-Explain release numbers. major, minor. developer releases. etc.
+ Explain release numbers. major, minor. developer releases. etc.
@@ -1436,22 +1529,550 @@ at sourceforge. Three simple steps:
+
+
+ Releasing a new version
+
+ To minimize trouble with distribution contents, webpage
+ errors and the like, we 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), autoconf, cvs, ???.
+
+
+
+ Before the Release
+
+ The following must be done by one of the
+ developers prior to each new release:
+
+
+
+
+
+ Make sure that everybody who has worked on the code in the last
+ couple of days has had a chance to yell no!
in case
+ they have pending changes/fixes in their pipelines.
+
+
+
+
+ Increment the version number in configure.in in
+ CVS. Also, the RPM release number in
+ configure.in. Do NOT touch version information
+ after export from CVS. All packages will use the
+ version and release data from configure.in.
+ Local files should not be changed, except prior to a CVS commit!!!
+ This way we are all on the same page!
+
+
+
+
+ If the default actionsfile has changed since last release,
+ bump up its version info in this line:
+
+
+
+ {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
+
+
+
+ Then change the version info in doc/webserver/actions/index.php,
+ line: '$required_actions_file_version = "A.B";'
+
+
+
+
+ Tag all files in CVS with the version number with
+ cvs tag v_X_Y_Z
(where X = major, Y
+ = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
+ etc.
+
+
+
+
+ The first package uploaded should be the official
+ tarball
release. This is built with the
+ make tarball-dist
Makefile
+ target, and then can be uploaded with
+ make tarball-upload
(see below).
+
+
+
+
+
+
+ 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
+ (or make redhat-dok
) creates
+ doc/webserver/user-manual,
+ doc/webserver/developer-manual,
+ doc/webserver/faq and
+ doc/webserver/man-page automatically.
+
+
+ Please do NOT use any other means of transferring files to the
+ webserver. make webserver
not only
+ uploads, but will make sure that the appropriate permissions are
+ preserved for shared group access.
+
+
+
+ SuSE or Red Hat
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ first.
+
+
+
+ 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
+
+
+
+ Go to the displayed URL and release the file publicly on Sourceforge.
+
+
+
+ OS/2
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd ..
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
+
+
+
+ You will need a mix of development tools.
+ The main compilation takes place with IBM Visual Age C++.
+ Some ancillary work takes place with GNU tools, available from
+ various sources like hobbes.nmsu.edu.
+ Specificially, you will need autoheader,
+ autoconf and sh tools.
+ The packaging takes place with WarpIN, available from various sources, including
+ its home page: xworkplace.
+
+
+ Change directory to the os2setup directory.
+ Edit the os2build.cmd file to set the final executable filename.
+ For example,
+
+ installExeName='privoxyos2_setup_2.9.13_beta.exe'
+
+ Next, edit the IJB.wis file so the release number matches
+ in the PACKAGEID section:
+
+ PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\2\9\13"
+
+ You're now ready to build. Run:
+
+ os2build
+
+ And in the ./files directory you will have the WarpIN-installable executable.
+ Upload this to uploads.sourceforge.net/incoming, create a release for it, and
+ you're done.
+
+
+
+ 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 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ If not, please checkout
+ Privoxy via CVS first. 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 publicly.
+
+
+
+ Windows
+
+ Ensure that you have the latest code version. Hence run
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ Run:
+
+
+
+ autoheader && autoconf && ./configure
+
+
+
+ Then do FIXME.
+
+
+
+ Debian
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ first. 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 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ If not, please checkout
+ Privoxy via CVS first. 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 publicly.
+
+
+
+ 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 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ If not, please checkout
+ Privoxy via CVS first. 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 publicly.
+
+
+
+ Tarball
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ first. 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 publicly on Sourceforge.
+
+
+
+ HP-UX 11
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ first. Run:
+
+
+
+ autoheader && autoconf && ./configure
+
+
+
+ Then do FIXME.
+
+
+
+ Amiga OS
+
+ Ensure that you have the latest code version. Hence run:
+
+
+
+ cd current
+ cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ first. 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 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+
+
+
+ If not, please checkout
+ Privoxy via CVS first. 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 publicly.
+
+
+
+
Contact the developers
- Please see the user manual for information on how to contact the developers.
+
+ Please see the contact page in the user-manual for details.
Copyright and History
- Please see the user manual for information on Copyright and History.
-
+
+ Please see the user-manual for
+ information on Copyright and History.
+
See also
- Please see the user manual for information on references.
+
+ Please see the user-manual for others
+ references.
@@ -1476,6 +2097,38 @@ at sourceforge. Three simple steps:
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.18 2002/04/03 03:51:48 hal9
+ Touch ups.
+
+ Revision 1.17 2002/04/03 01:21:17 hal9
+ Implementing Andreas's suggestions for Release sections.
+
+ Revision 1.16 2002/03/31 23:04:40 hal9
+ Fleshed out the doc section, and added something for an intro so it was not
+ blank.
+
+ Revision 1.15 2002/03/30 22:29:47 swa
+ wrong make flavour
+
+ 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