1 <chapter id="installation">
2 <title>Installation</title>
4 &zebra; is written in &acro.ansi; C and was implemented with portability in mind.
5 We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and
6 <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
10 The software is regularly tested on
11 <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
12 <ulink url="&url.redhat;">Red Hat Linux</ulink>,
13 <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
14 <ulink url="&url.macosx;">MAC OSX</ulink>,
19 &zebra; can be configured to use the following utilities (most of
24 <term><ulink url="&url.yaz;">&yaz;</ulink>
28 &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> /
29 <ulink url="&url.sru;">&acro.sru;</ulink>.
30 Zebra also uses a lot of other utilities (not related to networking),
31 such as memory management and XML support.
34 For the <link linkend="record-model-domxml">DOM XML</link>
35 / <link linkend="record-model-alvisxslt">ALVIS</link>
36 record filters, &yaz; must be compiled with
37 <ulink url="&url.libxml2;">Libxml2</ulink>
39 <ulink url="&url.libxslt;">Libxslt</ulink>
40 support and Libxml2 must be version 2.6.15 or later.
45 <term><ulink url="&url.libiconv;">iconv</ulink>
49 Character set conversion. This is required if you're
50 going to use any other character set than UTF-8 and ISO-8859-1
51 for records. Note that some Unixes has iconv built-in.
56 <term><ulink url="&url.expat;">Expat</ulink>
60 &acro.xml; parser. If you're going to index real &acro.xml; you should
61 install this (filter grs.xml). On most systems you should be able
62 to find binary Expat packages.
68 <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
71 Tcl is required if you need to use the Tcl record filter
72 for &zebra;. You can find binary packages for Tcl for many
80 <ulink url="&url.autoconf;">Autoconf</ulink>,
81 <ulink url="&url.automake;">Automake</ulink>
85 GNU Automake and Autoconf are only required if you're
86 using the CVS version of &zebra;. You do not need these
87 if you have fetched a &zebra; tar.
93 <term><ulink url="&url.docbook;">Docbook</ulink>
94 and friends (optional)</term>
97 These tools are only required if you're writing
98 documentation for &zebra;. You need the following
99 Debian packages: docbook, docbook-xml, docbook-xsl,
100 docbook-utils, xsltproc.
107 <section id="installation-unix"><title>UNIX</title>
109 On Unix, GCC works fine, but any native
110 C compiler should be possible to use as long as it is
111 &acro.ansi; C compliant.
115 Unpack the distribution archive. The <literal>configure</literal>
116 shell script attempts to guess correct values for various
117 system-dependent variables used during compilation.
118 It uses those values to create a <literal>Makefile</literal> in each
119 directory of &zebra;.
123 To run the configure script type:
132 The configure script attempts to use C compiler specified by
133 the <literal>CC</literal> environment variable.
134 If this is not set, <literal>cc</literal> or GNU C will be used.
135 The <literal>CFLAGS</literal> environment variable holds
136 options to be passed to the C compiler. If you're using a
137 Bourne-shell compatible shell you may pass something like this:
140 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
144 The configure script support various options: you can see what they
152 Once the build environment is configured, build the software by
160 If the build is successful, two executables are created in the
161 sub-directory <literal>index</literal>:
165 <term><literal>zebrasrv</literal></term>
168 The &acro.z3950; server and search engine.
173 <term><literal>zebraidx</literal></term>
176 The administrative indexing tool.
182 <term><literal>index/*.so</literal></term>
185 The <literal>.so</literal>-files are &zebra; record filter modules.
186 There are modules for reading
187 &acro.marc; (<filename>mod-grs-marc.so</filename>),
188 &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc.
198 Using configure option <literal>--disable-shared</literal> builds
199 &zebra; statically and links "in" &zebra; filter code statically, i.e.
200 no <literal>.so-files</literal> are generated
205 You can now use &zebra;. If you wish to install it system-wide, then
210 By default this will install the &zebra; executables in
211 <filename>/usr/local/bin</filename>,
212 and the standard configuration files in
213 <filename>/usr/local/share/idzebra-2.0</filename>. If
214 shared modules are built, these are installed in
215 <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
216 You can override this with the <literal>--prefix</literal> option
221 <section id="installation-debian"><title>GNU/Debian</title>
222 <section id="installation-debian-linux"><title>GNU/Debian Linux on
223 amd64/i386 Platform</title>
225 Index Data provides pre-compiled GNU/Debian and Ubuntu packages
226 at our Debian package archive, both for recent releases.
231 <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/README"/>
232 for how to configure APT. For Ubuntu, refer to
233 <ulink url="http://ftp.indexdata.dk/pub/zebra/ubuntu/README"/>.
234 After refreshing the package cache with the command
238 as <literal>root</literal>, the
239 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
240 easily installed issuing
242 apt-get install idzebra-2.0 idzebra-2.0-doc
247 <section id="installation-debia-nother">
248 <title>GNU/Debian and Ubuntu on other architectures</title>
250 These <ulink url="&url.idzebra;">&zebra;</ulink>
251 packages are specifically compiled for
252 GNU/Debian Linux systems and Ubuntu. Installation on other
253 GNU/Debian systems is possible by
254 re-compilation the Debian way: you need to add only the
255 <literal>deb-src</literal> sources lines to the
256 <filename>/etc/apt/sources.list</filename> configuration file,
257 After refreshing the package cache with the command
260 apt-get build-dep idzebra-2.0
262 as <literal>root</literal>, the
263 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
264 recompiled and installed issuing
266 fakeroot apt-get source --compile idzebra-2.0
269 The compiled GNU/Debian packages can then be
270 installed as <literal>root</literal> issuing
272 dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
278 <section id="installation-win32"><title>Windows</title>
279 <para>The easiest way to install &zebra; on Windows is by downloading
281 <ulink url="&url.idzebra.download.win32;">here</ulink>.
282 The installer comes with source too - in case you wish to
283 compile &zebra; with different Compiler options.
287 &zebra; is shipped with "makefiles" for the NMAKE tool that comes
288 with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
289 Version 2013 has been tested.
292 Start a command prompt and switch the sub directory
293 <filename>WIN</filename> where the file <filename>makefile</filename>
294 is located. Customize the installation by editing the
295 <filename>makefile</filename> file (for example by using notepad).
297 The following summarizes the most important settings in that file:
300 <varlistentry><term><literal>DEBUG</literal></term>
302 If set to 1, the software is
303 compiled with debugging libraries (code generation is
304 multi-threaded debug DLL).
305 If set to 0, the software is compiled with release libraries
306 (code generation is multi-threaded DLL).
311 <term><literal>YAZDIR</literal></term>
313 Directory of &yaz; source. &zebra;'s makefile expects to find
314 YAZ<filename>.lib</filename>, YAZ<filename>.dll</filename>
315 in <replaceable>yazdir</replaceable><literal>/lib</literal> and
316 <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
322 <term><literal>HAVE_EXPAT</literal>,
323 <literal>EXPAT_DIR</literal></term>
325 If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
326 with <ulink url="&url.expat;">Expat</ulink> support.
327 In this configuration, set
328 <literal>ZEBRA_DIR</literal> to the Expat source directory.
329 Windows version of Expat can be downloaded from
330 <ulink url="&url.expat;">SourceForge</ulink>.
335 <term><literal>BZIP2INCLUDE</literal>,
336 <literal>BZIP2LIB</literal>,
337 <literal>BZIP2DEF</literal>
340 Define these symbols if &zebra; is to be compiled with
341 <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
349 The <literal>DEBUG</literal> setting in the makefile for &zebra; must
350 be set to the same value as <literal>DEBUG</literal> setting in the
352 If not, the &zebra; server/indexer will crash.
356 When satisfied with the settings in the makefile, type
363 If the <filename>nmake</filename> command is not found on your system
364 you probably haven't defined the environment variables required to
365 use that tool. To fix that, find and run the batch file
366 <filename>vcvars32.bat</filename>. You need to run it from within
367 the command prompt or set the environment variables "globally";
368 otherwise it doesn't work.
372 If you wish to recompile &zebra; - for example if you modify
373 settings in the <filename>makefile</filename> you can delete
374 object files, etc by running.
380 The following files are generated upon successful compilation:
383 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
386 </para></listitem></varlistentry>
388 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
391 </para></listitem></varlistentry>
399 <section id="installation-upgrade">
400 <title>Upgrading from &zebra; version 1.3.x</title>
402 &zebra;'s installation directories have changed a bit. In addition,
403 the new loadable modules must be defined in the
404 master <filename>zebra.cfg</filename> configuration file. The old
405 version 1.3.x configuration options
407 # profilePath - where to look for config files
408 profilePath: some/local/path:/usr/share/idzebra/tab
412 # profilePath - where to look for config files
413 profilePath: some/local/path:/usr/share/idzebra-2.0/tab
415 # modulePath - where to look for loadable zebra modules
416 modulePath: /usr/lib/idzebra-2.0/modules
421 The internal binary register structures have changed; all &zebra;
422 databases must be re-indexed after upgrade.
426 The attribute set definition files may no longer contain
427 redirection to other fields.
428 For example the following snippet of
429 a custom <filename>custom/bib1.att</filename>
430 &acro.bib1; attribute set definition file is no
433 att 1016 Any 1016,4,1005,62
435 and should be changed to
441 Similar behaviour can be expressed in the new release by defining
442 a new index <literal>Any:w</literal> in all &acro.grs1;
443 <filename>*.abs</filename> record indexing configuration files.
444 The above example configuration needs to make the changes
445 from version 1.3.x indexing instructions
447 xelm /*/alternative Body-of-text:w,Title:s,Title:w
448 xelm /*/title Body-of-text:w,Title:s,Title:w
450 to version 2.0.0 indexing instructions
452 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
453 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
457 It is also possible to map the numerical attribute value
458 <literal>@attr 1=1016</literal> onto another already existing huge
459 index, in this example, one could for example use the mapping
461 att 1016 Body-of-text
463 with equivalent outcome without editing all &acro.grs1;
464 <filename>*.abs</filename> record indexing configuration files.
468 Server installations which use the special
469 <literal>&acro.idxpath;</literal> attribute set must add the following
470 line to the <filename>zebra.cfg</filename> configuration file:
478 <!-- Keep this comment at the end of the file
483 sgml-minimize-attributes:nil
484 sgml-always-quote-attributes:t
487 sgml-parent-document: "idzebra.xml"
488 sgml-local-catalogs: nil
489 sgml-namecase-general:t