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.gentoo;">Gentoo Linux</ulink>,
14 <ulink url="&url.suse;">SuSE Linux</ulink>,
15 <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
16 <ulink url="&url.macosx;">MAC OSX</ulink>,
17 <ulink url="&url.solaris;">SunOS 5.9
19 <ulink url="&url.windows2000;">Windows 2000</ulink>.
23 &zebra; can be configured to use the following utilities (most of
28 <term><ulink url="&url.yaz;">&yaz;</ulink>
32 &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> /
33 <ulink url="&url.sru;">&acro.sru;</ulink>.
34 Zebra also uses a lot of other utilities (not related to networking),
35 such as memory management and XML support.
38 For the <link linkend="record-model-domxml">DOM XML</link>
39 / <link linkend="record-model-alvisxslt">ALVIS</link>
40 record filters, &yaz; must be compiled with
41 <ulink url="&url.libxml2;">Libxml2</ulink>
43 <ulink url="&url.libxslt;">Libxslt</ulink>
44 support and Libxml2 must be version 2.6.15 or later.
49 <term><ulink url="&url.libiconv;">iconv</ulink>
53 Character set conversion. This is required if you're
54 going to use any other character set than UTF-8 and ISO-8859-1
55 for records. Note that some Unixes has iconv built-in.
60 <term><ulink url="&url.expat;">Expat</ulink>
64 &acro.xml; parser. If you're going to index real &acro.xml; you should
65 install this (filter grs.xml). On most systems you should be able
66 to find binary Expat packages.
72 <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
75 Tcl is required if you need to use the Tcl record filter
76 for &zebra;. You can find binary packages for Tcl for many
84 <ulink url="&url.autoconf;">Autoconf</ulink>,
85 <ulink url="&url.automake;">Automake</ulink>
89 GNU Automake and Autoconf are only required if you're
90 using the CVS version of &zebra;. You do not need these
91 if you have fetched a &zebra; tar.
97 <term><ulink url="&url.docbook;">Docbook</ulink>
98 and friends (optional)</term>
101 These tools are only required if you're writing
102 documentation for &zebra;. You need the following
103 Debian packages: docbook, docbook-xml, docbook-xsl,
104 docbook-utils, xsltproc.
111 <section id="installation-unix"><title>UNIX</title>
113 On Unix, GCC works fine, but any native
114 C compiler should be possible to use as long as it is
115 &acro.ansi; C compliant.
119 Unpack the distribution archive. The <literal>configure</literal>
120 shell script attempts to guess correct values for various
121 system-dependent variables used during compilation.
122 It uses those values to create a <literal>Makefile</literal> in each
123 directory of &zebra;.
127 To run the configure script type:
136 The configure script attempts to use C compiler specified by
137 the <literal>CC</literal> environment variable.
138 If this is not set, <literal>cc</literal> or GNU C will be used.
139 The <literal>CFLAGS</literal> environment variable holds
140 options to be passed to the C compiler. If you're using a
141 Bourne-shell compatible shell you may pass something like this:
144 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
148 The configure script support various options: you can see what they
156 Once the build environment is configured, build the software by
164 If the build is successful, two executables are created in the
165 sub-directory <literal>index</literal>:
169 <term><literal>zebrasrv</literal></term>
172 The &acro.z3950; server and search engine.
177 <term><literal>zebraidx</literal></term>
180 The administrative indexing tool.
186 <term><literal>index/*.so</literal></term>
189 The <literal>.so</literal>-files are &zebra; record filter modules.
190 There are modules for reading
191 &acro.marc; (<filename>mod-grs-marc.so</filename>),
192 &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc.
202 Using configure option <literal>--disable-shared</literal> builds
203 &zebra; statically and links "in" &zebra; filter code statically, i.e.
204 no <literal>.so-files</literal> are generated
209 You can now use &zebra;. If you wish to install it system-wide, then
214 By default this will install the &zebra; executables in
215 <filename>/usr/local/bin</filename>,
216 and the standard configuration files in
217 <filename>/usr/local/share/idzebra-2.0</filename>. If
218 shared modules are built, these are installed in
219 <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
220 You can override this with the <literal>--prefix</literal> option
225 <section id="installation-debian"><title>GNU/Debian</title>
226 <section id="installation-debian-linux"><title>GNU/Debian Linux on
227 amd64/i386 Platform</title>
229 Index Data provides pre-compiled GNU/Debian and Ubuntu packages
230 at our Debian package archive, both for recent releases.
235 <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/README"/>
236 for how to configure APT. For Ubuntu, refer to
237 <ulink url="http://ftp.indexdata.dk/pub/zebra/ubuntu/README"/>.
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>GNU/Debian and Ubuntu on other architectures</title>
254 These <ulink url="&url.idzebra;">&zebra;</ulink>
255 packages are specifically compiled for
256 GNU/Debian Linux systems and Ubuntu. 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 After refreshing the package cache with the command
264 apt-get build-dep idzebra-2.0
266 as <literal>root</literal>, the
267 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
268 recompiled and installed issuing
270 fakeroot apt-get source --compile idzebra-2.0
273 The compiled GNU/Debian packages can then be
274 installed as <literal>root</literal> issuing
276 dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
282 <section id="installation-win32"><title>WIN32</title>
283 <para>The easiest way to install &zebra; on Windows is by downloading
285 <ulink url="&url.idzebra.download.win32;">here</ulink>.
286 The installer comes with source too - in case you wish to
287 compile &zebra; with different Compiler options.
291 &zebra; is shipped with "makefiles" for the NMAKE tool that comes
292 with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
293 Version 2003, 2005 and 2008 has been tested.
296 Start a command prompt and switch the sub directory
297 <filename>WIN</filename> where the file <filename>makefile</filename>
298 is located. Customize the installation by editing the
299 <filename>makefile</filename> file (for example by using notepad).
301 The following summarizes the most important settings in that file:
304 <varlistentry><term><literal>DEBUG</literal></term>
306 If set to 1, the software is
307 compiled with debugging libraries (code generation is
308 multi-threaded debug DLL).
309 If set to 0, the software is compiled with release libraries
310 (code generation is multi-threaded DLL).
315 <term><literal>YAZDIR</literal></term>
317 Directory of &yaz; source. &zebra;'s makefile expects to find
318 YAZ<filename>.lib</filename>, YAZ<filename>.dll</filename>
319 in <replaceable>yazdir</replaceable><literal>/lib</literal> and
320 <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
326 <term><literal>HAVE_EXPAT</literal>,
327 <literal>EXPAT_DIR</literal></term>
329 If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
330 with <ulink url="&url.expat;">Expat</ulink> support.
331 In this configuration, set
332 <literal>ZEBRA_DIR</literal> to the Expat source directory.
333 Windows version of Expat can be downloaded from
334 <ulink url="&url.expat;">SourceForge</ulink>.
339 <term><literal>HAVE_ICONV</literal>,
340 <literal>ICONV_DIR</literal></term>
342 If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
343 with iconv support. In this configuration, set
344 <literal>ICONV_DIR</literal> to the iconv source directory.
345 Iconv binaries can be downloaded from
346 <ulink url="&url.libxml2.download.win32;">this site</ulink>.
352 <term><literal>BZIP2INCLUDE</literal>,
353 <literal>BZIP2LIB</literal>,
354 <literal>BZIP2DEF</literal>
357 Define these symbols if &zebra; is to be compiled with
358 <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
366 The <literal>DEBUG</literal> setting in the makefile for &zebra; must
367 be set to the same value as <literal>DEBUG</literal> setting in the
369 If not, the &zebra; server/indexer will crash.
373 When satisfied with the settings in the makefile, type
380 If the <filename>nmake</filename> command is not found on your system
381 you probably haven't defined the environment variables required to
382 use that tool. To fix that, find and run the batch file
383 <filename>vcvars32.bat</filename>. You need to run it from within
384 the command prompt or set the environment variables "globally";
385 otherwise it doesn't work.
389 If you wish to recompile &zebra; - for example if you modify
390 settings in the <filename>makefile</filename> you can delete
391 object files, etc by running.
397 The following files are generated upon successful compilation:
400 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
403 </para></listitem></varlistentry>
405 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
408 </para></listitem></varlistentry>
416 <section id="installation-upgrade">
417 <title>Upgrading from &zebra; version 1.3.x</title>
419 &zebra;'s installation directories have changed a bit. In addition,
420 the new loadable modules must be defined in the
421 master <filename>zebra.cfg</filename> configuration file. The old
422 version 1.3.x configuration options
424 # profilePath - where to look for config files
425 profilePath: some/local/path:/usr/share/idzebra/tab
429 # profilePath - where to look for config files
430 profilePath: some/local/path:/usr/share/idzebra-2.0/tab
432 # modulePath - where to look for loadable zebra modules
433 modulePath: /usr/lib/idzebra-2.0/modules
438 The internal binary register structures have changed; all &zebra;
439 databases must be re-indexed after upgrade.
443 The attribute set definition files may no longer contain
444 redirection to other fields.
445 For example the following snippet of
446 a custom <filename>custom/bib1.att</filename>
447 &acro.bib1; attribute set definition file is no
450 att 1016 Any 1016,4,1005,62
452 and should be changed to
458 Similar behaviour can be expressed in the new release by defining
459 a new index <literal>Any:w</literal> in all &acro.grs1;
460 <filename>*.abs</filename> record indexing configuration files.
461 The above example configuration needs to make the changes
462 from version 1.3.x indexing instructions
464 xelm /*/alternative Body-of-text:w,Title:s,Title:w
465 xelm /*/title Body-of-text:w,Title:s,Title:w
467 to version 2.0.0 indexing instructions
469 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
470 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
474 It is also possible to map the numerical attribute value
475 <literal>@attr 1=1016</literal> onto another already existing huge
476 index, in this example, one could for example use the mapping
478 att 1016 Body-of-text
480 with equivalent outcome without editing all &acro.grs1;
481 <filename>*.abs</filename> record indexing configuration files.
485 Server installations which use the special
486 <literal>&acro.idxpath;</literal> attribute set must add the following
487 line to the <filename>zebra.cfg</filename> configuration file:
495 <!-- Keep this comment at the end of the file
500 sgml-minimize-attributes:nil
501 sgml-always-quote-attributes:t
504 sgml-parent-document: "idzebra.xml"
505 sgml-local-catalogs: nil
506 sgml-namecase-general:t