doc/source/buildsource.sgml

   1 <!--
   2  File        :  $Source: /cvsroot/ijbswa/current/doc/source/buildsource.sgml,v $
   3
   4  Purpose     :  Entity included in other project documents.
   5
   6  $Id: buildsource.sgml,v 2.14 2007/11/22 17:38:40 hal9 Exp $
   7
   8  Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/
   9  See LICENSE.
  10
  11  ======================================================================
  12   This file used for inclusion with other documents only.
  13  ======================================================================
  14
  15  If you make changes to this file, please verify the finished
  16  docs all display as intended.
  17
  18  This file is included into:
  19
  20   user-manual
  21   INSTALL
  22
  23 -->
  24 <para>
  25  To build <application>Privoxy</application> from source,
  26  <ulink url="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</ulink>,
  27  <ulink
  28  url="http://www.gnu.org/software/make/make.html">GNU make
  29  (gmake)</ulink>, and, of course, a C compiler like <ulink
  30  url="http://www.gnu.org/software/gcc/gcc.html">gcc</ulink> are required.
  31 </para>
  32
  33 <para>
  34  When building from a source tarball,
  35 <!--
  36  no longer available ...
  37  <ulink
  38  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">nightly CVS
  39  tarball</ulink>),
  40 --> first unpack the source:
  41 </para>
  42
  43 <para>
  44  <screen>
  45  tar xzvf privoxy-&p-version;<![%p-not-stable;[-beta]]>-src* [.tgz or .tar.gz]
  46  cd privoxy-&p-version;<![%p-not-stable;[-beta]]>
  47 </screen>
  48 </para>
  49
  50 <para>
  51  For retrieving the current CVS sources, you'll need a CVS client installed.
  52  Note that sources from CVS are typically development quality, and may not be
  53  stable, or well tested. To download CVS source, check the Sourceforge
  54  documentation, which might give commands like:
  55 </para>
  56
  57 <para>
  58  <screen>
  59   cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
  60   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co current
  61   cd current
  62 </screen>
  63 </para>
  64
  65 <para>
  66  This will create a directory named <filename>current/</filename>, which will
  67  contain the source tree.
  68 </para>
  69
  70 <para>
  71  You can also check out any <application>Privoxy</application>
  72  <quote>branch</quote>, just exchange the <application>current</application>
  73  name with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs
  74  tree).
  75 </para>
  76
  77 <para>
  78  It is also strongly recommended to not run <application>Privoxy</application>
  79  as root. You should configure/install/run <application>Privoxy</application> as
  80  an unprivileged user, preferably by  creating a <quote>privoxy</quote> user
  81  and group just for this purpose. See your local documentation for the correct
  82  command line to do add new users and groups (something like
  83  <command>adduser</command>, but the command syntax may vary from platform
  84  to platform).
  85 </para>
  86
  87 <para>
  88  <filename>/etc/passwd</filename> might then look like:
  89 </para>
  90
  91 <para>
  92  <screen>  privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</screen>
  93 </para>
  94
  95 <para>
  96  And then <filename>/etc/group</filename>, like:
  97 </para>
  98
  99 <para>
 100  <screen>  privoxy:*:7777:</screen>
 101 </para>
 102
 103 <para>
 104  Some binary packages may do this for you.
 105 </para>
 106
 107 <para>
 108  Then, to build from either unpacked tarball or CVS source:
 109 </para>
 110
 111 <para>
 112  <screen>
 113  autoheader
 114  autoconf
 115  ./configure      # (--help to see options)
 116  make             # (the make from GNU, sometimes called gmake)
 117  su               # Possibly required
 118  make -n install  # (to see where all the files will go)
 119  make -s install  # (to really install, -s to silence output)</screen>
 120 </para>
 121
 122 <para>
 123   Using GNU <command>make</command>, you can have the first four steps
 124   automatically done for you by just typing:
 125 </para>
 126
 127 <para>
 128  <screen>
 129   make
 130 </screen>
 131 </para>
 132
 133 <para>
 134   in the freshly downloaded or unpacked source directory.
 135 </para>
 136
 137 <para>
 138  To build an executable with security enhanced features so that
 139  users cannot easily bypass the proxy (e.g. <quote>Go There Anyway</quote>), or
 140  alter their own configurations, <command>configure</command> like this:
 141 </para>
 142 <para>
 143  <screen>
 144  ./configure  --disable-toggle  --disable-editor  --disable-force</screen>
 145 </para>
 146 <para>
 147 Then build as above. In Privoxy 3.0.7 and later, all of these options
 148 can also be disabled through the configuration file.
 149 </para>
 150 <para>
 151  <emphasis>WARNING:</emphasis> If installing as root, the install will fail
 152  unless a non-root user or group is specified, or a <literal>privoxy</literal>
 153  user and group already exist on the system. If a non-root user is specified,
 154  and no group, then the installation will try to also use a group of the same name
 155  as <quote>user</quote>. If a group is specified (and no user), then the
 156  support files will be installed as writable by that group, and owned by the
 157  user running the installation.
 158 </para>
 159
 160 <para>
 161  <command>configure</command> accepts <literal>--with-user</literal> and
 162  <literal>--with-group</literal> options for setting user and group ownership
 163  of the configuration files (which need to be writable by the daemon). The
 164  specified <emphasis>user must already exist</emphasis>. When starting
 165  <application>Privoxy</application>, it must be run as this same user to
 166  insure write access to configuration and log files!
 167 </para>
 168
 169 <para>
 170  Alternately, you can specify <literal>user</literal> and <literal>group</literal>
 171  on the <command>make</command> command line, but be sure both already exist:
 172 </para>
 173
 174 <para>
 175  <screen>
 176  make -s install  USER=privoxy GROUP=privoxy</screen>
 177 </para>
 178
 179 <para>
 180  The default installation path for <command>make install</command> is
 181  <filename>/usr/local</filename>. This may of course be customized with
 182  the various <command>./configure</command> path options. If you are doing
 183  an install to anywhere besides <filename>/usr/local</filename>, be
 184  sure to set the appropriate paths with the correct configure options
 185  (<command>./configure --help</command>). Non-privileged users must of course
 186  have write access permissions to wherever the target installation is going.
 187 </para>
 188
 189 <para>
 190  If you do install to <filename>/usr/local</filename>, the install will use
 191  <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
 192  destinations, and the direct usage of <literal>--sysconfdir</literal> flag
 193  behave like normal, i.e. will not add the extra <filename>privoxy</filename>
 194  directory. This is for a safer install, as there may already exist another
 195  program that uses a file with the <quote>config</quote> name, and thus makes
 196  <filename>/usr/local/etc</filename> cleaner.
 197 </para>
 198
 199 <para>
 200  If installing to <filename>/usr/local</filename>, the documentation will go
 201  by default to <filename>$prefix/share/doc</filename>. But if this directory
 202  doesn't exist, it will then try <filename>$prefix/doc</filename> and install
 203  there before creating a new <filename>$prefix/share/doc</filename> just for
 204  <application>Privoxy</application>.
 205 </para>
 206
 207 <para>
 208  Again, if the installs goes to <filename>/usr/local</filename>, the
 209  <literal>localstatedir</literal> (ie: <filename>var/</filename>) will default
 210  to <filename>/var</filename> instead of <literal>$prefix/var</literal> so
 211  the logs will go to <filename>/var/log/privoxy/</filename>, and the pid file
 212  will be created in <filename>/var/run/privoxy.pid</filename>.
 213 </para>
 214
 215 <para>
 216  <command>make install</command> will attempt to set the correct values
 217  in <filename>config</filename> (main configuration file). You should
 218  check this to make sure all values are correct. If appropriate,
 219  an init script will be installed, but it is up to the user to determine
 220  how and where to start <application>Privoxy</application>. The init
 221  script should be checked for correct paths and values, if anything other than
 222  a default install is done.
 223 </para>
 224
 225 <para>
 226  If install finds previous versions of local configuration files, most of
 227  these will not be overwritten, and the new ones will be installed with a
 228  <quote>new</quote> extension. default.action, default.filter, and
 229  standard.action <emphasis>will be overwritten</emphasis>. You will then need
 230  to manually update the other installed configuration files as needed. The
 231  default template files <emphasis>will</emphasis> be overwritten. If you have
 232  customized, local templates, these should be stored safely in a separate
 233  directory and defined in <filename>config</filename> by the
 234  <quote>templdir</quote> directive. It is of course wise to always back-up any
 235  important configuration files <quote>just in case</quote>. If a previous
 236  version of <application>Privoxy</application> is already running, you will
 237  have to restart it manually.
 238 </para>
 239
 240 <para>
 241  For more detailed instructions on how to build Redhat RPMs,
 242  Windows self-extracting installers, building on platforms with
 243  special requirements etc, please consult the <ulink
 244  url="../developer-manual/newrelease.html">developer manual</ulink>.
 245 </para>
 246
 247 <!-- print for README only -->
 248 <!-- Actually this is now in INSTALL -->
 249  <![%p-readme;[
 250 <para>
 251  The simplest command line to start <application>Privoxy</application> is
 252  <command>$path/privoxy --user=privoxy  $path/etc/privoxy/config</command>.
 253  See <command>privoxy --usage</command>, or the man page, for other options,
 254  and configuration.
 255 </para>
 256 ]]>