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.20 2016/03/04 13:20:35 fabiankeil Exp $
   7
   8  Copyright (C) 2001-2009 Privoxy Developers https://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]]><![%p-stable;[-stable]]>-src.tar.gz
  46  cd privoxy-&p-version;<![%p-not-stable;[-beta]]><![%p-stable;[-stable]]>
  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  Note that all of these options can also be disabled through the configuration file.
 148 </para>
 149 <para>
 150  <emphasis>WARNING:</emphasis> If installing as root, the install will fail
 151  unless a non-root user or group is specified, or a <literal>privoxy</literal>
 152  user and group already exist on the system. If a non-root user is specified,
 153  and no group, then the installation will try to also use a group of the same name
 154  as <quote>user</quote>. If a group is specified (and no user), then the
 155  support files will be installed as writable by that group, and owned by the
 156  user running the installation.
 157 </para>
 158
 159 <para>
 160  <command>configure</command> accepts <literal>--with-user</literal> and
 161  <literal>--with-group</literal> options for setting user and group ownership
 162  of the configuration files (which need to be writable by the daemon). The
 163  specified <emphasis>user must already exist</emphasis>. When starting
 164  <application>Privoxy</application>, it must be run as this same user to
 165  insure write access to configuration and log files!
 166 </para>
 167
 168 <para>
 169  Alternately, you can specify <literal>user</literal> and <literal>group</literal>
 170  on the <command>make</command> command line, but be sure both already exist:
 171 </para>
 172
 173 <para>
 174  <screen>
 175  make -s install  USER=privoxy GROUP=privoxy</screen>
 176 </para>
 177
 178 <para>
 179  The default installation path for <command>make install</command> is
 180  <filename>/usr/local</filename>. This may of course be customized with
 181  the various <command>./configure</command> path options. If you are doing
 182  an install to anywhere besides <filename>/usr/local</filename>, be
 183  sure to set the appropriate paths with the correct configure options
 184  (<command>./configure --help</command>). Non-privileged users must of course
 185  have write access permissions to wherever the target installation is going.
 186 </para>
 187
 188 <para>
 189  If you do install to <filename>/usr/local</filename>, the install will use
 190  <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
 191  destinations, and the direct usage of <literal>--sysconfdir</literal> flag
 192  behave like normal, i.e. will not add the extra <filename>privoxy</filename>
 193  directory. This is for a safer install, as there may already exist another
 194  program that uses a file with the <quote>config</quote> name, and thus makes
 195  <filename>/usr/local/etc</filename> cleaner.
 196 </para>
 197
 198 <para>
 199  If installing to <filename>/usr/local</filename>, the documentation will go
 200  by default to <filename>$prefix/share/doc</filename>. But if this directory
 201  doesn't exist, it will then try <filename>$prefix/doc</filename> and install
 202  there before creating a new <filename>$prefix/share/doc</filename> just for
 203  <application>Privoxy</application>.
 204 </para>
 205
 206 <para>
 207  Again, if the installs goes to <filename>/usr/local</filename>, the
 208  <literal>localstatedir</literal> (ie: <filename>var/</filename>) will default
 209  to <filename>/var</filename> instead of <literal>$prefix/var</literal> so
 210  the logs will go to <filename>/var/log/privoxy/</filename>, and the pid file
 211  will be created in <filename>/var/run/privoxy.pid</filename>.
 212 </para>
 213
 214 <para>
 215  <command>make install</command> will attempt to set the correct values
 216  in <filename>config</filename> (main configuration file). You should
 217  check this to make sure all values are correct. If appropriate,
 218  an init script will be installed, but it is up to the user to determine
 219  how and where to start <application>Privoxy</application>. The init
 220  script should be checked for correct paths and values, if anything other than
 221  a default install is done.
 222 </para>
 223
 224 <para>
 225  If install finds previous versions of local configuration files, most of
 226  these will not be overwritten, and the new ones will be installed with a
 227  <quote>new</quote> extension. default.action and default.filter
 228  <emphasis>will be overwritten</emphasis>. You will then need
 229  to manually update the other installed configuration files as needed. The
 230  default template files <emphasis>will</emphasis> be overwritten. If you have
 231  customized, local templates, these should be stored safely in a separate
 232  directory and defined in <filename>config</filename> by the
 233  <quote>templdir</quote> directive. It is of course wise to always back-up any
 234  important configuration files <quote>just in case</quote>. If a previous
 235  version of <application>Privoxy</application> is already running, you will
 236  have to restart it manually.
 237 </para>
 238
 239 <para>
 240  For more detailed instructions on how to build Redhat RPMs,
 241  Windows self-extracting installers, building on platforms with
 242  special requirements etc, please consult the <ulink
 243  url="https://www.privoxy.org/developer-manual/newrelease.html">developer manual</ulink>.
 244 </para>
 245
 246 <!-- print for README only -->
 247 <!-- Actually this is now in INSTALL -->
 248  <![%p-readme;[
 249 <para>
 250  The simplest command line to start <application>Privoxy</application> is
 251  <command>$path/privoxy --user=privoxy  $path/etc/privoxy/config</command>.
 252  See <command>privoxy --usage</command>, or the man page, for other options,
 253  and configuration.
 254 </para>
 255 ]]>