1 <!-- $Id: installation.xml,v 1.34 2007-02-02 09:58:39 marc Exp $ -->
2 <chapter id="installation">
3 <title>Installation</title>
5 &zebra; is written in ANSI C and was implemented with portability in mind.
6 We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and
7 <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
11 The software is regularly tested on
12 <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
13 <ulink url="&url.redhat;">Redhat Linux</ulink>,
14 <ulink url="&url.gentoo;">Gentoo Linux</ulink>,
15 <ulink url="&url.suse;">SuSE Linux</ulink>,
16 <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
17 <ulink url="&url.macosx;">MAC OSX</ulink>,
18 <ulink url="&url.solaris;">SunOS 5.9
20 <ulink url="&url.windows2000;">Windows 2000</ulink>.
24 &zebra; can be configured to use the following utilities (most of
29 <term><ulink url="&url.yaz;">yaz</ulink>
33 &zebra; uses YAZ to support <ulink url="&url.z39.50;">Z39.50</ulink> /
34 <ulink url="&url.sru;">SRU</ulink>.
35 Also the memory management utilites from YAZ is used by &zebra;.
40 <term><ulink url="&url.libiconv;">iconv</ulink>
44 Character set conversion. This is required if you're
45 going to use any other character set than UTF-8 and ISO-8859-1
46 for records. Note that some Unixes has iconv built-in.
51 <term><ulink url="&url.expat;">Expat</ulink>
55 XML parser. If you're going to index real XML you should
56 install this (filter grs.xml). On most systems you should be able
57 to find binary Expat packages.
63 <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
66 Tcl is required if you need to use the Tcl record filter
67 for &zebra;. You can find binary packages for Tcl for many
75 <ulink url="&url.autoconf;">Autoconf</ulink>,
76 <ulink url="&url.automake;">Automake</ulink>
80 GNU Automake and Autoconf are only required if you're
81 using the CVS version of &zebra;. You do not need these
82 if you have fetched a &zebra; tar.
88 <term><ulink url="&url.docbook;">Docbook</ulink>
89 and friends (optional)</term>
92 These tools are only required if you're writing
93 documentation for &zebra;. You need the following
94 Debian packages: docbook, docbook-xml, docbook-xsl,
95 docbook-utils, xsltproc.
102 <section id="installation-unix"><title>UNIX</title>
104 On Unix, GCC works fine, but any native
105 C compiler should be possible to use as long as it is
110 Unpack the distribution archive. The <literal>configure</literal>
111 shell script attempts to guess correct values for various
112 system-dependent variables used during compilation.
113 It uses those values to create a <literal>Makefile</literal> in each
114 directory of &zebra;.
118 To run the configure script type:
127 The configure script attempts to use C compiler specified by
128 the <literal>CC</literal> environment variable.
129 If this is not set, <literal>cc</literal> or GNU C will be used.
130 The <literal>CFLAGS</literal> environment variable holds
131 options to be passed to the C compiler. If you're using a
132 Bourne-shell compatible shell you may pass something like this:
135 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
139 The configure script support various options: you can see what they
147 Once the build environment is configured, build the software by
155 If the build is successful, two executables are created in the
156 sub-directory <literal>index</literal>:
160 <term><literal>zebrasrv</literal></term>
163 The Z39.50 server and search engine.
168 <term><literal>zebraidx</literal></term>
171 The administrative indexing tool.
177 <term><literal>index/*.so</literal></term>
180 The <literal>.so</literal>-files are &zebra; record filter modules.
181 There are modules for reading
182 MARC (<filename>mod-grs-marc.so</filename>),
183 XML (<filename>mod-grs-xml.so</filename>) , etc.
193 Using configure option <literal>--disable-shared</literal> builds
194 &zebra; statically and links "in" &zebra; filter code statically, i.e.
195 no <literal>.so-files</literal> are generated
200 You can now use &zebra;. If you wish to install it system-wide, then
205 By default this will install the &zebra; executables in
206 <filename>/usr/local/bin</filename>,
207 and the standard configuration files in
208 <filename>/usr/local/share/idzebra-2.0</filename>. If
209 shared modules are built, these are installed in
210 <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
211 You can override this with the <literal>--prefix</literal> option
216 <section id="installation-debian"><title>GNU/Debian</title>
217 <section id="installation-debian-linux"><title>GNU/Debian Linux on
218 i686 Platform</title>
220 Index Data provides pre-compiled GNU/Debian i686 Linux packages
221 at our Debian package archive, both for
222 the Sarge and the Etch release.
226 To install these packages, you need to add two lines to your
227 <filename>/etc/apt/sources.list</filename> configuration file,
228 either the Sarge sources found at
230 deb http://ftp.indexdata.dk/debian sarge main
231 deb-src http://ftp.indexdata.dk/debian sarge main
233 or the Etch sources from
235 deb http://ftp.indexdata.dk/debian etch main
236 deb-src http://ftp.indexdata.dk/debian etch main
238 After refreshing the package cache with the command
242 as <literal>root</literal>, the
243 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
244 easily installed issuing
246 apt-get install idzebra-2.0 idzebra-2.0-doc
251 <section id="installation-debia-nother">
252 <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
254 These <ulink url="&url.idzebra;">&zebra;</ulink>
255 packages are specifically compiled for
256 GNU/Debian Linux systems. Installation on other
257 GNU/Debian systems is possible by
258 re-compilation the Debian way: you need to add only the
259 <literal>deb-src</literal> sources lines to the
260 <filename>/etc/apt/sources.list</filename> configuration file,
261 that is either the Sarge sources
263 deb-src http://ftp.indexdata.dk/debian sarge main
267 deb-src http://ftp.indexdata.dk/debian etch main
269 After refreshing the package cache with the command
272 apt-get build-dep idzebra-2.0
274 as <literal>root</literal>, the
275 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
276 recompiled and installed issuing
278 fakeroot apt-get source --compile idzebra-2.0
281 The compiled GNU/Debian packages can then be
282 installed as <literal>root</literal> issuing
284 dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
290 <section id="installation-win32"><title>WIN32</title>
291 <para>The easiest way to install &zebra; on Windows is by downloading
293 <ulink url="&url.idzebra.download.win32;">here</ulink>.
294 The installer comes with source too - in case you wish to
295 compile &zebra; with different Compiler options.
299 &zebra; is shipped with "makefiles" for the NMAKE tool that comes
300 with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
301 Version 2003 and 2005 has been tested. We expect that zebra compiles
302 with version 6 as well.
305 Start a command prompt and switch the sub directory
306 <filename>WIN</filename> where the file <filename>makefile</filename>
307 is located. Customize the installation by editing the
308 <filename>makefile</filename> file (for example by using notepad).
310 The following summarizes the most important settings in that file:
313 <varlistentry><term><literal>DEBUG</literal></term>
315 If set to 1, the software is
316 compiled with debugging libraries (code generation is
317 multi-threaded debug DLL).
318 If set to 0, the software is compiled with release libraries
319 (code generation is multi-threaded DLL).
324 <term><literal>YAZDIR</literal></term>
326 Directory of YAZ source. &zebra;'s makefile expects to find
327 <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
328 in <replaceable>yazdir</replaceable><literal>/lib</literal> and
329 <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
335 <term><literal>HAVE_EXPAT</literal>,
336 <literal>EXPAT_DIR</literal></term>
338 If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
339 with <ulink url="&url.expat;">Expat</ulink> support.
340 In this configuration, set
341 <literal>ZEBRA_DIR</literal> to the Expat source directory.
342 Windows version of Expat can be downloaded from
343 <ulink url="&url.expat;">SourceForge</ulink>.
348 <term><literal>HAVE_ICONV</literal>,
349 <literal>ICONV_DIR</literal></term>
351 If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
352 with iconv support. In this configuration, set
353 <literal>ICONV_DIR</literal> to the iconv source directory.
354 Iconv binaries can be downloaded from
355 <ulink url="&url.libxml2.download.win32;">this site</ulink>.
361 <term><literal>BZIP2INCLUDE</literal>,
362 <literal>BZIP2LIB</literal>,
363 <literal>BZIP2DEF</literal>
366 Define these symbols if &zebra; is to be compiled with
367 <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
375 The <literal>DEBUG</literal> setting in the makefile for &zebra; must
376 be set to the same value as <literal>DEBUG</literal> setting in the
378 If not, the &zebra; server/indexer will crash.
382 When satisfied with the settings in the makefile, type
389 If the <filename>nmake</filename> command is not found on your system
390 you probably haven't defined the environment variables required to
391 use that tool. To fix that, find and run the batch file
392 <filename>vcvars32.bat</filename>. You need to run it from within
393 the command prompt or set the environment variables "globally";
394 otherwise it doesn't work.
398 If you wish to recompile &zebra; - for example if you modify
399 settings in the <filename>makefile</filename> you can delete
400 object files, etc by running.
406 The following files are generated upon successful compilation:
409 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
412 </para></listitem></varlistentry>
414 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
417 </para></listitem></varlistentry>
425 <section id="installation-upgrade">
426 <title>Upgrading from &zebra; version 1.3.x</title>
428 &zebra;'s installation directories have changed a bit. In addition,
429 the new loadable modules must be defined in the
430 master <filename>zebra.cfg</filename> configuration file. The old
431 version 1.3.x configuration options
433 # profilePath - where to look for config files
434 profilePath: some/local/path:/usr/share/idzebra/tab
438 # profilePath - where to look for config files
439 profilePath: some/local/path:/usr/share/idzebra-2.0/tab
441 # modulePath - where to look for loadable zebra modules
442 modulePath: /usr/lib/idzebra-2.0/modules
447 The internal binary register structures have changed; all &zebra;
448 databases must be re-indexed after upgrade.
452 The attribute set defintion files may no longer contain
453 redirection to other fields.
454 For example the following snippet of
455 a custom <filename>custom/bib1.att</filename>
456 Bib-1 attribute set definition file is no
459 att 1016 Any 1016,4,1005,62
461 and should be changed to
467 Similar behaviour can be expressed in the new release by defining
468 a new index <literal>Any:w</literal> in all GRS
469 <filename>*.abs</filename> record indexing configuration files.
470 The above example configuration needs to make the changes
471 from version 1.3.x indexing instructions
473 xelm /*/alternative Body-of-text:w,Title:s,Title:w
474 xelm /*/title Body-of-text:w,Title:s,Title:w
476 to version 2.0.0 indexing instructions
478 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
479 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
483 It is also possible to map the numerical attribute value
484 <literal>@attr 1=1016</literal> onto another already existing huge
485 index, in this example, one could for example use the mapping
487 att 1016 Body-of-text
489 with equivalent outcome without editing all GRS
490 <filename>*.abs</filename> record indexing configuration files.
494 Server installations which use the special
495 <literal>IDXPATH</literal> attribute set must add the following
496 line to the <filename>zebra.cfg</filename> configuration file:
504 <!-- Keep this comment at the end of the file
509 sgml-minimize-attributes:nil
510 sgml-always-quote-attributes:t
513 sgml-parent-document: "zebra.xml"
514 sgml-local-catalogs: nil
515 sgml-namecase-general:t