1 <!-- $Id: installation.xml,v 1.24 2006-06-27 13:42:20 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="http://gcc.gnu.org/">GCC</ulink> on UNIX and
7 <ulink url="http://msdn.microsoft.com/vstudio/">
8 Microsoft Visual C++</ulink>
13 The software is regularly tested on
14 <ulink url="http://www.debian.org/">Debian GNU/Linux</ulink>,
15 <ulink url="http://www.redhat.com/">Redhat Linux</ulink>,
16 <ulink url="http://www.gentoo.org/">Gentoo Linux</ulink>,
17 <ulink url="http://www.suse.com/">SuSE Linux</ulink>,
18 <ulink url="http://www.freebsd.org/">FreeBSD (i386)</ulink>,
19 <ulink url="http://www.apple.com/macosx/">MAC OSX</ulink>,
20 <ulink url="http://www.sun.com/software/solaris/">SunOS 5.8
22 <ulink url="http://www.microsoft.com/windows2000/">Windows 2000</ulink>.
26 Zebra can be configured to use the following utilities (most of
31 <term><ulink url="http://www.indexdata.dk/yaz/">yaz</ulink>
35 Zebra uses YAZ to support Z39.50/ <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>. Also the memory management
36 utilites from YAZ is used by Zebra.
41 <term><ulink url="http://www.gnu.org/software/libiconv/">iconv</ulink>
45 Character set conversion. This is required if you're
46 going to use any other character set than UTF-8 and ISO-8859-1
47 for records. Note that some Unixes has iconv built-in.
52 <term><ulink url="http://expat.sourceforge.net/">Expat</ulink>
56 XML parser. If you're going to index real XML you should
57 install this (filter grs.xml). On most systems you should be able
58 to find binary Expat packages.
64 <term><ulink url="http://www.perl.com/">Perl</ulink> (optional)</term>
67 Perl is required if you're going to use the Zebra perl
68 filter facility or the Zebra perl API. Perl is preinstalled
69 on many Unixes. We've not tried the Perl extension on
76 <term><ulink url="http://www.tcl.tk/">Tcl</ulink> (optional)</term>
79 Tcl is required if you need to use the Tcl record filter
80 for Zebra. You can find binary packages for Tcl for many
88 <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
89 <ulink url="http://www.gnu.org/software/automake/">Automake</ulink>
93 GNU Automake and Autoconf are only required if you're
94 using the CVS version of Zebra. You do not need these
95 if you have fetched a Zebra tar.
101 <term><ulink url="http://docbook.org/">Docbook</ulink>
102 and friends (optional)</term>
105 These tools are only required if you're writing
106 documentation for Zebra. You need the following
107 Debian packages: jadetex, docbook, docbook-dsssl,
108 docbook-xml, docbook-utils.
115 <sect1 id="installation.unix"><title>UNIX</title>
117 On Unix, <literal>gcc</literal> works fine, but any native
118 C compiler should be possible to use as long as it is
123 Unpack the distribution archive. The <literal>configure</literal>
124 shell script attempts to guess correct values for various
125 system-dependent variables used during compilation.
126 It uses those values to create a <literal>Makefile</literal> in each
131 To run the configure script type:
140 The configure script attempts to use C compiler specified by
141 the <literal>CC</literal> environment variable.
142 If this is not set, <literal>cc</literal> or GNU C will be used.
143 The <literal>CFLAGS</literal> environment variable holds
144 options to be passed to the C compiler. If you're using a
145 Bourne-shell compatible shell you may pass something like this:
148 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
152 The configure script support various options: you can see what they
160 Once the build environment is configured, build the software by
168 If the build is successful, two executables are created in the
169 sub-directory <literal>index</literal>:
173 <term><literal>zebrasrv</literal></term>
176 The Z39.50 server and search engine.
181 <term><literal>zebraidx</literal></term>
184 The administrative indexing tool.
192 You can now use Zebra. If you wish to install it system-wide, then
197 By default this will install the Zebra executables in
198 <filename>/usr/local/bin</filename>,
199 and the standard configuration files in
200 <filename>/usr/local/share/idzebra</filename>
201 You can override this with the <literal>--prefix</literal> option
206 <sect1 id="installation.debian"><title>GNU/Debian</title>
207 <sect2 id="installation.debianlinux"><title>GNU/Debian Linux on
208 i686 Platform</title>
210 Index Data provides pre-compiled <literal>GNU/Debian i686
211 Linux</literal> packages at our Debian package archive, both for
212 the <literal>Sarge</literal> and the <literal>Etch</literal> release.
216 To install these packages, you need to add two lines to your
217 <literal>/etc/apt/sources.list</literal> configuration file,
218 either the <literal>Sarge</literal> sources found at
220 deb http://ftp.indexdata.dk/t/debian sarge main
221 deb-src http://ftp.indexdata.dk/t/debian sarge main
223 or the <literal>Etch</literal> sources from
225 deb http://ftp.indexdata.dk/t/debian etch main
226 deb-src http://ftp.indexdata.dk/t/debian etch main
228 After refreshing the package cache with the command
232 as <literal>root</literal>, the
233 <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
234 easily installed issuing
236 apt-get install idzebra idzebra-doc
241 <sect2 id="installation.debianother">
242 <title>GNU/Debian On Other Platforms</title>
244 These <ulink url="http://indexdata.dk/zebra/">Zebra</ulink>
245 packages are specifically compiled for
246 <literal>GNU/Debian Linux</literal> systems. Installation on other
247 <literal>GNU/Debian</literal> systems is possible by
248 re-compilation the Debian way: you need to add only the
249 <literal>deb-src</literal> sources lines to the
250 <literal>/etc/apt/sources.list</literal> configuration file,
251 that is either the <literal>Sarge</literal> sources
253 deb-src http://ftp.indexdata.dk/t/debian sarge main
255 or the <literal>Etch</literal> sources
257 deb-src http://ftp.indexdata.dk/t/debian etch main
259 After refreshing the package cache with the command
263 as <literal>root</literal>, the
264 <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
265 recompiled and installed issuing
267 apt-get build-dep idzebra
268 apt-get source --compile idzebra
271 The compiled <literal>GNU/Debian</literal> packages can then be
272 installed as <literal>root</literal> issuing
274 dpkg -i install idzebra*.deb idzebra-doc*.deb
280 <sect1 id="installation.win32"><title>WIN32</title>
281 <para>The easiest way to install Zebra on Windows is by downloading
283 <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
284 The installer comes with source too - in case you wish to
285 compile Zebra with different Compiler options.
289 Zebra is shipped with "makefiles" for the NMAKE tool that comes
290 with <ulink url="http://msdn.microsoft.com/vstudio/">
291 Microsoft Visual C++</ulink>.
292 Version 6 has been tested. We expect that zebra compiles
293 with version 5 as well.
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 <filename>yaz.lib</filename>, <filename>yaz.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="http://expat.sourceforge.net/">Expat</ulink> support. In this configuration, set
331 <literal>ZEBRA_DIR</literal> to the <ulink url="http://expat.sourceforge.net/">Expat</ulink> source directory.
332 Windows version of Expat can be downloaded from
333 <ulink url="http://sourceforge.net/projects/expat/">
340 <term><literal>HAVE_ICONV</literal>,
341 <literal>ICONV_DIR</literal></term>
343 If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
344 with iconv support. In this configuration, set
345 <literal>ICONV_DIR</literal> to the iconv source directory.
346 Iconv binaries can be downloaded from
347 <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
355 <term><literal>BZIP2INCLUDE</literal>,
356 <literal>BZIP2LIB</literal>,
357 <literal>BZIP2DEF</literal>
360 Define these symbols if Zebra is to be compiled with
361 <ulink url="http://sources.redhat.com/bzip2/">BZIP2</ulink>
362 record compression support.
370 The <literal>DEBUG</literal> setting in the makefile for Zebra must
371 be set to the same value as <literal>DEBUG</literal> setting in the
373 If not, the Zebra server/indexer will crash.
377 When satisfied with the settings in the makefile, type
384 If the <filename>nmake</filename> command is not found on your system
385 you probably haven't defined the environment variables required to
386 use that tool. To fix that, find and run the batch file
387 <filename>vcvars32.bat</filename>. You need to run it from within
388 the command prompt or set the environment variables "globally";
389 otherwise it doesn't work.
393 If you wish to recompile Zebra - for example if you modify
394 settings in the <filename>makefile</filename> you can delete
395 object files, etc by running.
401 The following files are generated upon successful compilation:
404 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
407 </para></listitem></varlistentry>
409 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
412 </para></listitem></varlistentry>
420 <sect1 id="installation-upgrade">
421 <title>Upgrading from Zebra version 1.3.x</title>
423 Zebra's installation directories have changed a bit. In addition,
424 the new loadable modules must be defined in the
425 master <filename>zebra.cfg</filename> configuration file. The old
426 version 1.3.x configuration options
428 # profilePath - where to look for config files
429 profilePath: some/local/path:/usr/share/idzebra/tab
433 # profilePath - where to look for config files
434 profilePath: some/local/path:/usr/share/idzebra2.0/tab
436 # modulePath - where to look for loadable zebra modules
437 modulePath: /usr/lib/idzebra2.0/
441 The internal binary register structures have changed; all Zebra
442 databases must be re-indexed after upgrade.
445 The attribute set defintion files may no longer contain
446 redirection to other fields.
447 For example the following snippet of
448 a custom <filename>custom/bib1.att</filename>
449 <literal>Bib-1</literal> attribute set definition file is no
452 att 1016 Any 1016,4,1005,62
454 and should be changed to
460 Similar behaviour can be expressed in the new release by defining
461 a new index <literal>Any:w</literal> in all GRS
462 <filename>*.abs</filename> record indexing configuration files.
463 The above example configuration needs to make the changes
464 from version 1.3.x indexing instructions
466 xelm /*/alternative Body-of-text:w,Title:s,Title:w
467 xelm /*/title Body-of-text:w,Title:s,Title:w
469 to version 2.0.0 indexing instructions
471 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
472 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
476 It is also possible to map the numerical attribute value
477 <literal>@attr 1=1016</literal> onto another already existing huge
478 index, in this example, one could for example use the mapping
480 att 1016 Body-of-text
482 with equivalent outcome without editing all GRS
483 <filename>*.abs</filename> record indexing configuration files.
487 Server installations which use the special
488 <literal>IDXPATH</literal> attribute set must add the following
489 line to the <filename>zebra.cfg</filename> configuration file:
497 <!-- Keep this comment at the end of the file
502 sgml-minimize-attributes:nil
503 sgml-always-quote-attributes:t
506 sgml-parent-document: "zebra.xml"
507 sgml-local-catalogs: nil
508 sgml-namecase-general:t