<!--
- File : $Source: /cvsroot/ijbswa/current/doc/source/buildsource.sgml,v $
+ File : doc/source/buildsource.sgml
Purpose : Entity included in other project documents.
-
- $Id: buildsource.sgml,v 2.10 2006/10/14 23:03:56 hal9 Exp $
- Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
+ Copyright (C) 2001-2018 Privoxy Developers https://www.privoxy.org/
See LICENSE.
======================================================================
This file used for inclusion with other documents only.
======================================================================
- If you make changes to this file, please verify the finished
+ If you make changes to this file, please verify the finished
docs all display as intended.
This file is included into:
user-manual
- README
+ INSTALL
-->
<para>
- To build <application>Privoxy</application> from source,
+ To build <application>Privoxy</application> from source,
<ulink url="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</ulink>,
- <ulink
- url="http://www.gnu.org/software/make/make.html">GNU make
- (gmake)</ulink>, and, of course, a C compiler like <ulink
- url="http://www.gnu.org/software/gcc/gcc.html">gcc</ulink> are required.
+ <ulink url="http://www.gnu.org/software/make/make.html">GNU make (gmake)</ulink>,
+ and, of course, a C compiler like
+ <ulink url="http://www.gnu.org/software/gcc/gcc.html">gcc</ulink> are required.
</para>
<para>
When building from a source tarball,
-<!--
- no longer available ...
- <ulink
- url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">nightly CVS
- tarball</ulink>),
---> first unpack the source:
+ first unpack the source:
</para>
-<para>
- <screen>
- tar xzvf privoxy-&p-version;<![%p-not-stable;[-beta]]>-src* [.tgz or .tar.gz]
- cd privoxy-&p-version;<![%p-not-stable;[-beta]]>
+<screen>
+ tar xzvf privoxy-&p-version;<![%p-not-stable;[-beta]]><![%p-stable;[-stable]]>-src.tar.gz
+ cd privoxy-&p-version;<![%p-not-stable;[-beta]]><![%p-stable;[-stable]]>
</screen>
-</para>
<para>
- For retrieving the current CVS sources, you'll need a CVS client installed.
- Note that sources from CVS are typicially development quality, and may not be
- stable, or well tested. To download CVS source, check the Sourceforge
- documentation, which might give commands like:
+ To build the development version, you can get the source code by doing:
</para>
-<para>
- <screen>
- 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>
+ cd <root-dir>
+ git clone https://www.privoxy.org/git/privoxy.git
</screen>
-</para>
<para>
- This will create a directory named <filename>current/</filename>, which will
- contain the source tree.
+ This will create a directory named <filename><root-dir>/privoxy/</filename>,
+ which will contain the source tree.
</para>
<para>
+ Note that source code in Git is development quality, and may not be
+ stable or well tested.
+</para>
+
+<!-- para>
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 -->
<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.
+ It is strongly recommended to not run <application>Privoxy</application>
+ as root. You should configure/install/run <application>Privoxy</application> as
+ an unprivileged user, preferably by creating a <quote>privoxy</quote> user
+ and group just for this purpose. See your local documentation for the correct
+ command line to do add new users and groups (something like
+ <command>adduser</command>, but the command syntax may vary from platform
+ to platform).
</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:
+ Then, to build from either unpacked tarball or Git checkout:
</para>
-<para>
<screen>
autoheader
autoconf
./configure # (--help to see options)
- make # (the make from GNU, sometimes called gmake)
- su
+ make # (the make from GNU, sometimes called gmake)
+ su # Possibly required
make -n install # (to see where all the files will go)
make -s install # (to really install, -s to silence output)</screen>
-</para>
<para>
- If you have GNU <command>make</command>, you can have the first four steps
+ Using GNU <command>make</command>, you can have the first four steps
automatically done for you by just typing:
</para>
-<para>
<screen>
make
</screen>
-</para>
<para>
in the freshly downloaded or unpacked source directory.
</para>
<para>
- To build an executable with security enhanced features so that
- users cannot easily bypass the proxy (e.g. <quote>go there anyway</quote>), or
- change their own configurations, <command>configure</command> like this:
+ To build an executable with security enhanced features so that
+ users cannot easily bypass the proxy (e.g. <quote>Go There Anyway</quote>), or
+ alter their own configurations, <command>configure</command> like this:
</para>
-<para>
<screen>
./configure --disable-toggle --disable-editor --disable-force</screen>
-</para>
<para>
-Then build as above.
+ Note that all of these options can also be disabled through the configuration file.
</para>
<para>
<emphasis>WARNING:</emphasis> If installing as root, the install will fail
<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.
+ <application>Privoxy</application>, it must be run as this same user to
+ insure write access to configuration and log files!
</para>
<para>
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
+ 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
+ an install to anywhere besides <filename>/usr/local</filename>, be
sure to set the appropriate paths with the correct configure options
- (<command>./configure --help</command>).
+ (<command>./configure --help</command>). Non-privileged users must of course
+ have write access permissions to wherever the target installation is going.
</para>
<para>
</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
+ If installing to <filename>/usr/local</filename>, the documentation 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>
<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>.
+ 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
+ <command>make install</command> will attempt to set the correct values
+ in <filename>config</filename> (main configuration file). You should
+ 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 local configuration files, these
- will not be overwritten, and the new ones will be installed with a
- <quote>new</quote> extension. default.action, default.filter, and
- standard.action will be overwritten. You will then need to manually update
- the other 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.
+ If install finds previous versions of local configuration files, most of
+ these will not be overwritten, and the new ones will be installed with a
+ <quote>new</quote> extension. default.action and default.filter
+ <emphasis>will be overwritten</emphasis>. You will then need
+ to manually update the other installed configuration files as needed. The
+ default template files <emphasis>will</emphasis> be overwritten. If you have
+ customized, local templates, these should be stored safely in a separate
+ directory and defined in <filename>config</filename> by the
+ <quote>templdir</quote> directive. It is of course wise to always back-up any
+ important configuration files <quote>just in case</quote>. 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 RPMs,
Windows self-extracting installers, building on platforms with
special requirements etc, please consult the <ulink
- url="../developer-manual/newrelease.html">developer manual</ulink>.
+ url="https://www.privoxy.org/developer-manual/newrelease.html">developer manual</ulink>.
</para>
<!-- print for README only -->
<!-- Actually this is now in INSTALL -->
<![%p-readme;[
<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,
+ 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>
]]>