X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=8323f9f60d5edaf56ebffcf99df9d562befe5656;hp=fd1e65bb089f5624f29c8f1e39fc99406d041e0f;hb=60b20d7161793595eeba33187d8d0221d0faf147;hpb=4cb100b1eb7a5ea7e9583e85e89b972480a2621b
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index fd1e65bb..8323f9f6 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -1,4 +1,9 @@
-
+
+
+
+
+]>
+&p-intro;
- 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.
-
-
-
- Privoxy is based on the code of the
- Internet Junkbuster.
- Junkbuster was originally written by JunkBusters
- Corporation, and was released as free open-source software under the GNU GPL.
- Stefan Waldherr made many improvements, and started the SourceForge project
- to continue development. Other developers have since joined Stefan.
-
-
-
- You can find the latest version of the user manual at http://www.privoxy.org/developer-manual/.
- Please see the Contact section in the user-manual if you want to contact the
+ Please see the Contact section of the User Manual on how to contact the
developers.
@@ -72,17 +72,36 @@
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
-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.
+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 beeing (read, this section is under construction), please note the
+
+For the time being (read, this section is under construction), please note the
following guidelines for changing stuff in the code. If it is
@@ -101,21 +120,58 @@ following guidelines for changing stuff in the code. If it is
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.
- How do you update the webserver (i.e. the pages on sourceforge)?
+ 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.
+
+
+ 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
@@ -1256,7 +1312,7 @@ static void unload_re_filterfile( void *f ) { ... }
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
@@ -1316,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.14 2002/03/30 19:04:08 swa Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.18 2002/04/03 03:51:48 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
@@ -1414,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!
@@ -1427,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.
@@ -1478,15 +1534,78 @@ at sourceforge. Three simple steps:
Releasing a new version
To minimize trouble with distribution contents, webpage
- errors and the like, I (Stefan) strongly encourage you
+ 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), ???.
+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
@@ -1495,43 +1614,43 @@ at sourceforge. Three simple steps:
create new directories under doc/webserver), then do
-
- make webserver
+
+ make webserver
- Note that make dok creates
+ 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.
- Verify on the webserver that the permissions are set correctly. Do
- NOT use any other means of transferring files to the webserver.
+ 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 RedHat
+ SuSE or Red Hat
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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. 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
+ first.
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1539,7 +1658,7 @@ at sourceforge. Three simple steps:
- make suse-dist or make redhat-dist
+ make suse-dist or make redhat-dist
@@ -1547,35 +1666,56 @@ at sourceforge. Three simple steps:
- make suse-upload or make redhat-upload
+ make suse-upload or make redhat-upload
- Goto the displayed URL and release the file publically on Sourceforge.
+ Go to the displayed URL and release the file publicly on Sourceforge.
OS/2
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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
- first. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ 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.
-
- autoheader && autoconf && ./configure
+ 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'
-
-
- Then do FIXME.
+ 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.
@@ -1585,28 +1725,28 @@ at sourceforge. Three simple steps:
- ssh cf.sourceforge.net
+ ssh cf.sourceforge.net
Choose the right operating system (not the Debian one). If you have
- downloaded Privoxy before,
+ downloaded Privoxy before,
- cd current && cvs update .
+ 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. Verify the version number in
- configure.in. If necessary, change the version
- number. Run
+ Privoxy via CVS first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1614,14 +1754,14 @@ at sourceforge. Three simple steps:
- gmake solaris-dist
+ 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
+ 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
+ the file publicly.
@@ -1631,17 +1771,17 @@ at sourceforge. Three simple steps:
- cvs update .
+ 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. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1651,21 +1791,21 @@ at sourceforge. Three simple steps:
Debian
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1679,7 +1819,7 @@ at sourceforge. Three simple steps:
- ssh cf.sourceforge.net
+ ssh cf.sourceforge.net
@@ -1688,52 +1828,52 @@ at sourceforge. Three simple steps:
- cd current && cvs update .
+ 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. Verify the version number in
- configure.in. If necessary, change the version
- number. Run
+ Privoxy via CVS first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
- Then run
+ Then run:
- make macosx-dist
+ 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
+ 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
+ the file publicly.
FreeBSD
Change the version number of Privoxy in the
- configure.in file. Run
+ configure.in file. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
Then ...
- Login to Sourceforge's compilefarm via ssh
+ Login to Sourceforge's compilefarm via ssh:
- ssh cf.sourceforge.net
+ ssh cf.sourceforge.net
@@ -1742,63 +1882,63 @@ at sourceforge. Three simple steps:
- cd current && cvs update .
+ 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. Verify the version number in
- configure.in. If necessary, change the version
- number. Run
+ Privoxy via CVS first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
- Then run
+ Then run:
- gmake freebsd-dist
+ 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
+ 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
+ the file publicly.
Tarball
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ first. Run:
- make clobber
- autoheader && autoconf && ./configure
+ make clobber
+ autoheader && autoconf && ./configure
- Then do
+ Then do:
- make tarball-dist
+ make tarball-dist
@@ -1806,31 +1946,31 @@ at sourceforge. Three simple steps:
- make tarball-upload
+ make tarball-upload
- Goto the displayed URL and release the file publically on Sourceforge.
+ Goto the displayed URL and release the file publicly on Sourceforge.
HP-UX 11
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1840,21 +1980,21 @@ at sourceforge. Three simple steps:
Amiga OS
- Ensure that you have the latest code version. Hence run
+ Ensure that you have the latest code version. Hence run:
- cvs update .
+ 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. If necessary, change the version number of
- Privoxy in the
- configure.in file. Run
+ first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
@@ -1864,47 +2004,47 @@ at sourceforge. Three simple steps:
AIX
- Login to Sourceforge's compilefarm via ssh
+ Login to Sourceforge's compilefarm via ssh:
- ssh cf.sourceforge.net
+ ssh cf.sourceforge.net
Choose the right operating system. If you have downloaded Privoxy
- before,
+ before:
- cd current && cvs update .
+ 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. Verify the version number in
- configure.in. If necessary, change the version
- number. Run
+ Privoxy via CVS first. Run:
- autoheader && autoconf && ./configure
+ autoheader && autoconf && ./configure
- Then run
+ Then run:
- make aix-dist
+ 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
+ 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
+ the file publicly.
@@ -1912,19 +2052,27 @@ at sourceforge. Three simple steps:
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.
@@ -1949,6 +2097,19 @@ 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.