<!entity seealso SYSTEM "seealso.sgml">
<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
-<!entity p-version "2.9.14">
+<!entity p-version "2.9.13">
<!entity p-status "beta">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<artheader>
<title>Privoxy Developer Manual</title>
- <pubdate>$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $</pubdate>
<authorgroup>
<author>
<!-- Include privoxy.sgml boilerplate text: -->
-<!-- &p-intro; Someone interested enough in the project to contribute
- will already know at this point what Privoxy is. -->
+ &p-intro;
<!-- end boilerplate -->
<para>
You can find the latest version of the this manual at <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
- Please see <ulink url="contact.html">the Contact section</ulink>
- on how to contact the developers.
+ Please see the Contact section on how to contact the developers.
</para>
<!-- <para> -->
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="quickstart"><title>Quickstart to Privoxy Development</title>
<para>
- You'll need an account on <ulink
- url="http://sourceforge.net/">Sourceforge</ulink> to support our
- development. Mail your ID to <ulink
- url="mailto:developers@privoxy.org">the list</ulink> and wait until a
- project manager has added you.
- </para>
- <para>
- For the time being (read, this section is under construction), please
- refer to the extensive comments in the source code.
- </para>
- </sect1>
-
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="cvs"><title>The CVS Repository</title>
- <para>
- If you intend to help us with programming, documentation or packaging
- you will need write access to our holy grail, the CVS repository.
- Please read this chapter completely before accessing via CVS.
- </para>
-
- <sect2 id="cvsaccess"><title>Access to CVS</title>
- <para>
- The project's CVS repository is hosted on
- <ulink url="http://sourceforge.net/">SourceForge.</ulink>
- Please refer to the chapters 6 and 7 in
- <ulink url="http://sourceforge.net/docman/?group_id=1">SF's site
- documentation</ulink> for the technical access details for your
- operating system. For historical reasons, the CVS server is
- called <literal>cvs.ijbswa.sourceforge.net</literal>, the repository is
- called <literal>ijbswa</literal>, and the source tree module is called
- <literal>current</literal>.
- </para>
- </sect2>
-
- <sect2 id="cvscommit"><title>CVS Commit Guideline</title>
- <para>
- The source tree is the heart of every software project. Every effort must
- be made to ensure that it is readable, compilable and consistent at all
- times. We therefore ask anyone with CVS access to strictly adhere to the
- following guidelines:
- <itemizedlist>
- <listitem><para>
- Never (read: <emphasis>never, ever</emphasis>) be tempted to commit
- that small change without testing it thoroughly first. When we're
- close to a public release, ask a fellow developer to review your
- changes.
- </para></listitem>
- <listitem><para>
- Your commit message should give a concise overview of <emphasis>what you
- changed</emphasis> (no big details) and <emphasis>why you changed it</emphasis>
- Just check previous messages for good examples.
- </para></listitem>
- <listitem><para>
- Don't use the same message on multiple files, unless it equally applies to
- all those files.
- </para></listitem>
- <listitem><para>
- If your changes span multiple files, and the code won't recompile unless
- all changes are commited (e.g. when changing the signature of a function),
- then commit all files one after another, without long delays in beween.
- If necessary, prepare the commit messages in advance.
- </para></listitem>
- <listitem><para>
- Before changing things on CVS, make sure that your changes are in line
- with the team's general consensus on what should be done (see below).
- </para></listitem>
- </itemizedlist>
- </para>
- </sect2>
+You'll need an account on <ulink
+url="http://sourceforge.net">Sourceforge</ulink> to support our development.
+Mail your ID to the list and wait until a project manager has added you.
+</para>
- <sect2 id="cvswhenask"><title>Discussing Changes First</title>
- <para>
- We don't have a too formal policy on this, just use common sense. Hints: If it is..
- <orderedlist numeration="arabic">
- <listitem><para>
- ..a bugfix / clean-up / cosmetic thing: shoot
- </para></listitem>
- <listitem><para>
- ..a new feature that can be turned off: shoot
- </para></listitem>
- <listitem><para>
- ..a clear improvement w/o side effects on other parts of the code: shoot
- </para></listitem>
- <listitem><para>
- ..a matter of taste: <ulink url="mailto:developers@privoxy.org">ask the list</ulink>
- </para></listitem>
- <listitem><para>
- ..a major redesign of some part of the code: <ulink url="mailto:developers@privoxy.org">ask
- the list</ulink>
- </para></listitem>
- </orderedlist>
- </para>
- <para>
- Note that near a major public release, we get a bit more cautious - if
- unsure, it doesn't hurt to ask first. There is always the possibility
- to submit a patch to the <ulink
- url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patches
- tracker</ulink> instead.
- </para>
- </sect2>
- </sect1>
+<para>
+For the time being (read, this section is under construction), please note the
+following guidelines for changing stuff in the code. If it is
+ <orderedlist numeration="arabic">
+ <listitem><para>
+ A bugfix / clean-up / cosmetic thing: shoot
+ </para></listitem>
+ <listitem><para>
+ A new feature that can be turned off: shoot
+ </para></listitem>
+ <listitem><para>
+ A clear improvement w/o side effects on other parts of the code: shoot
+ </para></listitem>
+ <listitem><para>
+ A matter of taste: ask the list
+ </para></listitem>
+ <listitem><para>
+ A major redesign of some part of the code: ask the list
+ </para></listitem>
+ </orderedlist>
+ </para>
+</sect1>
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="documentation"><title>Documentation Guidelines</title>
<para>
- All formal documents are maintained in Docbook SGML and located in the
+ All formal documents are maintained in docbook SGML and located in the
<computeroutput>doc/source/*</computeroutput> directory. You will need
<ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<filename>INSTALL</filename>) are maintained as plain text files in the
- top-level source directory. At least for the time being.
+ toplevel source directory. At least for the time being.
</para>
<para>
Packagers are encouraged to include this documentation. For those without
</para>
<para>
Documentation writers should please make sure documents build
- successfully before committing to CVS, if possible.
+ successfully before committing to CVS.
</para>
<para>
How do you update the webserver (i.e. the pages on privoxy.org)?
</orderedlist>
</para>
- <para>
- Finished docs should be occasionally submitted to CVS
- (<filename>doc/webserver/*/*.html</filename>) so that those without
- the ability to build them locally, have access to them if needed.
- This is especially important just prior to a new release! Please
- do this <emphasis>after</emphasis> the <literal>$VERSION</literal> and
- other release specific data in <filename>configure.in</filename> has been
- updated (this is done just prior to a new release).
- </para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="sgml">
Some common elements that you likely will use:
</para>
-<para>
- <simplelist>
- <member>
- <emphasis><para></para></emphasis>, paragraph delimiter. Most
- text needs to be within paragraph elements (there are some exceptions).
- </member>
- <member>
- <emphasis><emphasis></emphasis></emphasis>, the stylesheets
- make this italics.
- </member>
- <member>
- <emphasis><filename></filename></emphasis>, files and directories.
- </member>
- <member>
- <emphasis><command></command></emphasis>, command examples.
- </member>
- <member>
- <emphasis><literallayout></literallayout></emphasis>, like
- <literal><pre></literal>, more or less.
- </member>
- <member>
- <emphasis><itemizedlist></itemizedlist></emphasis>, list with bullets.
- </member>
- <member>
- <emphasis><listitem></listitem></emphasis>, member of the above.
- </member>
- <member>
- <emphasis><screen></screen></emphasis>, screen output, implies
- <literal><literallayout></literal>.
- </member>
- <member>
- <emphasis><ulink url="example.com"></ulink></emphasis>, like
- HTML <literal><a></literal> tag.
- </member>
- <member>
- <emphasis><quote></quote></emphasis>, for, doh, quoting text.
- </member>
- </simplelist>
-</para>
+<simplelist>
+ <member>
+ <emphasis><para></para></emphasis>, paragraph delimiter. Most
+ text needs to be within paragraph elements (there are some exceptions).
+ </member>
+ <member>
+ <emphasis><emphasis></emphasis></emphasis>, the stylesheets make this
+ italics.
+ </member>
+ <member>
+ <emphasis><filename></filename></emphasis>, files and directories.
+ </member>
+ <member>
+ <emphasis><command></command></emphasis>, command examples.
+ </member>
+ <member>
+ <emphasis><literallayout></literllayout></emphasis>, like
+ <literal><pre></literal>, more or less.
+ </member>
+ <member>
+ <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
+ </member>
+ <member>
+ <emphasis><listitem></listitem></emphasis>, member of the above.
+ </member>
+ <member>
+ <emphasis><screen></screen></emphasis>, screen output, implies
+ <literal><literallayout></literal>.
+ </member>
+ <member>
+ <emphasis><ulink url="example.com"></ulink></emphasis>, like
+ HTML <literal><a></literal> tag.
+ </member>
+ <member>
+ <emphasis><quote></quote></emphasis>, for, doh, quoting text.
+ </member>
+</simplelist>
<para>
Look at any of the existing docs for examples of all these and more.
</sect2>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="docstyle">
<title><application>Privoxy</application> Documentation Style</title>
<listitem>
<para>
We have an international audience. Refrain from slang, or English
- idiosyncrasies (too many to list :). Humor also does not translate
- well sometimes.
+ idiosyncrasies (too many to list :).
</para>
</listitem>
<listitem>
<para>
Try to keep overall line lengths in source files to 80 characters or less
- for obvious reasons. This is not always possible, with lengthy URLs for
+ for obvious reasons. This is not always possible, with lenghty URLs for
instance.
</para>
</listitem>
<itemizedlist>
<listitem>
<para>
- Re- <quote>boilerplate</quote> text entities are defined like:
+ Re-cyclable <quote>boilerplate</quote> text entities are defined like:
</para>
<para>
<literal><!entity supported SYSTEM "supported.sgml"></literal>
<simplelist>
<member>
<emphasis>p-version</emphasis>: the <application>Privoxy</application>
- version string, e.g. <quote>&p-version;</quote>.
+ version string, e.g. <quote>2.9.13</quote>.
</member>
<member>
<emphasis>p-status</emphasis>: the project status, either
- <quote>alpha</quote>, <quote>beta</quote>, or <quote>stable</quote>.
+ <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
</member>
<member>
<emphasis>p-not-stable</emphasis>: use to conditionally include
- text in <quote>not stable</quote> releases (e.g. <quote>beta</quote>).
+ text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
</member>
<member>
<emphasis>p-stable</emphasis>: just the opposite.
<para><emphasis>Exception:</emphasis></para>
<para>If you are trying to add a small logic comment and do not
- wish to "disrupt" the flow of the code, feel free to use a 1
+ wish to "disrubt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.</para>
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and separate words via an underscore
+ <para>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.
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and separate words via an underscore
+ <para>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.
<para><emphasis>Note:</emphasis> In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
- condition that is obvious from the purpose of the block,
+ 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.</para>
- <para><emphasis>Status:</emphasis> developer-discretion.</para>
+ <para><emphasis>Status:</emphasis> developer-discrection.</para>
<para><emphasis>Example exception:</emphasis></para>
<programlisting>
<para>if ( condition ) { structure->flag = 1; } else {
structure->flag = 0; }</para>
- <para><emphasis>Note:</emphasis> The former is readable and concise. The later
+ <para><emphasis>Note:</emphasis> 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-)</para>
function2( ... ) { }</para>
<para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
- lines afterward. This makes the end of function standout to
+ lines afterwards. This makes the end of function standout to
the most casual viewer. Although function comments help
- separate functions, this is still a good coding practice. In
+ seperate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!</para>
- <para><emphasis>Status:</emphasis> developer-discretion on the number of blank
+ <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
lines. Enforced is the end of function comments.</para>
and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
arrayPtr[0].</para>
- <para><emphasis>Status:</emphasis> developer-discretion if and only if the
+ <para><emphasis>Status:</emphasis> developer-discrection if and only if the
variable is assigned a value "shortly after" declaration.</para>
</sect3>
<para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behavior.</para>
+ "file.h" behaviour.</para>
</sect3>
<para><emphasis>Note:</emphasis> 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 unnecessary.</para>
+ file is unneccessary.</para>
- <para><emphasis>Status:</emphasis> Use with discretion.</para>
+ <para><emphasis>Status:</emphasis> Use with discrection.</para>
</sect3>
default :
log_error( ... );
- ... anomaly code goes here ...
+ ... anomly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */</programlisting>
This API call *should* be included in a default statement.</para>
<para><emphasis>Another Note:</emphasis> This is not so much a readability issue
- as a robust programming issue. The "anomaly code goes here" may
+ 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.</para>
on 1 line. You should, although, provide a good comment on
their functions.</para>
- <para><emphasis>Status:</emphasis> developer-discretion.</para>
+ <para><emphasis>Status:</emphasis> developer-discrection.</para>
</sect3>
<para><emphasis>Explanation:</emphasis></para>
- <para>Create a local struct (on the stack) if the variable will
+ <para>Create a local stuct (on the stack) if the variable will
live and die within the context of one function call.</para>
<para>Only "malloc" a struct (on the heap) if the variable's life
<para><emphasis>Example:</emphasis></para>
<programlisting>
If a function creates a struct and stores a pointer to it in a
-list, then it should definitely be allocated via `malloc'.
+list, then it should definately be allocated via `malloc'.
</programlisting>
</sect3>
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accommodate this.</para>
+ free/unload/destuctor type function to accomodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
functions for C run-time library functions ... such as
`strdup'.</para>
- <para><emphasis>Status:</emphasis> developer-discretion. The "main" use of this
+ <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</para>
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- existing code, use FIXME</title>
+ exitinst code, use FIXME</title>
<para><emphasis>Explanation:</emphasis></para>
<para>If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the repercussions,
+ your changes, but are not *quite* sure of the reprocussions,
add this:</para>
<para>/* FIXME: this code has a logic error on platform XYZ, *
- attempting to fix */ #ifdef PLATFORM ...changed code here...
+ attempthing to fix */ #ifdef PLATFORM ...changed code here...
#endif</para>
<para>or:</para>
<para><emphasis>Note:</emphasis> 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 conversely exclude from the
+ include in the project (or conversly exclude from the
project).</para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<para><emphasis>Note:</emphasis> The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
- skip the verbiage and get to the heart of the code (via
+ skip the verbige and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</para>
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.33 2002/04/12 03:49:53 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
</sect1>
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="cvs"><title>Version Control Guidelines</title>
+ <para>To be filled. note on cvs comments. Don't only comment what you did,
+ but also why you did it!
+</para>
+ </sect1>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="testing"><title>Testing Guidelines</title>
<para>To be filled.
</sect1>
<!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="newrelease"><title>Releasing a New Version</title>
+ <sect1 id="newrelease"><title>Releasing a new version</title>
<para>
- When we release versions of <application>Privoxy</application>,
- our work leaves our cozy secret lab and has to work in the cold
- RealWorld[tm]. Once it is released, there is no way to call it
- back, so it is very important that great care is taken to ensure
- that everything runs fine, and not to introduce problems in the
- very last minute.
+ 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.
</para>
- <para>
- So when releasing a new version, please adhere exactly to the
- procedure outlined in this chapter.
- </para>
-
<para>
The following programs are required to follow this process:
- <filename>ncftpput</filename> (ncftp), <filename>scp, ssh</filename> (ssh),
- <filename>gmake</filename> (GNU's version of make), autoconf, cvs.
+ <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
+<filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
</para>
-
<para>
- In the following text, replace X, Y and Z with the actual version number
- (X = major, Y = minor, Z = point):
+ Replace X, Y and Z with the actual version number (X = major, Y = minor, Z = point):
</para>
<sect2 id="beforerelease">
</listitem>
<listitem>
<para>
- Increment the version number and increase or reset the RPM release number
- in <filename>configure.in</filename> as appropriate.
+ Increment the version number in <filename>configure.in</filename> in
+ CVS. Also, inrease or reset the RPM release number in
+ <filename>configure.in</filename> as appropriate. Do <emphasis>NOT</emphasis>
+ touch version information after export from CVS.
+ <emphasis>All packages</emphasis> will use the version and release data
+ from <filename>configure.in</filename>.
+ Local files should not be changed, except prior to a CVS commit!!!
+ This way we are all on the same page!
</para>
</listitem>
<listitem>
<para>
- If the default <filename>actionsfile</filename> has changed since last
- release, bump up its version info in this line:
+ If the default actionsfile has changed since last release,
+ bump up its version info in this line:
</para>
<para>
<programlisting>
Then change the version info in doc/webserver/actions/index.php,
line: '$required_actions_file_version = "A.B";'
</para>
- </listitem>
- <listitem>
- <para>
- If the HTML documentation is not in sync with the SGML sources
- you need to regenerate it. (If in doubt, just do it.) See the
- Section "Updating the webserver" in this manual for details.
- </para>
</listitem>
<listitem>
<para>
Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
</para>
</listitem>
+ <listitem>
+ <para>
+ The first package uploaded should be the official
+ <quote>tarball</quote> release. This is built with the
+ <quote><command>make tarball-dist</command></quote> Makefile
+ target, and then can be uploaded with
+ <quote><command>make tarball-upload</command></quote> (see below).
+ </para>
+ </listitem>
</itemizedlist>
</para>
</sect2>
- <sect2 id="therelease">
- <title>Building and Releasing the Packages</title>
- <para>
- Now the individual packages can be built and released. Note that for
- GPL reasons the first package to be released is always the source tarball.
- </para>
-
- <para>
- For <emphasis>all</emphasis> types of packages, including the source tarball,
- <emphasis>you must make sure that you build from clean sources by exporting
- the right version from CVS into an empty directory:</emphasis>.
- </para>
-
- <para>
- <programlisting>
- mkdir dist # delete or choose different name if it already exists
- cd dist
- 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
- </programlisting>
- </para>
-
- <para>
- <emphasis>Do NOT change</emphasis> a single bit, including, but not limited to
- version information after export from CVS. This is to make sure that
- all release packages, and with them, all future bug reports, are based
- on exactly the same code.
- </para>
-
- <para>
- Please find additional instructions for the source tarball and the
- individual platform dependent binary packages below.
- </para>
-
- <sect3 id="newrelease-tarball"><title>Source Tarball</title>
- <para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
- </para>
- <para>
- <programlisting>
- cd current
- autoheader && autoconf && ./configure
- </programlisting>
- </para>
- <para>
- Then do:
+ <sect2 id="newrelease-web"><title>Update the webserver</title>
+ <para>
+ 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 <filename>doc/webserver</filename> directory (or
+ create new directories under <filename>doc/webserver</filename>), then do
</para>
<para>
- <programlisting>
- make tarball-dist
+ <programlisting>
+ make webserver
</programlisting>
</para>
<para>
- To upload the package to Sourceforge, simply issue
+ Note that <quote><command>make dok</command></quote>
+ (or <quote><command>make redhat-dok</command></quote>) creates
+ <filename>doc/webserver/user-manual</filename>,
+ <filename>doc/webserver/developer-manual</filename>,
+ <filename>doc/webserver/faq</filename> and
+ <filename>doc/webserver/man-page</filename> automatically.
+ </para>
+ <para>
+ Please do NOT use any other means of transferring files to the
+ webserver. <quote><command>make webserver</command></quote> not only
+ uploads, but will make sure that the appropriate permissions are
+ preserved for shared group access.
+ </para>
+ </sect2>
+
+ <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
+ <para>
+ Ensure that you have the latest code version. Hence run:
</para>
<para>
<programlisting>
- make tarball-upload
+ 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 current
</programlisting>
</para>
<para>
- Go to the displayed URL and release the file publicly on Sourceforge.
- For the change log field, use the relevant section of the
- <filename>ChangeLog</filename> file.
- </para>
- </sect3>
-
- <sect3 id="newrelease-rpm"><title>SuSE or Red Hat</title>
- <para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ first.
</para>
<para>
<programlisting>
- cd current
autoheader && autoconf && ./configure
</programlisting>
</para>
</para>
<para>
<programlisting>
- make suse-dist (or make redhat-dist)
+ make suse-dist or make redhat-dist
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- make suse-upload (or make redhat-upload)
+ make suse-upload or make redhat-upload
</programlisting>
</para>
<para>
Go to the displayed URL and release the file publicly on Sourceforge.
- Use the release notes and çhange log from the source tarball package.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-os2"><title>OS/2</title>
+ <sect2 id="newrelease-os2"><title>OS/2</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then get the OS/2 Setup module:
+ Ensure that you have the latest code version. Hence run:
</para>
<para>
<programlisting>
+ 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
</programlisting>
</para>
Change directory to the <filename>os2setup</filename> directory.
Edit the os2build.cmd file to set the final executable filename.
For example,
- </para>
- <para>
<programlisting>
installExeName='privoxyos2_setup_X.Y.Z.exe'
</programlisting>
- </para>
- <para>
Next, edit the <filename>IJB.wis</filename> file so the release number matches
in the <filename>PACKAGEID</filename> section:
- </para>
- <para>
- <programlisting>
+ <programlisting>
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
</programlisting>
- </para>
- <para>
You're now ready to build. Run:
- </para>
- <para>
<programlisting>
os2build
</programlisting>
+ And in the <filename>./files</filename> directory you will have the
+ WarpIN-installable executable.
+ Upload this anonymously to
+ <filename>uploads.sourceforge.net/incoming</filename>, create a release
+ for it, and you're done.
</para>
- <para>
- You will find the WarpIN-installable executable in the
- <filename>./files</filename> directory. Upload this anonymously to
- <filename>uploads.sourceforge.net/incoming</filename>, create a release
- for it, and you're done. Use the release notes and Change Log from the
- source tarball package.
- </para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-solaris"><title>Solaris</title>
+ <sect2 id="newrelease-solaris"><title>Solaris</title>
<para>
- Login to Sourceforge's compilefarm via ssh:
+ Login to Sourceforge's compilefarm via ssh
</para>
<para>
<programlisting>
</programlisting>
</para>
<para>
- Choose the right operating system (not the Debian one).
- When logged in, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ Choose the right operating system (not the Debian one). If you have
+ downloaded <application>Privoxy</application> before,
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ If not, please <ulink
+ url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
+ Privoxy via CVS first</ulink>. Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly. Use the release notes and Change Log from the
- source tarball package.
+ the file publicly.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-windows"><title>Windows</title>
- <para>
- You should ensure you have the latest version of Cygwin (from
- <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>).
- Run the following commands from within a Cygwin bash shell.
- </para>
- <para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then get the Windows setup module:
- </para>
- <para>
- <programlisting>
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
- </programlisting>
- </para>
- <para>
- Then you can build the package. This is fully automated, and is
- controlled by <filename>winsetup/GNUmakefile</filename>.
- All you need to do is:
- </para>
- <para>
- <programlisting>
- cd winsetup
- make
- </programlisting>
- </para>
+ <sect2 id="newrelease-windows"><title>Windows</title>
<para>
- Now you can manually rename <filename>privoxy_setup.exe</filename> to
- <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
- SourceForge. When releasing the package on SourceForge, use the release notes
- and Change Log from the source tarball package.
- </para>
- </sect3>
+ Ensure that you have the latest code version. Hence run
+ </para>
+ <para>
+ <programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ Run:
+ </para>
+ <para>
+ <programlisting>
+ autoheader && autoconf && ./configure
+ </programlisting>
+ </para>
+ <para>
+ Then do FIXME.
+ </para>
+ </sect2>
- <sect3 id="newrelease-debian"><title>Debian</title>
+ <sect2 id="newrelease-debian"><title>Debian</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then, run:
+ Ensure that you have the latest code version. Hence run:
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ first. Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
<para>
Then do FIXME.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-macosx"><title>Mac OSX</title>
+ <sect2 id="newrelease-macosx"><title>Mac OSX</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then get the Mac OSX setup module:
+ Ensure that you have the latest code version. Hence run:
</para>
<para>
<programlisting>
+ 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 osxsetup
</programlisting>
</para>
<para>
- Then run:
- </para>
- <para>
+ From the osxsetup directory, run:
<programlisting>
- cd osxsetup
build
</programlisting>
</para>
name to match the release, and hit the "Create package" button.
If you specify ./Privoxy.pkg as the output package name, you can then create
the distributable zip file with the command:
- </para>
- <para>
<programlisting>
zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
</programlisting>
- </para>
- <para>
You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
<filename>uploads.sourceforge.net/incoming</filename>,
- create a release for it, and you're done. Use the release notes
- and Change Log from the source tarball package.
+ create a release for it, and you're done.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-freebsd"><title>FreeBSD</title>
+ <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
+ <para>
+ Change the version number of <application>Privoxy</application> in the
+ configure.in file. Run:
+ <programlisting>
+ autoheader && autoconf && ./configure
+ </programlisting>
+ Then ...
+ </para>
<para>
Login to Sourceforge's compilefarm via ssh:
</para>
</para>
<para>
Choose the right operating system.
- When logged in, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly. Use the release notes and Change Log from the
- source tarball package.
+ the file publicly.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-hpux"><title>HP-UX 11</title>
+ <sect2 id="newrelease-tarball"><title>Tarball</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ Ensure that you have the right code version. Hence run:
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ first. Run:
+ </para>
+ <para>
+ <programlisting>
+ autoheader && autoconf && ./configure
+ </programlisting>
+ </para>
+ <para>
+ Then do:
+ </para>
+ <para>
+ <programlisting>
+ make tarball-dist
+ </programlisting>
+ </para>
+ <para>
+ To upload the package to Sourceforge, simply issue
+ </para>
+ <para>
+ <programlisting>
+ make tarball-upload
+ </programlisting>
+ </para>
+ <para>
+ Goto the displayed URL and release the file publicly on Sourceforge.
+ </para>
+ </sect2>
+
+ <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
+ <para>
+ Ensure that you have the latest code version. Hence run:
+ </para>
+ <para>
+ <programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ first. Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
<para>
Then do FIXME.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-amiga"><title>Amiga OS</title>
+ <sect2 id="newrelease-amiga"><title>Amiga OS</title>
<para>
- First, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ Ensure that you have the latest code version. Hence run:
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ first. Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
<para>
Then do FIXME.
</para>
- </sect3>
+ </sect2>
- <sect3 id="newrelease-aix"><title>AIX</title>
+ <sect2 id="newrelease-aix"><title>AIX</title>
<para>
Login to Sourceforge's compilefarm via ssh:
</para>
</programlisting>
</para>
<para>
- Choose the right operating system.
- When logged in, <emphasis>make sure that you have freshly exported the right
- version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then run:
+ Choose the right operating system. If you have downloaded Privoxy
+ before:
</para>
<para>
<programlisting>
+ 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 current
+ </programlisting>
+ </para>
+ <para>
+ If not, please <ulink
+ url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
+ Privoxy via CVS first</ulink>. Run:
+ </para>
+ <para>
+ <programlisting>
autoheader && autoconf && ./configure
</programlisting>
</para>
which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
to manually upload the archive to Sourceforge's ftp server and release
- the file publicly. Use the release notes and Change Log from the
- source tarball package.
+ the file publicly.
</para>
- </sect3>
- </sect2>
-
- <sect2 id="afterrelease">
- <title>After the Release</title>
- <para>
- When all (or: most of the) packages have been uploaded and made available,
- send an email to the <ulink url="mailto:ijbswa-announce@lists.sourceforge.net">announce
- mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
- include the
- <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download
- location</ulink>, the release notes and the change log.
- </para>
- </sect2>
+ </sect2>
</sect1>
- <!-- ~~~~~ New section ~~~~~ -->
- <sect1 id="webserver-update"><title>Update the Webserver</title>
- <para>
- When updating the webserver, please follow these steps to make
- sure that no broken links, incosistent contents or permission
- problems will occur:
- </para>
- <para>
- If you have changed anything in the documentation source SGML files,
- do:
- </para>
- <para>
- <programlisting>
- make dok # (or make redkat-dok if make dok doesn't work for you)
- </programlisting>
- </para>
- <para>
- That will generate <filename>doc/webserver/user-manual</filename>,
- <filename>doc/webserver/developer-manual</filename>,
- <filename>doc/webserver/faq</filename> and
- <filename>doc/webserver/index.html</filename> automatically.
- </para>
- <para>
- If you changed the manual page source, generate
- <filename>doc/webserver/man-page/privoxy-man-page.html</filename>
- by running <quote><command>make man</command></quote>. (This is
- a separate target due to dependencies on some obscure perl scripts.
- See comments in <filename>GNUmakefile</filename>.)
- </para>
- <para>
- If you want to add new files to the webserver, create them locally in
- the <filename>doc/webserver/*</filename> directory (or
- create new directories under <filename>doc/webserver</filename>).
- </para>
- <para>
- Next, commit any changes from the above steps to CVS. All set? Then do
- </para>
- <para>
- <programlisting>
- make webserver
- </programlisting>
- </para>
- <para>
- This will do the upload to <ulink url="http://www.privoxy.org/">the
- webserver</ulink> (www.privoxy.org) and ensure all files and directories
- there are group writable.
- </para>
- <para>
- Please do <emphasis>NOT</emphasis> use any other means of transferring
- files to the webserver to avoid permission problems.
- </para>
- </sect1>
-
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
<!-- Include contacting.sgml -->
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
- Revision 1.33 2002/04/12 03:49:53 hal9
- Spell checked. Clarification on where docs are kept.
-
- Revision 1.32 2002/04/11 21:29:58 jongfoster
- Documenting Win32 release procedure
-
- Revision 1.31 2002/04/11 09:32:52 oes
- more nits
-
Revision 1.30 2002/04/11 09:24:53 oes
nits
projects / privoxy.git / blobdiff