a24da213e5a8211f044f18788bcd77d62ed58a4f
[privoxy.git] / 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.3 2002/09/06 01:58:28 hal9 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   INSTALL
22
23 -->
24
25 <para>
26  To build <application>Privoxy</application> from source, 
27  <ulink url="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</ulink>,
28  <ulink
29  url="http://www.gnu.org/software/make/make.html">GNU make
30  (gmake)</ulink>, and, of course, a C compiler like <ulink
31  url="http://www.gnu.org/software/gcc/gcc.html">gcc</ulink> are required.
32 </para>
33
34 <para>
35  When building from a source tarball (either release version or
36  <ulink
37  url="http://cvs.sourceforge.net/cvstarballs/ijbswa-cvsroot.tar.gz">nightly CVS
38  tarball</ulink>), first unpack the source: 
39 </para>
40
41 <para>
42  <screen>
43  tar xzvf privoxy-&p-version;<![%p-not-stable;[-beta]]>-src* [.tgz or .tar.gz]
44  cd privoxy-&p-version;<![%p-not-stable;[-beta]]>
45 </screen>
46 </para>
47
48 <para>
49  For retrieving the current CVS sources, you'll need CVS installed.
50  Note that sources from CVS are development quality, and may not be
51  stable, or well tested. To download CVS source:
52 </para>
53
54 <para>
55  <screen>
56   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
57   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co current
58   cd current
59 </screen>
60 </para>
61
62 <para>
63  This will create a directory named <filename>current/</filename>, which will 
64  contain the source tree.
65 </para>
66
67 <para>
68  You can also check out any <application>Privoxy</application>
69  <quote>branch</quote>, just exchange the <application>current</application>
70  name with the wanted branch name (Example: v_3_0_branch for the 3.0 cvs
71  tree).
72 </para>
73
74 <para>
75  It is also recommended to not run <application>Privoxy</application> as 
76  root, and instead it is suggested to create a <quote>privoxy</quote> user for
77  this purpose.
78 </para>
79
80 <para>
81  <filename>/etc/passwd</filename> might then look like:
82 </para>
83
84 <para>
85  <screen>  privoxy:*:7777:7777:privoxy proxy:/no/home:/no/shell</screen>
86 </para>
87
88 <para>
89  And then <filename>/etc/group</filename>, like:
90 </para>
91
92 <para>
93  <screen>  privoxy:*:7777:privoxy</screen>
94 </para>
95
96 <para>
97  Some binary packages may do this for you.
98 </para>
99
100 <para>
101  Then, to build from either unpacked tarball or CVS source:
102 </para>
103
104 <para>
105  <screen>
106  autoheader
107  autoconf
108  ./configure      # (--help to see options)
109  make             # (the make from gnu, gmake for *BSD) 
110  su 
111  make -n install  # (to see where all the files will go)
112  make install     # (to really install)
113 </screen>
114 </para>
115 <!--
116 /we hope this is fixed! 09/24/02
117 <warning>
118  <para> 
119   The <quote>make install</quote> target is temporary quite broken! It is
120   recommended to use a binary package, or do a source build, and manually 
121   install the components. Sorry.
122  </para>
123 </warning>
124 -->
125 <para>
126   If you have GNU <command>make</command>, you can have the first four steps
127   automatically done for you by just typing:
128 </para>
129
130 <para>
131  <screen>
132   make
133 </screen>
134 </para>
135
136 <para>
137   in the freshly downloaded or unpacked source directory.
138 </para>
139
140 <para>
141  The default installation path for <command>make install</command> is 
142  <filename>/usr/local</filename>. This may of course be customized with 
143  the various <command>./configure</command> path options.
144  <command>configure</command> also accepts a <literal>--with-user</literal> and
145  <literal>--with-group</literal> options for setting user and group
146  ownership.
147 </para>
148
149 <para>
150  If you do install to <filename>/usr/local</filename>, the install will use
151  <literal>sysconfdir=$prefix/etc/privoxy</literal> by default. All other
152  destinations, and the direct usage of <literal>--sysconfdir</literal> flag
153  behave like normal, i.e. will not add the extra <filename>privoxy</filename>
154  directory. This is for a safer install, as there may already exist another
155  program that uses a file with the <quote>config</quote> name, and thus makes
156  <filename>/usr/local/etc</filename> cleaner.
157 </para>
158
159 <para>
160  If installing to <filename>/usr/local</filename>, the docs will go by default
161  to <filename>$prefix/share/doc</filename>. But if this directory doesn't
162  exist, it will then try <filename>$prefix/doc</filename> and install there before
163  creating a new <filename>$prefix/share/doc</filename> just for
164  <application>Privoxy</application>.
165 </para>
166
167 <para>
168  Again, if the installs goes to <filename>/usr/local</filename>, the
169  <literal>localstatedir</literal> (ie: var/) will default to
170  <filename>/var</filename> instead of <literal>$prefix/var</literal> so the
171  logs will go to <filename>/var/log/privoxy/</filename>, and the pid file will
172  be created in <filename>/var/run/privoxy.pid</filename>. 
173 </para>
174
175 <para>
176  <command>make install</command> will attempt to set the correct values 
177  in <filename>config</filename> (main configuration file). If appropriate,
178  an init script will be installed, but it is up to the user to determine 
179  how and where to start <application>Privoxy</application>.
180 </para>
181
182 <para>
183  For more detailed instructions on how to build Redhat and SuSE RPMs,
184  Windows self-extracting installers, building on platforms with
185  special requirements etc, please consult the <ulink
186  url="../developer-manual/newrelease.html">developer manual</ulink>.
187 </para>
188
189 <!-- print for README only -->
190 <!-- Actually this is now in INSTALL -->
191  <![%p-readme;[
192  <para>
193   For binary RPM installation, and other platforms, see the User Manual
194   as well.
195  </para>
196 ]]>