<!entity p-intro SYSTEM "privoxy.sgml">
<!entity history SYSTEM "history.sgml">
<!entity seealso SYSTEM "seealso.sgml">
-<!entity p-version "3.0.32">
+<!entity p-version "3.0.35">
<!entity p-status "UNRELEASED">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
Purpose : developer manual
- Copyright (C) 2001-2021 Privoxy Developers https://www.privoxy.org/
+ Copyright (C) 2001-2023 Privoxy Developers https://www.privoxy.org/
See LICENSE.
========================================================================
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
<ulink url="https://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
- &my-copy; 2001-2021 by
+ &my-copy; 2001-2023 by
<ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
2020-12-14 12:17:56: Ooops. Expected removal but: 'Referer: https://p.p/' is still there.
2020-12-14 12:17:56: Failure for test 785 (0/13/5). Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-block}'
2020-12-14 12:17:56: Executed 1 regression tests. Skipped 1201. 0 successes, 1 failures.
- </programlisting>
+</programlisting>
<para>
Use the if the <command>--privoxy-address</command> option if the
http_proxy environment variable isn't configured and you don't want
</listitem>
<listitem>
<para>
- Update the code status (CODE_STATUS="xxx") in configure.in to one of
+ Update the code status (CODE_STATUS="xxx") in <filename>configure.in</filename> to one of
"alpha", "beta" or "stable".
</para>
</listitem>
<para>
If action file processing has changed and is not backward-compatible,
make sure the "for-privoxy-version=x.y.z" minimum version number in
- default.action.master has been updated:
+ <filename>default.action.master</filename> has been updated:
</para>
<programlisting>
{{settings}}
Create the change log:
</para>
<programlisting>
- $ git tag
- # to see the tags
- $ git log [last release tag]..master > /tmp/log
- # get the commit log since the last release
- $ utils/makeChangeLog /tmp/log > /tmp/change.log
- # reformat the commit log
+$ git tag
+# to see the tags
+$ git log [last release tag]..master > /tmp/log
+# get the commit log since the last release
+$ utils/makeChangeLog /tmp/log > /tmp/change.log
+# reformat the commit log
</programlisting>
<para>
Edit <filename>/tmp/change.log</filename> to remove trivial
<filename>doc/source/changelog.sgml</filename>:
</para>
<programlisting>
- $ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
+$ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml
</programlisting>
</listitem>
<listitem>
make sure noteworthy changes are referenced.
</para>
</listitem>
+ <listitem>
+ <para>
+ Update the announcement at <filename>doc/webserver/announce.txt</filename>.
+ </para>
+ </listitem>
<listitem>
<para>
All documentation should be rebuilt:
<programlisting>
- $ make man
- $ make dok
- $ make dok-man
- $ make dok-tidy
- $ make config-file
+$ make man
+$ make dok
+$ make dok-man
+$ make dok-tidy
+$ make config-file
</programlisting>
Finished docs should be then be committed to Git (for those
without the ability to build these). Some docs may require
Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
</para>
</listitem>
+ <listitem>
+ <para>
+ Push the tag to the remote with
+ <quote><command>git push origin v_X_Y_Z</command></quote>.
+ </para>
+ </listitem>
<listitem>
<para>
On the webserver, copy the user manual to a new top-level directory
</para>
<programlisting>
- mkdir dist # delete or choose different name if it already exists
- cd dist
- git clone https://www.privoxy.org/git/privoxy.git
- cd privoxy
- git checkout v_X_Y_Z
+mkdir dist # delete or choose different name if it already exists
+cd dist
+git clone https://www.privoxy.org/git/privoxy.git
+cd privoxy
+git checkout v_X_Y_Z
</programlisting>
<para>
packages" above). Then run from that directory:
</para>
<programlisting>
- autoheader && autoconf && ./configure
+autoheader && autoconf && ./configure
</programlisting>
<para>
Then do:
</para>
<programlisting>
- make tarball-dist
+make tarball-dist
</programlisting>
</sect3>
First, <emphasis>make sure that you have freshly exported the right
version into an empty directory</emphasis>. (See "Building and releasing
packages" above).
- <!-- XXX ??? are we still basing releases off a tarball???
- -->
</para>
+
+ <para>
+ Check that you have the current versions of the
+ <ulink url="https://sourceforge.net/projects/nsis/files/NSIS%203/">
+ NSIS installer</ulink>,
+ <ulink url="https://sourceforge.net/projects/pcre/files/pcre/">PCRE library</ulink>,
+ <ulink url="https://github.com/Mbed-TLS/mbedtls/tags">MBED TLS library</ulink>,
+ <ulink url="https://github.com/google/brotli/releases">
+ Brotli library</ulink>,
+ and that the <emphasis>MAKENSIS</emphasis> evar in
+ <filename>windows/GNUMakefile</filename>
+ points to the NSIS installer program. (See the
+ <ulink url="../user-manual/installation.html#WINBUILD-CYGWIN">
+ <emphasis>Building from Source / Windows</emphasis></ulink>
+ section of the User Manual for details.)
+ </para>
+
<para>
Then you can build the package. This is fully automated, and is
controlled by <filename>windows/GNUmakefile</filename>.
All you need to do is:
</para>
<programlisting>
- cd windows
- make
+cd windows
+make
</programlisting>
<para>
Now you can manually rename <filename>privoxy_setup.exe</filename> to
GPG sign the installer and zip file,
</para>
<programlisting>
- $ gpg --armor --detach --sign <filename>privoxy_setup_X.Y.Z.exe</filename>
- $ gpg --armor --detach --sign <filename>privoxy_X.Y.Z.zip</filename>
+gpg --armor --detach --sign <filename>privoxy_setup_X.Y.Z.exe</filename>
+gpg --armor --detach --sign <filename>privoxy_X.Y.Z.zip</filename>
</programlisting>
<para>
and upload the files to SourceForge.
Using git-buildpackage we start with a clone of the last Debian version:
</para>
<programlisting>
- gbp clone https://salsa.debian.org/debian/privoxy.git
- cd privoxy
+gbp clone https://salsa.debian.org/debian/privoxy.git
+cd privoxy
</programlisting>
<para>
or if the repository is already there
</para>
<programlisting>
- cd privoxy
- gbp pull
+cd privoxy
+gbp pull
</programlisting>
<para>
Now import the newly released upstream tarball via debian/watch file:
</para>
<programlisting>
- gbp import-orig --uscan
+gbp import-orig --uscan
</programlisting>
<para>
Next update all Debian quilt patches to the new version:
</para>
<programlisting>
- while quilt push; do quilt refresh; done
+while quilt push; do quilt refresh; done
</programlisting>
<para>
If some patch is no longer required (because it is already merged
upstream), it can be removed using
</para>
<programlisting>
- quilt delete XX_patchname.patch
- git rm debian/patches/XX_patchname.patch
+quilt delete XX_patchname.patch
+git rm debian/patches/XX_patchname.patch
</programlisting>
<para>
If the patch needs modification, you can apply, edit and update it with
</para>
<programlisting>
- quilt push -f
- quilt edit some_file
- quilt refresh
+quilt push -f
+quilt edit some_file
+quilt refresh
</programlisting>
<para>
until
</para>
<programlisting>
- while quilt push; do quilt refresh; done
+while quilt push; do quilt refresh; done
</programlisting>
<para>
succeeds. Then you can
</para>
<programlisting>
- quilt pop -a
+quilt pop -a
</programlisting>
<para>
Now add a new entry to the debian/changelog representing the new
version:
</para>
<programlisting>
- dch -v &p-version;-1
+dch -v &p-version;-1
</programlisting>
<para>
and describe what you did before and don't forget to git commit all
Now you can build the package on the local machine using
</para>
<programlisting>
- gbp buildpackage -us -uc
+gbp buildpackage -us -uc
</programlisting>
<para>
You should check for warnings using
</para>
<programlisting>
- lintian -iI ../build-area/privoxy_&p-version;-1_amd64.changes
+lintian -iI ../build-area/privoxy_&p-version;-1_amd64.changes
</programlisting>
<para>
Maybe rebuild the package in different defined cowbuilder environments
like
</para>
<programlisting>
- sudo cowbuilder --build --basepath /var/cache/pbuilder/base.cow ../build-area/privoxy_&p-version;-1.dsc
+sudo cowbuilder --build --basepath /var/cache/pbuilder/base.cow ../build-area/privoxy_&p-version;-1.dsc
</programlisting>
<para>
And try to run autopackage testing suite on the result:
</para>
<programlisting>
- autopkgtest /var/cache/pbuilder/result/privoxy_&p-version;-1_amd64.changes -s -- schroot sid
+autopkgtest /var/cache/pbuilder/result/privoxy_&p-version;-1_amd64.changes -s -- schroot sid
</programlisting>
<para>
Or just push the changes to salsa.debian.org, where a CI pipeline is
Then sign both files:
</para>
<programlisting>
- gpg --detach-sign --armor privoxy_&p-version;-1_i386.deb
- gpg --detach-sign --armor privoxy_&p-version;-1_amd64.deb
+gpg --detach-sign --armor privoxy_&p-version;-1_i386.deb
+gpg --detach-sign --armor privoxy_&p-version;-1_amd64.deb
</programlisting>
<para>
Create a README file containing the recent block from debian/changelog
run the following commands:
</para>
<programlisting>
- sudo apt install build-essential devscripts
- sudo apt-get build-dep privoxy
+sudo apt install build-essential devscripts
+sudo apt-get build-dep privoxy
</programlisting>
<para>
After this enter the checked out privoxy git tree and check that all
(new) build dependencies are met:
</para>
<programlisting>
- dpkg-checkbuilddeps
+dpkg-checkbuilddeps
</programlisting>
<para>
If something is missing, just add it using
</para>
<programlisting>
- sudo apt install foobar
+sudo apt install foobar
</programlisting>
<para>
Now you may update debian/changelog, especially the version number
using
</para>
<programlisting>
- dch
+dch
</programlisting>
<para>
and finally build the package:
</para>
<programlisting>
- debuild -us -uc -b
+debuild -us -uc -b
</programlisting>
<para>
If everything went okay, you may find the resulting Debian package in
You may want to clean up the build tree using
</para>
<programlisting>
- debian/rules clean
+debian/rules clean
</programlisting>
<para>
And maybe repair some artefacts using one or both of the following
commands:
</para>
<programlisting>
- git reset --hard
- git clean -fd
+git reset --hard
+git clean -fd
</programlisting>
</sect4>
</sect3>
- <sect3 id="newrelease-macosx"><title>Mac OS X</title>
+ <sect3 id="newrelease-macosx"><title>macOS / OS X</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).
</para>
<para>
- There are three modules available in the CVS repository backups for use on Mac
- OS X, though technically only two of them generate a release (the other
- can be used to install from source).
+ The OSXPackageBuilder module can generate OS X installer packages
+ supporting all Macs running OS X 10.4 and above. Obtain it from Git as
+ follows into a folder parallel to the exported privoxy source:
</para>
- <sect4 id="OS-X-OSXPackageBuilder-module">
- <title>OSXPackageBuilder module (Documentation out of date)</title>
- <para>
- The OSXPackageBuilder module generates OS X installer packages
- supporting all Macs running OS X 10.4 and above. Obtain it from CVS as
- follows into a folder parallel to the exported privoxy source:
- </para>
- <programlisting>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
-</programlisting>
- <para>
- The module contains complete instructions on its usage in the file
- <filename>OS X Package Builder HOWTO.txt</filename>.
- </para>
- <para>
- Once the package(s) have been generated, you can then upload them
- directly to the Files section of the Sourceforge project in the
- Macintosh (OS X) folder. Each new version release of Privoxy should
- have a new subfolder created in which to store its files. Please
- ensure that the folder contains a readme file that makes it clear
- which package is for whichversion of OS X.
- </para>
- </sect4>
- <sect4 id="OS-X-osxsetup-module">
- <title>osxsetup module (DEPRECATED) (Documentation out of date)</title>
- <para>
- <emphasis>This module is deprecated since the installer it generates
- places all Privoxy files in one folder in a non-standard location, and
- supports only Intel Macs running OS X 10.6 or higher.</emphasis>
- </para>
- <para>
- Check out the module from CVS as follows into a folder parallel to the
- exported privoxy source:
- </para>
- <programlisting>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
-</programlisting>
- <para>
- Then run:
- </para>
- <programlisting>
- cd osxsetup
- build
-</programlisting>
- <para>
- This will run <filename>autoheader</filename>, <filename>autoconf</filename>
- and <filename>configure</filename> as well as <filename>make</filename>.
- Finally, it will copy over the necessary files to the ./osxsetup/files
- directory for further processing by <filename>PackageMaker</filename>.
- </para>
- <para>
- Bring up PackageMaker with the PrivoxyPackage.pmsp definition file,
- modify the package 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>
- <programlisting>
- zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
-</programlisting>
- <para>
- You can then upload this file directly to the Files section of the
- Sourceforge project in the Macintosh (OS X) folder. Each new version
- release of Privoxy should have a new subfolder created in which to
- store its files.
- Please ensure that the folder contains a readme file that makes it
- clear which version(s) of OS X the package supports.
- </para>
- </sect4>
- <sect4 id="OS-X-macsetup-module">
- <title>macsetup module (Documentation out of date)</title>
- <para>
- The macsetup module is ideal if you wish to build and install Privoxy
- from source on a single machine.
- </para>
- <para>
- Check out the module from CVS as follows into a folder parallel to the
- exported privoxy source:
- </para>
- <programlisting>
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup
+ <programlisting>
+git clone ssh://git@git.privoxy.org:23/git/OSXPackageBuilder.git
</programlisting>
- <para>
- The module contains complete instructions on its usage in its
- <filename>README</filename> file. The end result will be the
- exported version of Privoxy installed on the build machine.
- </para>
- </sect4>
+ <para>
+ The module contains complete instructions on its usage in the file
+ <filename>OS X Package Builder HOWTO.txt</filename>.
+ </para>
+ <para>
+ Once the package(s) have been generated, you can then upload them
+ directly to the Files section of the Sourceforge project in the
+ Macintosh (OS X) folder. Each new version release of Privoxy should
+ have a new subfolder created in which to store its files. Please
+ ensure that the folder contains a readme file that makes it clear
+ which package is for which version of OS X.
+ </para>
</sect3>
<sect3 id="newrelease-freebsd"><title>FreeBSD</title>
</para>
</sect2>
+ <sect2 id="update-rss-feed">
+ <title>Updating the RSS feed</title>
+ <para>
+ Once the packages are uploaded to SourceForge they should be
+ mirrored on the Privoxy websites
+ (<ulink url="https://www.privoxy.org/">https://www.privoxy.org/</ulink>
+ and
+ <ulink url="http://l3tczdiiwoo63iwxty4lhs6p7eaxop5micbn7vbliydgv63x5zrrrfyd.onion/">http://l3tczdiiwoo63iwxty4lhs6p7eaxop5micbn7vbliydgv63x5zrrrfyd.onion/</ulink>).
+ This is usually done by Fabian who uses a couple of shell functions
+ for this that aren't documented or published yet.
+ </para>
+ <para>
+ Once the packages are uploaded to the mirror the RSS feed has to
+ be regenerated with a command like:
+ </para>
+ <programlisting>
+ fk@t520 ~/git/privoxy $utils/create-package-feed.pl /tank/backups/sourceforge/frs/project/ijbswa/ doc/webserver/feeds/privoxy-releases.xm
+ </programlisting>
+ <para>
+ The updated RSS feed then has to be uploaded to the SourceForge webserver
+ and mirrored on the Privoxy websites again. This, too, is usually done
+ by Fabian with undocumented and unpublished shell functions.
+ </para>
+ </sect2>
+
<sect2 id="afterrelease">
<title>After the Release</title>
<para>
SGML files, do:
</para>
<programlisting>
- make dok
+make dok && make dok-tidy
</programlisting>
<para>
That will generate <filename>doc/webserver/user-manual</filename>,
If these are docs in the stable branch, then do:
</para>
<programlisting>
- make webserver
+make webserver
</programlisting>
<para>
This will do the upload to the SourceForge webserver (which is manually