1 <!-- $Id: installation.xml,v 1.29 2006-09-03 21:37:26 adam 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.8
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: jadetex, docbook, docbook-dsssl,
95 docbook-xml, docbook-utils.
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
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.
179 You can now use Zebra. If you wish to install it system-wide, then
184 By default this will install the Zebra executables in
185 <filename>/usr/local/bin</filename>,
186 and the standard configuration files in
187 <filename>/usr/local/share/idzebra-2.0</filename>
188 You can override this with the <literal>--prefix</literal> option
193 <section id="installation-debian"><title>GNU/Debian</title>
194 <section id="installation-debian-linux"><title>GNU/Debian Linux on
195 i686 Platform</title>
197 Index Data provides pre-compiled GNU/Debian i686 Linux packages
198 at our Debian package archive, both for
199 the Sarge and the Etch release.
203 To install these packages, you need to add two lines to your
204 <filename>/etc/apt/sources.list</filename> configuration file,
205 either the Sarge sources found at
207 deb http://ftp.indexdata.dk/debian sarge main
208 deb-src http://ftp.indexdata.dk/debian sarge main
210 or the Etch sources from
212 deb http://ftp.indexdata.dk/debian etch main
213 deb-src http://ftp.indexdata.dk/debian etch main
215 After refreshing the package cache with the command
219 as <literal>root</literal>, the
220 <ulink url="&url.idzebra;">Zebra</ulink> indexer is
221 easily installed issuing
223 apt-get install idzebra-2.0 idzebra-2.0-doc
228 <section id="installation-debia-nother">
229 <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
231 These <ulink url="&url.idzebra;">Zebra</ulink>
232 packages are specifically compiled for
233 GNU/Debian Linux systems. Installation on other
234 GNU/Debian systems is possible by
235 re-compilation the Debian way: you need to add only the
236 <literal>deb-src</literal> sources lines to the
237 <filename>/etc/apt/sources.list</filename> configuration file,
238 that is either the Sarge sources
240 deb-src http://ftp.indexdata.dk/debian sarge main
244 deb-src http://ftp.indexdata.dk/debian etch main
246 After refreshing the package cache with the command
249 apt-get build-dep idzebra-2.0
251 as <literal>root</literal>, the
252 <ulink url="&url.idzebra;">Zebra</ulink> indexer is
253 recompiled and installed issuing
255 apt-get source --compile idzebra-2.0
258 The compiled GNU/Debian packages can then be
259 installed as <literal>root</literal> issuing
261 dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
267 <section id="installation-win32"><title>WIN32</title>
268 <para>The easiest way to install Zebra on Windows is by downloading
270 <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
271 The installer comes with source too - in case you wish to
272 compile Zebra with different Compiler options.
276 Zebra is shipped with "makefiles" for the NMAKE tool that comes
277 with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
278 Version 2003 and 2005 has been tested. We expect that zebra compiles
279 with version 6 as well.
282 Start a command prompt and switch the sub directory
283 <filename>WIN</filename> where the file <filename>makefile</filename>
284 is located. Customize the installation by editing the
285 <filename>makefile</filename> file (for example by using notepad).
287 The following summarizes the most important settings in that file:
290 <varlistentry><term><literal>DEBUG</literal></term>
292 If set to 1, the software is
293 compiled with debugging libraries (code generation is
294 multi-threaded debug DLL).
295 If set to 0, the software is compiled with release libraries
296 (code generation is multi-threaded DLL).
301 <term><literal>YAZDIR</literal></term>
303 Directory of YAZ source. Zebra's makefile expects to find
304 <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
305 in <replaceable>yazdir</replaceable><literal>/lib</literal> and
306 <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
312 <term><literal>HAVE_EXPAT</literal>,
313 <literal>EXPAT_DIR</literal></term>
315 If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
316 with <ulink url="&url.expat;">Expat</ulink> support.
317 In this configuration, set
318 <literal>ZEBRA_DIR</literal> to the Expat source directory.
319 Windows version of Expat can be downloaded from
320 <ulink url="&url.expat;">SourceForge</ulink>.
325 <term><literal>HAVE_ICONV</literal>,
326 <literal>ICONV_DIR</literal></term>
328 If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
329 with iconv support. In this configuration, set
330 <literal>ICONV_DIR</literal> to the iconv source directory.
331 Iconv binaries can be downloaded from
332 <ulink url="&url.libxml2.download.win32;">this site</ulink>.
338 <term><literal>BZIP2INCLUDE</literal>,
339 <literal>BZIP2LIB</literal>,
340 <literal>BZIP2DEF</literal>
343 Define these symbols if Zebra is to be compiled with
344 <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
352 The <literal>DEBUG</literal> setting in the makefile for Zebra must
353 be set to the same value as <literal>DEBUG</literal> setting in the
355 If not, the Zebra server/indexer will crash.
359 When satisfied with the settings in the makefile, type
366 If the <filename>nmake</filename> command is not found on your system
367 you probably haven't defined the environment variables required to
368 use that tool. To fix that, find and run the batch file
369 <filename>vcvars32.bat</filename>. You need to run it from within
370 the command prompt or set the environment variables "globally";
371 otherwise it doesn't work.
375 If you wish to recompile Zebra - for example if you modify
376 settings in the <filename>makefile</filename> you can delete
377 object files, etc by running.
383 The following files are generated upon successful compilation:
386 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
389 </para></listitem></varlistentry>
391 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
394 </para></listitem></varlistentry>
402 <section id="installation-upgrade">
403 <title>Upgrading from Zebra version 1.3.x</title>
405 Zebra's installation directories have changed a bit. In addition,
406 the new loadable modules must be defined in the
407 master <filename>zebra.cfg</filename> configuration file. The old
408 version 1.3.x configuration options
410 # profilePath - where to look for config files
411 profilePath: some/local/path:/usr/share/idzebra/tab
415 # profilePath - where to look for config files
416 profilePath: some/local/path:/usr/share/idzebra-2.0/tab
418 # modulePath - where to look for loadable zebra modules
419 modulePath: /usr/lib/idzebra-2.0/
423 The internal binary register structures have changed; all Zebra
424 databases must be re-indexed after upgrade.
427 The attribute set defintion files may no longer contain
428 redirection to other fields.
429 For example the following snippet of
430 a custom <filename>custom/bib1.att</filename>
431 Bib-1 attribute set definition file is no
434 att 1016 Any 1016,4,1005,62
436 and should be changed to
442 Similar behaviour can be expressed in the new release by defining
443 a new index <literal>Any:w</literal> in all GRS
444 <filename>*.abs</filename> record indexing configuration files.
445 The above example configuration needs to make the changes
446 from version 1.3.x indexing instructions
448 xelm /*/alternative Body-of-text:w,Title:s,Title:w
449 xelm /*/title Body-of-text:w,Title:s,Title:w
451 to version 2.0.0 indexing instructions
453 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
454 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
458 It is also possible to map the numerical attribute value
459 <literal>@attr 1=1016</literal> onto another already existing huge
460 index, in this example, one could for example use the mapping
462 att 1016 Body-of-text
464 with equivalent outcome without editing all GRS
465 <filename>*.abs</filename> record indexing configuration files.
469 Server installations which use the special
470 <literal>IDXPATH</literal> attribute set must add the following
471 line to the <filename>zebra.cfg</filename> configuration file:
479 <!-- Keep this comment at the end of the file
484 sgml-minimize-attributes:nil
485 sgml-always-quote-attributes:t
488 sgml-parent-document: "zebra.xml"
489 sgml-local-catalogs: nil
490 sgml-namecase-general:t