Purpose : Entity included in other project documents.
- $Id: buildsource.sgml,v 1.9.2.3 2003/11/06 13:36:37 oes Exp $
+ $Id: buildsource.sgml,v 2.5 2006/07/18 14:48:50 david__schmidt Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
README
-->
-
<para>
To build <application>Privoxy</application> from source,
<ulink url="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</ulink>,
<para>
When building from a source tarball (either release version or
+<!--
<ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.bz2">nightly CVS
- tarball</ulink>), first unpack the source:
+ url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">nightly CVS
+ tarball</ulink>),
+--> a nightly CVS tarball, first unpack the source:
</para>
<para>
<para>
For retrieving the current CVS sources, you'll need CVS installed.
Note that sources from CVS are development quality, and may not be
- stable, or well tested. To download CVS source:
+ stable, or well tested. To download CVS source, check the Sourceforge
+ documentation, which might give commands like:
</para>
<para>
<screen>
- cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
+ cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
cd current
</screen>
</para>
</para>
<para>
- Then, in either case, to build from unpacked tarball or CVS source:
+ You can also check out any <application>Privoxy</application>
+ <quote>branch</quote>, just exchange the <application>current</application>
+ name with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs
+ tree).
+</para>
+
+<para>
+ It is also strongly recommended to not run <application>Privoxy</application>
+ as root, and instead it is suggested to create a <quote>privoxy</quote> user
+ and group for this purpose. See your local documentation for the correct
+ command line to do this.
+</para>
+
+<para>
+ <filename>/etc/passwd</filename> might then look like:
+</para>
+
+<para>
+ <screen> privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</screen>
+</para>
+
+<para>
+ And then <filename>/etc/group</filename>, like:
+</para>
+
+<para>
+ <screen> privoxy:*:7777:</screen>
+</para>
+
+<para>
+ Some binary packages may do this for you.
+</para>
+
+<para>
+ Then, to build from either unpacked tarball or CVS source:
</para>
<para>
autoheader
autoconf
./configure # (--help to see options)
- make # (the make from gnu, gmake for *BSD)
+ make # (the make from GNU, sometimes called gmake)
su
make -n install # (to see where all the files will go)
- make install # (to really install)
-</screen>
+ make -s install # (to really install, -s to silence output)</screen>
</para>
<para>
- If you have gnu make, you can have the first four steps
+ If you have GNU <command>make</command>, you can have the first four steps
automatically done for you by just typing:
</para>
in the freshly downloaded or unpacked source directory.
</para>
+<para>
+ <emphasis>WARNING:</emphasis> If installing as root, the install will fail
+ unless a non-root user or group is specified, or a <literal>privoxy</literal>
+ user and group already exist on the system. If a non-root user is specified,
+ and no group, then the installation will try to also use a group of the same name
+ as <quote>user</quote>. If a group is specified (and no user), then the
+ support files will be installed as writable by that group, and owned by the
+ user running the installation.
+</para>
+
+<para>
+ <command>configure</command> accepts <literal>--with-user</literal> and
+ <literal>--with-group</literal> options for setting user and group ownership
+ of the configuration files (which need to be writable by the daemon). The
+ specified <emphasis>user must already exist</emphasis>. When starting
+ <application>Privoxy</application>, it should be run as this same user to
+ insure write access to configuration and log files.
+</para>
+
+<para>
+ Alternately, you can specify <literal>user</literal> and <literal>group</literal>
+ on the <command>make</command> command line, but be sure both already exist:
+</para>
+
+<para>
+ <screen>
+ make -s install USER=privoxy GROUP=privoxy</screen>
+</para>
+
+<para>
+ The default installation path for <command>make install</command> is
+ <filename>/usr/local</filename>. This may of course be customized with
+ the various <command>./configure</command> path options. If you are doing
+ a root install to anywhere else besides <filename>/usr/local</filename>, be
+ sure to set the appropriate paths with the correct configure options
+ (<command>./configure --help</command>).
+</para>
+
+<para>
+ If you do install to <filename>/usr/local</filename>, the install will use
+ <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
+ destinations, and the direct usage of <literal>--sysconfdir</literal> flag
+ behave like normal, i.e. will not add the extra <filename>privoxy</filename>
+ directory. This is for a safer install, as there may already exist another
+ program that uses a file with the <quote>config</quote> name, and thus makes
+ <filename>/usr/local/etc</filename> cleaner.
+</para>
+
+<para>
+ If installing to <filename>/usr/local</filename>, the docs will go by default
+ to <filename>$prefix/share/doc</filename>. But if this directory doesn't
+ exist, it will then try <filename>$prefix/doc</filename> and install there before
+ creating a new <filename>$prefix/share/doc</filename> just for
+ <application>Privoxy</application>.
+</para>
+
+<para>
+ Again, if the installs goes to <filename>/usr/local</filename>, the
+ <literal>localstatedir</literal> (ie: <filename>var/</filename>) will default
+ to <filename>/var</filename> instead of <literal>$prefix/var</literal> so
+ the logs will go to <filename>/var/log/privoxy/</filename>, and the pid file
+ will be created in <filename>/var/run/privoxy.pid</filename>.
+</para>
+
+<para>
+ <command>make install</command> will attempt to set the correct values
+ in <filename>config</filename> (main configuration file). You may want
+ to check this to make sure all values are correct. If appropriate,
+ an init script will be installed, but it is up to the user to determine
+ how and where to start <application>Privoxy</application>. The init
+ script should be checked for correct paths and values, if anything other than
+ a default install is done.
+</para>
+
+<para>
+ If install finds previous versions of any configuration files, these will not
+ be overwritten, and the new ones will be installed with a <quote>new</quote>
+ extension. You will then need to manually update the installed configuration
+ files as needed. All template files will be overwritten. If you have
+ customized, local templates, you should save these first. If a previous
+ version of <application>Privoxy</application> is already running, you will
+ have to restart it manually.
+</para>
+
<para>
For more detailed instructions on how to build Redhat and SuSE RPMs,
Windows self-extracting installers, building on platforms with
</para>
<!-- print for README only -->
+<!-- Actually this is now in INSTALL -->
<![%p-readme;[
- <para>
- For binary RPM installation, and other platforms, see the user-manual
- as well.
- </para>
+<para>
+ The simplest command line to start <application>Privoxy</application> is
+ <command>$path/privoxy --user=privoxy $path/etc/privoxy/config</command>.
+ See <command>privoxy --usage</command>, or the man page, for other options,
+ and configuration.
+</para>
]]>