Code

Merge branch 'upstream'
[pkg-rrdtool.git] / doc / rrdbuild.pod
1 =head1 NAME
3 rrdbuild - Instructions for building RRDtool
5 =head1 OVERVIEW
7 If you downloaded the source of rrdtool you have to compile it. This
8 document will give some information on how this is done.
10 RRDtool relies on services of third part libraries. Some of these libraries
11 may already be installed on your system. You have to compile copies of the other
12 ones before you can build RRDtool.
14 This document will tell you about all the necessary steps to get going.
16 These instructions assume you are using a B<bash> shell. If you use csh/tcsh,
17 then you can either type F<bash> to switch to bash for the compilation or if
18 you know what you are doing just replace the export bits with
19 setenv.
21 We further assume that your copies of B<tar> and B<make> are actually B<GNU
22 tar> and B<GNU make> respectively. It could be that they are installed as
23 B<gtar> and B<gmake> on your system.
25 =head1 OPTIMISTIC BUILD
27 Before you start to build RRDtool, you have to decide two things:
29 =over
31 =item 1.
33 In which directory you want to build the software.
35 =item 2.
37 Where you want to install the software.
39 =back
41 Once you have decided. Save the two locations into environment variables.
43  BUILD_DIR=/tmp/rrdbuild
44  INSTALL_DIR=/usr/local/rrdtool-1.3.7
47 If your F</tmp> is mounted with the option noexec (RHEL seems todo that) you have to choose
48 a different directory!
50 Now make sure the BUILD_DIR exists and go there:
52  mkdir -p $BUILD_DIR
53  cd $BUILD_DIR
55 Lets first assume you already have all the necessary libraries
56 pre-installed. 
58  wget http://oss.oetiker.ch/rrdtool/pub/rrdtool-1.3.7.tar.gz
59  gunzip -c rrdtool-1.3.7.tar.gz | tar xf -
60  cd rrdtool-1.3.7
61  ./configure --prefix=$INSTALL_DIR && make && make install
63 Ok, this was very optimistic. This try will probably have ended with
64 B<configure> complaining about several missing libraries.
66 =head1 INSTALLING DEPENDENCIES
68 If your OS lets you install additional packages from a software repository,
69 you may get away with installing the missing packages. When the packages are
70 installed, run configure again and try to compile again. Below you find some
71 hints on getting your OS ready for the rrdtool compilation. 
73 Additions to this list are welcome. In general rrdtool should work with the
74 latest versions of the libraries. The versions listed here are just what was
75 current when I tested this.
77 =head2 OpenSolaris 2008.05
79 Just add a compiler and the gnome development package:
81  pkg install sunstudioexpress
82  pkg install SUNWgnome-common-devel
84 There is a problem with F<cairo.pc> on OpenSolaris. It suggests that
85 xrender is required for compilation with cairo. This is not true and also
86 bad since OpenSolaris does not include an F<xrender.pc> file. Use Perl to
87 fix this:
89  perl -i~ -p -e 's/(Requires.*?)\s*xrender.*/$1/' /usr/lib/pkgconfig/cairo.pc 
91 Make sure rrdtool finds your new compiler
93  export PATH=/opt/SunStudioExpress/bin
95 Since there does not seem to be a viable msgfmt tool on OpenSolaris (short
96 of installing it yourself). You have to call configure with the
98  --disable-libintl
100 option.
102 =head2 Debian / Ubuntu
104 Use apt-get to make sure you have all that is required. A number
105 of packages will get added through dependencies.
107  apt-get install libpango1.0-dev libxml2-dev
109 =head2 Gentoo
111 In Gentoo installing rrdtool is really simple you just need to B<emerge
112 rrdtool>. All dependencies will be handled automatically by the portage
113 system. The only thing you should care about are USE flags, which allow you
114 fine tune features rrdtool will be built with. Currently the following USE
115 flags are available:
117  doc    - install .html and .txt documentation
118           into /usr/share/doc/rrdtool-1.x.xx/
119  perl   - build and install perl language bindings
120  python - build and install python language bindings
121  ruby   - build and install ruby language bindings
122  tcl    - build and install tcl language bindings
123  rrdcgi - build and install rrdcgi
125 After you've decided which USE flags you need, set them either in
126 F<make.conf> or F</etc/portage/package.use> and finally run:
128  # emerge -va rrdtool
130 Take a look at Gentoo handbook for further details on how to manage USE
131 flags: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2
133 =head1 BUILDING DEPENDENCIES
135 But again this may have been too optimistic still, and you actually have to
136 compile your own copies of some of the required libraries. Things like
137 libpng and zlib are pretty standard so you will probably have them on your
138 system anyway. Freetype, Fontinst, Cairo, Pango may be installed, but it is
139 possible that they are pretty old and thus don't live up to our
140 expectations, so you may want to compile their latest versions.
142 =head2 General build tips for AIX
144 If you are working with AIX, you may find the B<--disable-shared> option
145 will cause things to break for you. In that case you may have to install the
146 shared libraries into the rrdtool PREFIX and work with B<--disable-static>
147 instead.
149 Another hint to get rrdtool working on AIX is to use the IBM XL C Compiler:
151  export CC=/usr/vac/bin/cc
152  export PERLCC=$CC
154 (Better instructions for AIX welcome!)
156 =head2 Build Instructions
158 Some libraries want to know where other libraries are. For this to work,
159 set the following environment variable
161  export PKG_CONFIG_PATH=${INSTALL_DIR}/lib/pkgconfig
162  export PATH=$INSTALL_DIR/bin:$PATH
164 The above relies on the presence of the F<pkgconfig> program. Below you find instructions
165 on how to compile pkgconfig.
167 Since we are compiling libraries dynamically, they must know where to find
168 each other. This is done by setting an appropriate LDFLAGS. Unfortunately,
169 the syntax again differs from system to system:
171 =over
173 =item Solaris
175  export LDFLAGS=-R${INSTALL_DIR}/lib 
177 if you are using the Sun Studio/Forte compiler, you may also want to set
179  export CFLAGS="-xO3 -xcode=pic13"   (SPARC)
180  export CFLAGS="-xO3 -Kpic"          (x86)
183 =item Linux
185  export CFLAGS="-O3 -fPIC"
186  export LDFLAGS="-Wl,--rpath -Wl,${INSTALL_DIR}/lib" 
188 =item HPUX
190  export LDFLAGS="+b${INSTALL_DIR}/lib"
192 =item AIX
194  export LDFLAGS="-Wl,-blibpath:${INSTALL_DIR}/lib"
196 =back 
198 If you have GNU make installed and it is not called 'make',
199 then do
201  export MAKE=gmake
202  export GNUMAKE=gmake
204 otherwise just do
206  export MAKE=make
208 =head3 Building pkgconfig
210 As mentioned above, without pkgconfig the whole build process will be lots
211 of pain and suffering, so make sure you have a copy on your system. If it is
212 not available natively, here is how to compile it.
214  wget http://pkgconfig.freedesktop.org/releases/pkg-config-0.23.tar.gz
215  gunzip -c pkg-config-0.23.tar.gz | tar xf -
216  cd pkg-config-0.23
217  ./configure --prefix=$INSTALL_DIR
218  $MAKE
219  $MAKE install
221 After installing pkgconfig in a custom directory, setting up the corresponding
222 environment variable will be helpful.
224  export PKG_CONFIG=$INSTALL_DIR/bin/pkg-config
226 =head3 Building zlib
228 Chances are very high that you already have that on your system ... 
230  cd $BUILD_DIR
231  wget http://oss.oetiker.ch/rrdtool/pub/libs/zlib-1.2.3.tar.gz
232  gunzip -c zlib-1.2.3.tar.gz | tar xf -
233  cd zlib-1.2.3
234  ./configure --prefix=$INSTALL_DIR --shared
235  $MAKE
236  $MAKE install
238 =head3 Building libpng
240 Libpng itself requires zlib to build, so we need to help a bit. If you
241 already have a copy of zlib on your system (which is very likely) you can
242 drop the settings of LDFLAGS and CPPFLAGS. Note that the backslash (\) at
243 the end of line 4 means that line 4 and line 5 are on one line.
245  cd $BUILD_DIR
246  wget http://oss.oetiker.ch/rrdtool/pub/libs/libpng-1.2.18.tar.gz
247  gunzip -c libpng-1.2.18.tar.gz | tar xf -
248  cd libpng-1.2.18
249  ./configure --prefix=$INSTALL_DIR
250  $MAKE
251  $MAKE install
253 =head3 Building freetype
255  cd $BUILD_DIR
256  wget http://oss.oetiker.ch/rrdtool/pub/libs/freetype-2.3.5.tar.gz
257  gunzip -c freetype-2.3.5.tar.gz | tar xf -
258  cd freetype-2.3.5
259  ./configure --prefix=$INSTALL_DIR CFLAGS="-O3 -fPIC"
260  $MAKE
261  $MAKE install
263 If you run into problems building freetype on Solaris, you may want to try to
264 add the following at the start the configure line:
266  env EGREP=egrep
268 =head3 Building LibXML2
270  cd $BUILD_DIR
271  wget http://oss.oetiker.ch/rrdtool/pub/libs/libxml2-2.6.32.tar.gz
272  gunzip -c libxml2-2.6.32.tar.gz | tar xf -
273  cd libxml2-2.6.32
274  ./configure --prefix=$INSTALL_DIR
275  $MAKE
276  $MAKE install
278 =head3 Building fontconfig
280 Note that fontconfig has a run time configuration file in INSTALL_DIR/etc you
281 may want to adjust that so that fontconfig finds the fonts on your system.
282 Run the fc-cache program to build the fontconfig cache after changing the
283 config file.
285  cd $BUILD_DIR
286  wget http://oss.oetiker.ch/rrdtool/pub/libs/fontconfig-2.4.2.tar.gz
287  gunzip -c fontconfig-2.4.2.tar.gz   | tar xf -
288  cd fontconfig-2.4.2
289  ./configure --prefix=$INSTALL_DIR --with-freetype-config=$INSTALL_DIR/bin/freetype-config
290  $MAKE
291  $MAKE install
293 =head3 Building Pixman
295  cd $BUILD_DIR
296  wget http://oss.oetiker.ch/rrdtool/pub/libs/pixman-0.10.0.tar.gz
297  gunzip -c pixman-0.10.0.tar.gz  | tar xf -
298  cd pixman-0.10.0
299  ./configure --prefix=$INSTALL_DIR
300  $MAKE
301  $MAKE install
303 =head3 Building Cairo
305  cd $BUILD_DIR
306  wget http://oss.oetiker.ch/rrdtool/pub/libs/cairo-1.6.4.tar.gz
307  gunzip -c cairo-1.6.4.tar.gz   | tar xf -
308  cd cairo-1.6.4
309  ./configure --prefix=$INSTALL_DIR \
310     --enable-xlib=no \
311     --enable-xlib-render=no \
312     --enable-win32=no
313  $MAKE
314  $MAKE install
316 =head3 Building Glib
318  cd $BUILD_DIR
319  wget http://oss.oetiker.ch/rrdtool/pub/libs/glib-2.15.4.tar.gz
320  gunzip -c glib-2.15.4.tar.gz  | tar xf -
321  cd glib-2.15.4
322  ./configure --prefix=$INSTALL_DIR
323  $MAKE
324  $MAKE install
326 =head3 Building Pango
328  cd $BUILD_DIR
329  wget http://oss.oetiker.ch/rrdtool/pub/libs/pango-1.21.1.tar.bz2
330  bunzip2 -c pango-1.21.1.tar.bz2 | tar xf -
331  cd pango-1.21.1
332  ./configure --prefix=$INSTALL_DIR --without-x
333  $MAKE
334  $MAKE install
336 =head2 Building rrdtool (second try)
338 Now all the dependent libraries are built and you can try again. This time
339 you tell configure where it should be looking for libraries and include
340 files. This is done via environment variables. Depending on the shell you
341 are running, the syntax for setting environment variables is different.
343 And finally try building again. We disable the python and tcl bindings
344 because it seems that a fair number of people have ill configured python and
345 tcl setups that would prevent rrdtool from building if they are included in
346 their current state.
348  cd $BUILD_DIR/rrdtool-1.3.7
349  ./configure --prefix=$INSTALL_DIR --disable-tcl --disable-python
350  $MAKE clean
351  $MAKE
352  $MAKE install
354 SOLARIS HINT: if you want to build  the Perl module for the native Perl (the
355 one shipping with Solaris) you will need the Sun Forte compiler installed on
356 your box or you have to hand-tune bindings/perl-shared/Makefile while
357 building!
359 Now go to I<$INSTALL_DIR>B</share/rrdtool/examples/> and run them to see if
360 your build has been successful.
362 =head1 AUTHOR
364 Tobias Oetiker E<lt>tobi@oetiker.chE<gt>