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;">Redhat 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 Also the memory management utilites from &yaz; is used by &zebra;.
39 <term><ulink url="&url.libiconv;">iconv</ulink>
43 Character set conversion. This is required if you're
44 going to use any other character set than UTF-8 and ISO-8859-1
45 for records. Note that some Unixes has iconv built-in.
50 <term><ulink url="&url.expat;">Expat</ulink>
54 &acro.xml; parser. If you're going to index real &acro.xml; you should
55 install this (filter grs.xml). On most systems you should be able
56 to find binary Expat packages.
62 <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
65 Tcl is required if you need to use the Tcl record filter
66 for &zebra;. You can find binary packages for Tcl for many
74 <ulink url="&url.autoconf;">Autoconf</ulink>,
75 <ulink url="&url.automake;">Automake</ulink>
79 GNU Automake and Autoconf are only required if you're
80 using the CVS version of &zebra;. You do not need these
81 if you have fetched a &zebra; tar.
87 <term><ulink url="&url.docbook;">Docbook</ulink>
88 and friends (optional)</term>
91 These tools are only required if you're writing
92 documentation for &zebra;. You need the following
93 Debian packages: docbook, docbook-xml, docbook-xsl,
94 docbook-utils, xsltproc.
101 <section id="installation-unix"><title>UNIX</title>
103 On Unix, GCC works fine, but any native
104 C compiler should be possible to use as long as it is
105 &acro.ansi; C compliant.
109 Unpack the distribution archive. The <literal>configure</literal>
110 shell script attempts to guess correct values for various
111 system-dependent variables used during compilation.
112 It uses those values to create a <literal>Makefile</literal> in each
113 directory of &zebra;.
117 To run the configure script type:
126 The configure script attempts to use C compiler specified by
127 the <literal>CC</literal> environment variable.
128 If this is not set, <literal>cc</literal> or GNU C will be used.
129 The <literal>CFLAGS</literal> environment variable holds
130 options to be passed to the C compiler. If you're using a
131 Bourne-shell compatible shell you may pass something like this:
134 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
138 The configure script support various options: you can see what they
146 Once the build environment is configured, build the software by
154 If the build is successful, two executables are created in the
155 sub-directory <literal>index</literal>:
159 <term><literal>zebrasrv</literal></term>
162 The &acro.z3950; server and search engine.
167 <term><literal>zebraidx</literal></term>
170 The administrative indexing tool.
176 <term><literal>index/*.so</literal></term>
179 The <literal>.so</literal>-files are &zebra; record filter modules.
180 There are modules for reading
181 &acro.marc; (<filename>mod-grs-marc.so</filename>),
182 &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc.
192 Using configure option <literal>--disable-shared</literal> builds
193 &zebra; statically and links "in" &zebra; filter code statically, i.e.
194 no <literal>.so-files</literal> are generated
199 You can now use &zebra;. If you wish to install it system-wide, then
204 By default this will install the &zebra; executables in
205 <filename>/usr/local/bin</filename>,
206 and the standard configuration files in
207 <filename>/usr/local/share/idzebra-2.0</filename>. If
208 shared modules are built, these are installed in
209 <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
210 You can override this with the <literal>--prefix</literal> option
215 <section id="installation-debian"><title>GNU/Debian</title>
216 <section id="installation-debian-linux"><title>GNU/Debian Linux on
217 i686 Platform</title>
219 Index Data provides pre-compiled GNU/Debian i686 Linux packages
220 at our Debian package archive, both for
221 the Sarge and the Etch release.
225 To install these packages, you need to add two lines to your
226 <filename>/etc/apt/sources.list</filename> configuration file,
227 either the Sarge sources found at
229 deb http://ftp.indexdata.dk/debian sarge main
230 deb-src http://ftp.indexdata.dk/debian sarge main
232 or the Etch sources from
234 deb http://ftp.indexdata.dk/debian etch main
235 deb-src http://ftp.indexdata.dk/debian etch main
237 After refreshing the package cache with the command
241 as <literal>root</literal>, the
242 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
243 easily installed issuing
245 apt-get install idzebra-2.0 idzebra-2.0-doc
250 <section id="installation-debia-nother">
251 <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
253 These <ulink url="&url.idzebra;">&zebra;</ulink>
254 packages are specifically compiled for
255 GNU/Debian Linux systems. Installation on other
256 GNU/Debian systems is possible by
257 re-compilation the Debian way: you need to add only the
258 <literal>deb-src</literal> sources lines to the
259 <filename>/etc/apt/sources.list</filename> configuration file,
260 that is either the Sarge sources
262 deb-src http://ftp.indexdata.dk/debian sarge main
266 deb-src http://ftp.indexdata.dk/debian etch main
268 After refreshing the package cache with the command
271 apt-get build-dep idzebra-2.0
273 as <literal>root</literal>, the
274 <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
275 recompiled and installed issuing
277 fakeroot apt-get source --compile idzebra-2.0
280 The compiled GNU/Debian packages can then be
281 installed as <literal>root</literal> issuing
283 dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
289 <section id="installation-win32"><title>WIN32</title>
290 <para>The easiest way to install &zebra; on Windows is by downloading
292 <ulink url="&url.idzebra.download.win32;">here</ulink>.
293 The installer comes with source too - in case you wish to
294 compile &zebra; with different Compiler options.
298 &zebra; is shipped with "makefiles" for the NMAKE tool that comes
299 with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
300 Version 2003 and 2005 has been tested. We expect that zebra compiles
301 with version 6 as well.
304 Start a command prompt and switch the sub directory
305 <filename>WIN</filename> where the file <filename>makefile</filename>
306 is located. Customize the installation by editing the
307 <filename>makefile</filename> file (for example by using notepad).
309 The following summarizes the most important settings in that file:
312 <varlistentry><term><literal>DEBUG</literal></term>
314 If set to 1, the software is
315 compiled with debugging libraries (code generation is
316 multi-threaded debug DLL).
317 If set to 0, the software is compiled with release libraries
318 (code generation is multi-threaded DLL).
323 <term><literal>YAZDIR</literal></term>
325 Directory of &yaz; source. &zebra;'s makefile expects to find
326 <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
327 in <replaceable>yazdir</replaceable><literal>/lib</literal> and
328 <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
334 <term><literal>HAVE_EXPAT</literal>,
335 <literal>EXPAT_DIR</literal></term>
337 If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
338 with <ulink url="&url.expat;">Expat</ulink> support.
339 In this configuration, set
340 <literal>ZEBRA_DIR</literal> to the Expat source directory.
341 Windows version of Expat can be downloaded from
342 <ulink url="&url.expat;">SourceForge</ulink>.
347 <term><literal>HAVE_ICONV</literal>,
348 <literal>ICONV_DIR</literal></term>
350 If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
351 with iconv support. In this configuration, set
352 <literal>ICONV_DIR</literal> to the iconv source directory.
353 Iconv binaries can be downloaded from
354 <ulink url="&url.libxml2.download.win32;">this site</ulink>.
360 <term><literal>BZIP2INCLUDE</literal>,
361 <literal>BZIP2LIB</literal>,
362 <literal>BZIP2DEF</literal>
365 Define these symbols if &zebra; is to be compiled with
366 <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
374 The <literal>DEBUG</literal> setting in the makefile for &zebra; must
375 be set to the same value as <literal>DEBUG</literal> setting in the
377 If not, the &zebra; server/indexer will crash.
381 When satisfied with the settings in the makefile, type
388 If the <filename>nmake</filename> command is not found on your system
389 you probably haven't defined the environment variables required to
390 use that tool. To fix that, find and run the batch file
391 <filename>vcvars32.bat</filename>. You need to run it from within
392 the command prompt or set the environment variables "globally";
393 otherwise it doesn't work.
397 If you wish to recompile &zebra; - for example if you modify
398 settings in the <filename>makefile</filename> you can delete
399 object files, etc by running.
405 The following files are generated upon successful compilation:
408 <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
411 </para></listitem></varlistentry>
413 <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
416 </para></listitem></varlistentry>
424 <section id="installation-upgrade">
425 <title>Upgrading from &zebra; version 1.3.x</title>
427 &zebra;'s installation directories have changed a bit. In addition,
428 the new loadable modules must be defined in the
429 master <filename>zebra.cfg</filename> configuration file. The old
430 version 1.3.x configuration options
432 # profilePath - where to look for config files
433 profilePath: some/local/path:/usr/share/idzebra/tab
437 # profilePath - where to look for config files
438 profilePath: some/local/path:/usr/share/idzebra-2.0/tab
440 # modulePath - where to look for loadable zebra modules
441 modulePath: /usr/lib/idzebra-2.0/modules
446 The internal binary register structures have changed; all &zebra;
447 databases must be re-indexed after upgrade.
451 The attribute set defintion files may no longer contain
452 redirection to other fields.
453 For example the following snippet of
454 a custom <filename>custom/bib1.att</filename>
455 &acro.bib1; attribute set definition file is no
458 att 1016 Any 1016,4,1005,62
460 and should be changed to
466 Similar behaviour can be expressed in the new release by defining
467 a new index <literal>Any:w</literal> in all &acro.grs1;
468 <filename>*.abs</filename> record indexing configuration files.
469 The above example configuration needs to make the changes
470 from version 1.3.x indexing instructions
472 xelm /*/alternative Body-of-text:w,Title:s,Title:w
473 xelm /*/title Body-of-text:w,Title:s,Title:w
475 to version 2.0.0 indexing instructions
477 xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
478 xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
482 It is also possible to map the numerical attribute value
483 <literal>@attr 1=1016</literal> onto another already existing huge
484 index, in this example, one could for example use the mapping
486 att 1016 Body-of-text
488 with equivalent outcome without editing all &acro.grs1;
489 <filename>*.abs</filename> record indexing configuration files.
493 Server installations which use the special
494 <literal>&acro.idxpath;</literal> attribute set must add the following
495 line to the <filename>zebra.cfg</filename> configuration file:
503 <!-- Keep this comment at the end of the file
508 sgml-minimize-attributes:nil
509 sgml-always-quote-attributes:t
512 sgml-parent-document: "zebra.xml"
513 sgml-local-catalogs: nil
514 sgml-namecase-general:t