Code

Imported upstream version 1.3.8.
[pkg-rrdtool.git] / doc / rrdbuild.1
1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "RRDBUILD 1"
127 .TH RRDBUILD 1 "2009-05-19" "1.3.8" "rrdtool"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 rrdbuild \- Instructions for building RRDtool
134 .SH "OVERVIEW"
135 .IX Header "OVERVIEW"
136 If you downloaded the source of rrdtool you have to compile it. This
137 document will give some information on how this is done.
138 .PP
139 RRDtool relies on services of third part libraries. Some of these libraries
140 may already be installed on your system. You have to compile copies of the other
141 ones before you can build RRDtool.
142 .PP
143 This document will tell you about all the necessary steps to get going.
144 .PP
145 These instructions assume you are using a \fBbash\fR shell. If you use csh/tcsh,
146 then you can either type \fIbash\fR to switch to bash for the compilation or if
147 you know what you are doing just replace the export bits with
148 setenv.
149 .PP
150 We further assume that your copies of \fBtar\fR and \fBmake\fR are actually \fB\s-1GNU\s0
151 tar\fR and \fB\s-1GNU\s0 make\fR respectively. It could be that they are installed as
152 \&\fBgtar\fR and \fBgmake\fR on your system.
153 .SH "OPTIMISTIC BUILD"
154 .IX Header "OPTIMISTIC BUILD"
155 Before you start to build RRDtool, you have to decide two things:
156 .IP "1." 4
157 In which directory you want to build the software.
158 .IP "2." 4
159 Where you want to install the software.
160 .PP
161 Once you have decided. Save the two locations into environment variables.
162 .PP
163 .Vb 2
164 \& BUILD_DIR=/tmp/rrdbuild
165 \& INSTALL_DIR=/usr/local/rrdtool\-1.3.8
166 .Ve
167 .PP
168 If your \fI/tmp\fR is mounted with the option noexec (\s-1RHEL\s0 seems todo that) you have to choose
169 a different directory!
170 .PP
171 Now make sure the \s-1BUILD_DIR\s0 exists and go there:
172 .PP
173 .Vb 2
174 \& mkdir \-p $BUILD_DIR
175 \& cd $BUILD_DIR
176 .Ve
177 .PP
178 Lets first assume you already have all the necessary libraries
179 pre-installed.
180 .PP
181 .Vb 4
182 \& wget http://oss.oetiker.ch/rrdtool/pub/rrdtool\-1.3.8.tar.gz
183 \& gunzip \-c rrdtool\-1.3.8.tar.gz | tar xf \-
184 \& cd rrdtool\-1.3.8
185 \& ./configure \-\-prefix=$INSTALL_DIR && make && make install
186 .Ve
187 .PP
188 Ok, this was very optimistic. This try will probably have ended with
189 \&\fBconfigure\fR complaining about several missing libraries.
190 .SH "INSTALLING DEPENDENCIES"
191 .IX Header "INSTALLING DEPENDENCIES"
192 If your \s-1OS\s0 lets you install additional packages from a software repository,
193 you may get away with installing the missing packages. When the packages are
194 installed, run configure again and try to compile again. Below you find some
195 hints on getting your \s-1OS\s0 ready for the rrdtool compilation.
196 .PP
197 Additions to this list are welcome. In general rrdtool should work with the
198 latest versions of the libraries. The versions listed here are just what was
199 current when I tested this.
200 .SS "OpenSolaris 2008.05"
201 .IX Subsection "OpenSolaris 2008.05"
202 Just add a compiler and the gnome development package:
203 .PP
204 .Vb 2
205 \& pkg install sunstudioexpress
206 \& pkg install SUNWgnome\-common\-devel
207 .Ve
208 .PP
209 There is a problem with \fIcairo.pc\fR on OpenSolaris. It suggests that
210 xrender is required for compilation with cairo. This is not true and also
211 bad since OpenSolaris does not include an \fIxrender.pc\fR file. Use Perl to
212 fix this:
213 .PP
214 .Vb 1
215 \& perl \-i~ \-p \-e \*(Aqs/(Requires.*?)\es*xrender.*/$1/\*(Aq /usr/lib/pkgconfig/cairo.pc
216 .Ve
217 .PP
218 Make sure rrdtool finds your new compiler
219 .PP
220 .Vb 1
221 \& export PATH=/opt/SunStudioExpress/bin
222 .Ve
223 .PP
224 Since there does not seem to be a viable msgfmt tool on OpenSolaris (short
225 of installing it yourself). You have to call configure with the
226 .PP
227 .Vb 1
228 \& \-\-disable\-libintl
229 .Ve
230 .PP
231 option.
232 .SS "Debian / Ubuntu"
233 .IX Subsection "Debian / Ubuntu"
234 Use apt-get to make sure you have all that is required. A number
235 of packages will get added through dependencies.
236 .PP
237 .Vb 1
238 \& apt\-get install libpango1.0\-dev libxml2\-dev
239 .Ve
240 .SS "Gentoo"
241 .IX Subsection "Gentoo"
242 In Gentoo installing rrdtool is really simple you just need to \fBemerge
243 rrdtool\fR. All dependencies will be handled automatically by the portage
244 system. The only thing you should care about are \s-1USE\s0 flags, which allow you
245 fine tune features rrdtool will be built with. Currently the following \s-1USE\s0
246 flags are available:
247 .PP
248 .Vb 7
249 \& doc    \- install .html and .txt documentation
250 \&          into /usr/share/doc/rrdtool\-1.x.xx/
251 \& perl   \- build and install perl language bindings
252 \& python \- build and install python language bindings
253 \& ruby   \- build and install ruby language bindings
254 \& tcl    \- build and install tcl language bindings
255 \& rrdcgi \- build and install rrdcgi
256 .Ve
257 .PP
258 After you've decided which \s-1USE\s0 flags you need, set them either in
259 \&\fImake.conf\fR or \fI/etc/portage/package.use\fR and finally run:
260 .PP
261 .Vb 1
262 \& # emerge \-va rrdtool
263 .Ve
264 .PP
265 Take a look at Gentoo handbook for further details on how to manage \s-1USE\s0
266 flags: http://www.gentoo.org/doc/en/handbook/handbook\-x86.xml?part=2
267 .SH "BUILDING DEPENDENCIES"
268 .IX Header "BUILDING DEPENDENCIES"
269 But again this may have been too optimistic still, and you actually have to
270 compile your own copies of some of the required libraries. Things like
271 libpng and zlib are pretty standard so you will probably have them on your
272 system anyway. Freetype, Fontinst, Cairo, Pango may be installed, but it is
273 possible that they are pretty old and thus don't live up to our
274 expectations, so you may want to compile their latest versions.
275 .SS "General build tips for \s-1AIX\s0"
276 .IX Subsection "General build tips for AIX"
277 If you are working with \s-1AIX\s0, you may find the \fB\-\-disable\-shared\fR option
278 will cause things to break for you. In that case you may have to install the
279 shared libraries into the rrdtool \s-1PREFIX\s0 and work with \fB\-\-disable\-static\fR
280 instead.
281 .PP
282 Another hint to get rrdtool working on \s-1AIX\s0 is to use the \s-1IBM\s0 \s-1XL\s0 C Compiler:
283 .PP
284 .Vb 2
285 \& export CC=/usr/vac/bin/cc
286 \& export PERLCC=$CC
287 .Ve
288 .PP
289 (Better instructions for \s-1AIX\s0 welcome!)
290 .SS "Build Instructions"
291 .IX Subsection "Build Instructions"
292 Some libraries want to know where other libraries are. For this to work,
293 set the following environment variable
294 .PP
295 .Vb 2
296 \& export PKG_CONFIG_PATH=${INSTALL_DIR}/lib/pkgconfig
297 \& export PATH=$INSTALL_DIR/bin:$PATH
298 .Ve
299 .PP
300 The above relies on the presence of the \fIpkgconfig\fR program. Below you find instructions
301 on how to compile pkgconfig.
302 .PP
303 Since we are compiling libraries dynamically, they must know where to find
304 each other. This is done by setting an appropriate \s-1LDFLAGS\s0. Unfortunately,
305 the syntax again differs from system to system:
306 .IP "Solaris" 4
307 .IX Item "Solaris"
308 .Vb 1
309 \& export LDFLAGS=\-R${INSTALL_DIR}/lib
310 .Ve
311 .Sp
312 if you are using the Sun Studio/Forte compiler, you may also want to set
313 .Sp
314 .Vb 2
315 \& export CFLAGS="\-xO3 \-xcode=pic13"   (SPARC)
316 \& export CFLAGS="\-xO3 \-Kpic"          (x86)
317 .Ve
318 .IP "Linux" 4
319 .IX Item "Linux"
320 .Vb 2
321 \& export CFLAGS="\-O3 \-fPIC"
322 \& export LDFLAGS="\-Wl,\-\-rpath \-Wl,${INSTALL_DIR}/lib"
323 .Ve
324 .IP "\s-1HPUX\s0" 4
325 .IX Item "HPUX"
326 .Vb 1
327 \& export LDFLAGS="+b${INSTALL_DIR}/lib"
328 .Ve
329 .IP "\s-1AIX\s0" 4
330 .IX Item "AIX"
331 .Vb 1
332 \& export LDFLAGS="\-Wl,\-blibpath:${INSTALL_DIR}/lib"
333 .Ve
334 .PP
335 If you have \s-1GNU\s0 make installed and it is not called 'make',
336 then do
337 .PP
338 .Vb 2
339 \& export MAKE=gmake
340 \& export GNUMAKE=gmake
341 .Ve
342 .PP
343 otherwise just do
344 .PP
345 .Vb 1
346 \& export MAKE=make
347 .Ve
348 .PP
349 \fIBuilding pkgconfig\fR
350 .IX Subsection "Building pkgconfig"
351 .PP
352 As mentioned above, without pkgconfig the whole build process will be lots
353 of pain and suffering, so make sure you have a copy on your system. If it is
354 not available natively, here is how to compile it.
355 .PP
356 .Vb 6
357 \& wget http://pkgconfig.freedesktop.org/releases/pkg\-config\-0.23.tar.gz
358 \& gunzip \-c pkg\-config\-0.23.tar.gz | tar xf \-
359 \& cd pkg\-config\-0.23
360 \& ./configure \-\-prefix=$INSTALL_DIR
361 \& $MAKE
362 \& $MAKE install
363 .Ve
364 .PP
365 After installing pkgconfig in a custom directory, setting up the corresponding
366 environment variable will be helpful.
367 .PP
368 .Vb 1
369 \& export PKG_CONFIG=$INSTALL_DIR/bin/pkg\-config
370 .Ve
371 .PP
372 \fIBuilding zlib\fR
373 .IX Subsection "Building zlib"
374 .PP
375 Chances are very high that you already have that on your system ...
376 .PP
377 .Vb 7
378 \& cd $BUILD_DIR
379 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/zlib\-1.2.3.tar.gz
380 \& gunzip \-c zlib\-1.2.3.tar.gz | tar xf \-
381 \& cd zlib\-1.2.3
382 \& ./configure \-\-prefix=$INSTALL_DIR \-\-shared
383 \& $MAKE
384 \& $MAKE install
385 .Ve
386 .PP
387 \fIBuilding libpng\fR
388 .IX Subsection "Building libpng"
389 .PP
390 Libpng itself requires zlib to build, so we need to help a bit. If you
391 already have a copy of zlib on your system (which is very likely) you can
392 drop the settings of \s-1LDFLAGS\s0 and \s-1CPPFLAGS\s0. Note that the backslash (\e) at
393 the end of line 4 means that line 4 and line 5 are on one line.
394 .PP
395 .Vb 7
396 \& cd $BUILD_DIR
397 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/libpng\-1.2.18.tar.gz
398 \& gunzip \-c libpng\-1.2.18.tar.gz | tar xf \-
399 \& cd libpng\-1.2.18
400 \& ./configure \-\-prefix=$INSTALL_DIR
401 \& $MAKE
402 \& $MAKE install
403 .Ve
404 .PP
405 \fIBuilding freetype\fR
406 .IX Subsection "Building freetype"
407 .PP
408 .Vb 7
409 \& cd $BUILD_DIR
410 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/freetype\-2.3.5.tar.gz
411 \& gunzip \-c freetype\-2.3.5.tar.gz | tar xf \-
412 \& cd freetype\-2.3.5
413 \& ./configure \-\-prefix=$INSTALL_DIR CFLAGS="\-O3 \-fPIC"
414 \& $MAKE
415 \& $MAKE install
416 .Ve
417 .PP
418 If you run into problems building freetype on Solaris, you may want to try to
419 add the following at the start the configure line:
420 .PP
421 .Vb 1
422 \& env EGREP=egrep
423 .Ve
424 .PP
425 \fIBuilding LibXML2\fR
426 .IX Subsection "Building LibXML2"
427 .PP
428 .Vb 7
429 \& cd $BUILD_DIR
430 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/libxml2\-2.6.32.tar.gz
431 \& gunzip \-c libxml2\-2.6.32.tar.gz | tar xf \-
432 \& cd libxml2\-2.6.32
433 \& ./configure \-\-prefix=$INSTALL_DIR
434 \& $MAKE
435 \& $MAKE install
436 .Ve
437 .PP
438 \fIBuilding fontconfig\fR
439 .IX Subsection "Building fontconfig"
440 .PP
441 Note that fontconfig has a run time configuration file in INSTALL_DIR/etc you
442 may want to adjust that so that fontconfig finds the fonts on your system.
443 Run the fc-cache program to build the fontconfig cache after changing the
444 config file.
445 .PP
446 .Vb 7
447 \& cd $BUILD_DIR
448 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/fontconfig\-2.4.2.tar.gz
449 \& gunzip \-c fontconfig\-2.4.2.tar.gz   | tar xf \-
450 \& cd fontconfig\-2.4.2
451 \& ./configure \-\-prefix=$INSTALL_DIR \-\-with\-freetype\-config=$INSTALL_DIR/bin/freetype\-config
452 \& $MAKE
453 \& $MAKE install
454 .Ve
455 .PP
456 \fIBuilding Pixman\fR
457 .IX Subsection "Building Pixman"
458 .PP
459 .Vb 7
460 \& cd $BUILD_DIR
461 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/pixman\-0.10.0.tar.gz
462 \& gunzip \-c pixman\-0.10.0.tar.gz  | tar xf \-
463 \& cd pixman\-0.10.0
464 \& ./configure \-\-prefix=$INSTALL_DIR
465 \& $MAKE
466 \& $MAKE install
467 .Ve
468 .PP
469 \fIBuilding Cairo\fR
470 .IX Subsection "Building Cairo"
471 .PP
472 .Vb 10
473 \& cd $BUILD_DIR
474 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/cairo\-1.6.4.tar.gz
475 \& gunzip \-c cairo\-1.6.4.tar.gz   | tar xf \-
476 \& cd cairo\-1.6.4
477 \& ./configure \-\-prefix=$INSTALL_DIR \e
478 \&    \-\-enable\-xlib=no \e
479 \&    \-\-enable\-xlib\-render=no \e
480 \&    \-\-enable\-win32=no
481 \& $MAKE
482 \& $MAKE install
483 .Ve
484 .PP
485 \fIBuilding Glib\fR
486 .IX Subsection "Building Glib"
487 .PP
488 .Vb 7
489 \& cd $BUILD_DIR
490 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/glib\-2.15.4.tar.gz
491 \& gunzip \-c glib\-2.15.4.tar.gz  | tar xf \-
492 \& cd glib\-2.15.4
493 \& ./configure \-\-prefix=$INSTALL_DIR
494 \& $MAKE
495 \& $MAKE install
496 .Ve
497 .PP
498 \fIBuilding Pango\fR
499 .IX Subsection "Building Pango"
500 .PP
501 .Vb 7
502 \& cd $BUILD_DIR
503 \& wget http://oss.oetiker.ch/rrdtool/pub/libs/pango\-1.21.1.tar.bz2
504 \& bunzip2 \-c pango\-1.21.1.tar.bz2 | tar xf \-
505 \& cd pango\-1.21.1
506 \& ./configure \-\-prefix=$INSTALL_DIR \-\-without\-x
507 \& $MAKE
508 \& $MAKE install
509 .Ve
510 .SS "Building rrdtool (second try)"
511 .IX Subsection "Building rrdtool (second try)"
512 Now all the dependent libraries are built and you can try again. This time
513 you tell configure where it should be looking for libraries and include
514 files. This is done via environment variables. Depending on the shell you
515 are running, the syntax for setting environment variables is different.
516 .PP
517 And finally try building again. We disable the python and tcl bindings
518 because it seems that a fair number of people have ill configured python and
519 tcl setups that would prevent rrdtool from building if they are included in
520 their current state.
521 .PP
522 .Vb 5
523 \& cd $BUILD_DIR/rrdtool\-1.3.8
524 \& ./configure \-\-prefix=$INSTALL_DIR \-\-disable\-tcl \-\-disable\-python
525 \& $MAKE clean
526 \& $MAKE
527 \& $MAKE install
528 .Ve
529 .PP
530 \&\s-1SOLARIS\s0 \s-1HINT:\s0 if you want to build  the Perl module for the native Perl (the
531 one shipping with Solaris) you will need the Sun Forte compiler installed on
532 your box or you have to hand-tune bindings/perl\-shared/Makefile while
533 building!
534 .PP
535 Now go to \fI\f(CI$INSTALL_DIR\fI\fR\fB/share/rrdtool/examples/\fR and run them to see if
536 your build has been successful.
537 .SH "AUTHOR"
538 .IX Header "AUTHOR"
539 Tobias Oetiker <tobi@oetiker.ch>