<!--
 File        :  $Source: /ds6/cvs/privoxy/doc/source/buildsource.sgml,v $

 Purpose     :  Entity included in other project documents.
                
 $Id: buildsource.sgml,v 1.1.1.1 2003/05/23 11:16:57 lionel Exp $

 Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
 See LICENSE.

 ======================================================================
  This file used for inclusion with other documents only.
 ======================================================================

 If you make changes to this file, please verify the finished 
 docs all display as intended.

 This file is included into:

  user-manual
  INSTALL

-->

<para>
 To build <application>Privoxy</application> from source, 
 <ulink url="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</ulink>,
 <ulink
 url="http://www.gnu.org/software/make/make.html">GNU make
 (gmake)</ulink>, and, of course, a C compiler like <ulink
 url="http://www.gnu.org/software/gcc/gcc.html">gcc</ulink> are required.
</para>

<para>
 When building from a source tarball (either release version or
 <ulink
 url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">nightly CVS
 tarball</ulink>), first unpack the source: 
</para>

<para>
 <screen>
 tar xzvf privoxy-&p-version;<![%p-not-stable;[-beta]]>-src* [.tgz or .tar.gz]
 cd privoxy-&p-version;<![%p-not-stable;[-beta]]>
</screen>
</para>

<para>
 For retrieving the current CVS sources, you'll need CVS installed.
 Note that sources from CVS are development quality, and may not be
 stable, or well tested. To download CVS source:
</para>

<para>
 <screen>
  cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
  cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
  cd current
</screen>
</para>

<para>
 This will create a directory named <filename>current/</filename>, which will 
 contain the source tree.
</para>

<para>
 You can also check out any <application>Privoxy</application>
 <quote>branch</quote>, just exchange the <application>current</application>
 name with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs
 tree).
</para>

<para>
 It is also recommended to not run <application>Privoxy</application> as 
 root, and instead it is suggested to create a <quote>privoxy</quote> user for
 this purpose.
</para>

<para>
 <filename>/etc/passwd</filename> might then look like:
</para>

<para>
 <screen>  privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</screen>
</para>

<para>
 And then <filename>/etc/group</filename>, like:
</para>

<para>
 <screen>  privoxy:*:7777:privoxy</screen>
</para>

<para>
 Some binary packages may do this for you.
</para>

<para>
 Then, to build from either unpacked tarball or CVS source:
</para>

<para>
 <screen>
 autoheader
 autoconf
 ./configure      # (--help to see options)
 make             # (the make from gnu, gmake for *BSD) 
 su 
 make -n install  # (to see where all the files will go)
 make install     # (to really install)
</screen>
</para>
<!--
/we hope this is fixed! 09/24/02
<warning>
 <para> 
  The <quote>make install</quote> target is temporary quite broken! It is
  recommended to use a binary package, or do a source build, and manually 
  install the components. Sorry.
 </para>
</warning>
-->
<para>
  If you have GNU <command>make</command>, you can have the first four steps
  automatically done for you by just typing:
</para>

<para>
 <screen>
  make
</screen>
</para>

<para>
  in the freshly downloaded or unpacked source directory.
</para>

<para>
 The default installation path for <command>make install</command> is 
 <filename>/usr/local</filename>. This may of course be customized with 
 the various <command>./configure</command> path options.
 <command>configure</command> also accepts a <literal>--with-user</literal> and
 <literal>--with-group</literal> options for setting user and group
 ownership.
</para>

<para>
 If you do install to <filename>/usr/local</filename>, the install will use
 <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
 destinations, and the direct usage of <literal>--sysconfdir</literal> flag
 behave like normal, i.e. will not add the extra <filename>privoxy</filename>
 directory. This is for a safer install, as there may already exist another
 program that uses a file with the <quote>config</quote> name, and thus makes
 <filename>/usr/local/etc</filename> cleaner.
</para>

<para>
 If installing to <filename>/usr/local</filename>, the docs will go by default
 to <filename>$prefix/share/doc</filename>. But if this directory doesn't
 exist, it will then try <filename>$prefix/doc</filename> and install there before
 creating a new <filename>$prefix/share/doc</filename> just for
 <application>Privoxy</application>.
</para>

<para>
 Again, if the installs goes to <filename>/usr/local</filename>, the
 <literal>localstatedir</literal> (ie: var/) will default to
 <filename>/var</filename> instead of <literal>$prefix/var</literal> so the
 logs will go to <filename>/var/log/privoxy/</filename>, and the pid file will
 be created in <filename>/var/run/privoxy.pid</filename>. 
</para>

<para>
 <command>make install</command> will attempt to set the correct values 
 in <filename>config</filename> (main configuration file). If appropriate,
 an init script will be installed, but it is up to the user to determine 
 how and where to start <application>Privoxy</application>.
</para>

<para>
 For more detailed instructions on how to build Redhat and SuSE RPMs,
 Windows self-extracting installers, building on platforms with
 special requirements etc, please consult the <ulink
 url="../developer-manual/newrelease.html">developer manual</ulink>.
</para>

<!-- print for README only -->
<!-- Actually this is now in INSTALL -->
 <![%p-readme;[
 <para>
  For binary RPM installation, and other platforms, see the User Manual
  as well.
 </para>
]]>
