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