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.9 2006/09/22 10:38:05 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 a CVS client installed.
  52  Note that sources from CVS are typicially 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  To build an executable with security enhanced features so that
 136  users cannot easily bypass the proxy (e.g. <quote>go there anyway</quote>, or
 137  change their own configurations, <command>configure</command> like this:
 138 </para>
 139 <para>
 140  <screen>
 141  ./configure  --disable-toggle  --disable-editor  --disable-force</screen>
 142 </para>
 143 <para>
 144 Then build as above.
 145 </para>
 146 <para>
 147  <emphasis>WARNING:</emphasis> If installing as root, the install will fail
 148  unless a non-root user or group is specified, or a <literal>privoxy</literal>
 149  user and group already exist on the system. If a non-root user is specified,
 150  and no group, then the installation will try to also use a group of the same name
 151  as <quote>user</quote>. If a group is specified (and no user), then the
 152  support files will be installed as writable by that group, and owned by the
 153  user running the installation.
 154 </para>
 155
 156 <para>
 157  <command>configure</command> accepts <literal>--with-user</literal> and
 158  <literal>--with-group</literal> options for setting user and group ownership
 159  of the configuration files (which need to be writable by the daemon). The
 160  specified <emphasis>user must already exist</emphasis>. When starting
 161  <application>Privoxy</application>, it should be run as this same user to
 162  insure write access to configuration and log files.
 163 </para>
 164
 165 <para>
 166  Alternately, you can specify <literal>user</literal> and <literal>group</literal>
 167  on the <command>make</command> command line, but be sure both already exist:
 168 </para>
 169
 170 <para>
 171  <screen>
 172  make -s install  USER=privoxy GROUP=privoxy</screen>
 173 </para>
 174
 175 <para>
 176  The default installation path for <command>make install</command> is
 177  <filename>/usr/local</filename>. This may of course be customized with
 178  the various <command>./configure</command> path options. If you are doing
 179  a root install to anywhere else besides <filename>/usr/local</filename>, be
 180  sure to set the appropriate paths with the correct configure options
 181  (<command>./configure --help</command>).
 182 </para>
 183
 184 <para>
 185  If you do install to <filename>/usr/local</filename>, the install will use
 186  <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
 187  destinations, and the direct usage of <literal>--sysconfdir</literal> flag
 188  behave like normal, i.e. will not add the extra <filename>privoxy</filename>
 189  directory. This is for a safer install, as there may already exist another
 190  program that uses a file with the <quote>config</quote> name, and thus makes
 191  <filename>/usr/local/etc</filename> cleaner.
 192 </para>
 193
 194 <para>
 195  If installing to <filename>/usr/local</filename>, the docs will go by default
 196  to <filename>$prefix/share/doc</filename>. But if this directory doesn't
 197  exist, it will then try <filename>$prefix/doc</filename> and install there before
 198  creating a new <filename>$prefix/share/doc</filename> just for
 199  <application>Privoxy</application>.
 200 </para>
 201
 202 <para>
 203  Again, if the installs goes to <filename>/usr/local</filename>, the
 204  <literal>localstatedir</literal> (ie: <filename>var/</filename>) will default
 205  to <filename>/var</filename> instead of <literal>$prefix/var</literal> so
 206  the logs will go to <filename>/var/log/privoxy/</filename>, and the pid file
 207  will be created in <filename>/var/run/privoxy.pid</filename>.
 208 </para>
 209
 210 <para>
 211  <command>make install</command> will attempt to set the correct values
 212  in <filename>config</filename> (main configuration file). You may want
 213  to check this to make sure all values are correct. If appropriate,
 214  an init script will be installed, but it is up to the user to determine
 215  how and where to start <application>Privoxy</application>. The init
 216  script should be checked for correct paths and values, if anything other than
 217  a default install is done.
 218 </para>
 219
 220 <para>
 221  If install finds previous versions of any local configuration files, these
 222  will not be overwritten, and the new ones will be installed with a
 223  <quote>new</quote> extension. default.action, default.filter, and
 224  standard.action will be overwritten. You will then need to manually update
 225  the other installed configuration files as needed. All template files will be
 226  overwritten. If you have customized, local templates, you should save these
 227  first. If a previous version of <application>Privoxy</application> is
 228  already running, you will have to restart it manually.
 229 </para>
 230
 231 <para>
 232  For more detailed instructions on how to build Redhat RPMs,
 233  Windows self-extracting installers, building on platforms with
 234  special requirements etc, please consult the <ulink
 235  url="../developer-manual/newrelease.html">developer manual</ulink>.
 236 </para>
 237
 238 <!-- print for README only -->
 239 <!-- Actually this is now in INSTALL -->
 240  <![%p-readme;[
 241 <para>
 242  The simplest command line to start <application>Privoxy</application> is
 243  <command>$path/privoxy --user=privoxy  $path/etc/privoxy/config</command>.
 244  See <command>privoxy --usage</command>, or the man page, for other options,
 245  and configuration.
 246 </para>
 247 ]]>