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.7 2006/08/29 11:11:33 hal9 Exp $
   7
   8  Copyright (C) 2001-2006 Privoxy Developers http://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   README
  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 CVS installed.
  52  Note that sources from CVS are 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, and instead it is suggested to create a <quote>privoxy</quote> user
  80  and group for this purpose. See your local documentation for the correct
  81  command line to do this.
  82 </para>
  83
  84 <para>
  85  <filename>/etc/passwd</filename> might then look like:
  86 </para>
  87
  88 <para>
  89  <screen>  privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</screen>
  90 </para>
  91
  92 <para>
  93  And then <filename>/etc/group</filename>, like:
  94 </para>
  95
  96 <para>
  97  <screen>  privoxy:*:7777:</screen>
  98 </para>
  99
 100 <para>
 101  Some binary packages may do this for you.
 102 </para>
 103
 104 <para>
 105  Then, to build from either unpacked tarball or CVS source:
 106 </para>
 107
 108 <para>
 109  <screen>
 110  autoheader
 111  autoconf
 112  ./configure      # (--help to see options)
 113  make             # (the make from GNU, sometimes called gmake)
 114  su
 115  make -n install  # (to see where all the files will go)
 116  make -s install  # (to really install, -s to silence output)</screen>
 117 </para>
 118
 119 <para>
 120   If you have GNU <command>make</command>, you can have the first four steps
 121   automatically done for you by just typing:
 122 </para>
 123
 124 <para>
 125  <screen>
 126   make
 127 </screen>
 128 </para>
 129
 130 <para>
 131   in the freshly downloaded or unpacked source directory.
 132 </para>
 133
 134 <para>
 135  <emphasis>WARNING:</emphasis> If installing as root, the install will fail
 136  unless a non-root user or group is specified, or a <literal>privoxy</literal>
 137  user and group already exist on the system. If a non-root user is specified,
 138  and no group, then the installation will try to also use a group of the same name
 139  as <quote>user</quote>. If a group is specified (and no user), then the
 140  support files will be installed as writable by that group, and owned by the
 141  user running the installation.
 142 </para>
 143
 144 <para>
 145  <command>configure</command> accepts <literal>--with-user</literal> and
 146  <literal>--with-group</literal> options for setting user and group ownership
 147  of the configuration files (which need to be writable by the daemon). The
 148  specified <emphasis>user must already exist</emphasis>. When starting
 149  <application>Privoxy</application>, it should be run as this same user to
 150  insure write access to configuration and log files.
 151 </para>
 152
 153 <para>
 154  Alternately, you can specify <literal>user</literal> and <literal>group</literal>
 155  on the <command>make</command> command line, but be sure both already exist:
 156 </para>
 157
 158 <para>
 159  <screen>
 160  make -s install  USER=privoxy GROUP=privoxy</screen>
 161 </para>
 162
 163 <para>
 164  The default installation path for <command>make install</command> is
 165  <filename>/usr/local</filename>. This may of course be customized with
 166  the various <command>./configure</command> path options. If you are doing
 167  a root install to anywhere else besides <filename>/usr/local</filename>, be
 168  sure to set the appropriate paths with the correct configure options
 169  (<command>./configure --help</command>).
 170 </para>
 171
 172 <para>
 173  If you do install to <filename>/usr/local</filename>, the install will use
 174  <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
 175  destinations, and the direct usage of <literal>--sysconfdir</literal> flag
 176  behave like normal, i.e. will not add the extra <filename>privoxy</filename>
 177  directory. This is for a safer install, as there may already exist another
 178  program that uses a file with the <quote>config</quote> name, and thus makes
 179  <filename>/usr/local/etc</filename> cleaner.
 180 </para>
 181
 182 <para>
 183  If installing to <filename>/usr/local</filename>, the docs will go by default
 184  to <filename>$prefix/share/doc</filename>. But if this directory doesn't
 185  exist, it will then try <filename>$prefix/doc</filename> and install there before
 186  creating a new <filename>$prefix/share/doc</filename> just for
 187  <application>Privoxy</application>.
 188 </para>
 189
 190 <para>
 191  Again, if the installs goes to <filename>/usr/local</filename>, the
 192  <literal>localstatedir</literal> (ie: <filename>var/</filename>) will default
 193  to <filename>/var</filename> instead of <literal>$prefix/var</literal> so
 194  the logs will go to <filename>/var/log/privoxy/</filename>, and the pid file
 195  will be created in <filename>/var/run/privoxy.pid</filename>.
 196 </para>
 197
 198 <para>
 199  <command>make install</command> will attempt to set the correct values
 200  in <filename>config</filename> (main configuration file). You may want
 201  to check this to make sure all values are correct. If appropriate,
 202  an init script will be installed, but it is up to the user to determine
 203  how and where to start <application>Privoxy</application>. The init
 204  script should be checked for correct paths and values, if anything other than
 205  a default install is done.
 206 </para>
 207
 208 <para>
 209  If install finds previous versions of any configuration files, these will not
 210  be overwritten, and the new ones will be installed with a <quote>new</quote>
 211  extension. You will then need to manually update the installed configuration
 212  files as needed. All template files will be overwritten. If you have
 213  customized, local templates, you should save these first. If a previous
 214  version of <application>Privoxy</application> is already running, you will
 215  have to restart it manually.
 216 </para>
 217
 218 <para>
 219  For more detailed instructions on how to build Redhat and SuSE RPMs,
 220  Windows self-extracting installers, building on platforms with
 221  special requirements etc, please consult the <ulink
 222  url="../developer-manual/newrelease.html">developer manual</ulink>.
 223 </para>
 224
 225 <!-- print for README only -->
 226 <!-- Actually this is now in INSTALL -->
 227  <![%p-readme;[
 228 <para>
 229  The simplest command line to start <application>Privoxy</application> is
 230  <command>$path/privoxy --user=privoxy  $path/etc/privoxy/config</command>.
 231  See <command>privoxy --usage</command>, or the man page, for other options,
 232  and configuration.
 233 </para>
 234 ]]>