-<chapter id="installation">
- <!-- $Id: installation.xml,v 1.5 2002-10-08 08:09:43 mike Exp $ -->
- <title>Installation</title>
- <para>
- An ANSI C compiler is required to compile the Zebra
- server system — <literal>gcc</literal> works fine if your
- own system doesn't provide an adequate compiler.
- </para>
-
- <para>
- Unpack the distribution archive. The <literal>configure</literal>
- shell script attempts to guess correct values for various
- system-dependent variables used during compilation.
- It uses those values to create a 'Makefile' in each directory of Zebra.
- </para>
-
- <para>
- To run the configure script type:
+<!-- $Id: installation.xml,v 1.28 2006-08-14 19:56:50 adam Exp $ -->
+ <chapter id="installation">
+ <title>Installation</title>
+ <para>
+ Zebra is written in ANSI C and was implemented with portability in mind.
+ We primarily use <ulink url="http://gcc.gnu.org/">GCC</ulink> on UNIX and
+ <ulink url="http://msdn.microsoft.com/vstudio/">
+ Microsoft Visual C++</ulink>
+ on Windows.
+ </para>
- <screen>
- ./configure
- </screen>
-
- </para>
-
- <para>
- The configure script attempts to use C compiler specified by
- the <literal>CC</literal> environment variable.
- If not set, <literal>cc</literal> or GNU C will be used.
- The <literal>CFLAGS</literal> environment variable holds
- options to be passed to the C compiler. If you're using a
- Bourne-shell compatible shell you may pass something like this:
-
- <screen>
- CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
- </screen>
+ <para>
+ The software is regularly tested on
+ <ulink url="http://www.debian.org/">Debian GNU/Linux</ulink>,
+ <ulink url="http://www.redhat.com/">Redhat Linux</ulink>,
+ <ulink url="http://www.gentoo.org/">Gentoo Linux</ulink>,
+ <ulink url="http://www.suse.com/">SuSE Linux</ulink>,
+ <ulink url="http://www.freebsd.org/">FreeBSD (i386)</ulink>,
+ <ulink url="http://www.apple.com/macosx/">MAC OSX</ulink>,
+ <ulink url="http://www.sun.com/software/solaris/">SunOS 5.8
+ (sparc)</ulink>,
+ <ulink url="http://www.microsoft.com/windows2000/">Windows 2000</ulink>.
+ </para>
- The configure script takes a number of arguments, you can see
- them all with
- <screen>
- ./configure --help
- </screen>
+ <para>
+ Zebra can be configured to use the following utilities (most of
+ which are optional):
- </para>
-
- <para>
- When configured, build the software by typing:
-
- <screen>
- make
- </screen>
-
- </para>
-
- <para>
- If successful, two executables are created in the sub-directory
- <literal>index</literal>.
- <variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><ulink url="http://www.indexdata.dk/yaz/">yaz</ulink>
+ (required)</term>
+ <listitem>
+ <para>
+ Zebra uses YAZ to support Z39.50/ <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>. Also the memory management
+ utilites from YAZ is used by Zebra.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://www.gnu.org/software/libiconv/">iconv</ulink>
+ (optional)</term>
+ <listitem>
+ <para>
+ Character set conversion. This is required if you're
+ going to use any other character set than UTF-8 and ISO-8859-1
+ for records. Note that some Unixes has iconv built-in.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><ulink url="http://expat.sourceforge.net/">Expat</ulink>
+ (optional)</term>
+ <listitem>
+ <para>
+ XML parser. If you're going to index real XML you should
+ install this (filter grs.xml). On most systems you should be able
+ to find binary Expat packages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://www.perl.com/">Perl</ulink> (optional)</term>
+ <listitem>
+ <para>
+ Perl is required if you're going to use the Zebra perl
+ filter facility or the Zebra perl API. Perl is preinstalled
+ on many Unixes. We've not tried the Perl extension on
+ Windows ourselves.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://www.tcl.tk/">Tcl</ulink> (optional)</term>
+ <listitem>
+ <para>
+ Tcl is required if you need to use the Tcl record filter
+ for Zebra. You can find binary packages for Tcl for many
+ Unices and Windows.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
+ <ulink url="http://www.gnu.org/software/automake/">Automake</ulink>
+ (optional)</term>
+ <listitem>
+ <para>
+ GNU Automake and Autoconf are only required if you're
+ using the CVS version of Zebra. You do not need these
+ if you have fetched a Zebra tar.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ulink url="http://docbook.org/">Docbook</ulink>
+ and friends (optional)</term>
+ <listitem>
+ <para>
+ These tools are only required if you're writing
+ documentation for Zebra. You need the following
+ Debian packages: jadetex, docbook, docbook-dsssl,
+ docbook-xml, docbook-utils.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <sect1 id="installation.unix"><title>UNIX</title>
+ <para>
+ On Unix, GCC works fine, but any native
+ C compiler should be possible to use as long as it is
+ ANSI C compliant.
+ </para>
+
+ <para>
+ Unpack the distribution archive. The <literal>configure</literal>
+ shell script attempts to guess correct values for various
+ system-dependent variables used during compilation.
+ It uses those values to create a <literal>Makefile</literal> in each
+ directory of Zebra.
+ </para>
+
+ <para>
+ To run the configure script type:
+
+ <screen>
+ ./configure
+ </screen>
+
+ </para>
+
+ <para>
+ The configure script attempts to use C compiler specified by
+ the <literal>CC</literal> environment variable.
+ If this is not set, <literal>cc</literal> or GNU C will be used.
+ The <literal>CFLAGS</literal> environment variable holds
+ options to be passed to the C compiler. If you're using a
+ Bourne-shell compatible shell you may pass something like this:
+
+ <screen>
+ CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
+ </screen>
+ </para>
+ <para>
+ The configure script support various options: you can see what they
+ are with
+ <screen>
+ ./configure --help
+ </screen>
+ </para>
+
+ <para>
+ Once the build environment is configured, build the software by
+ typing:
+ <screen>
+ make
+ </screen>
+ </para>
+
+ <para>
+ If the build is successful, two executables are created in the
+ sub-directory <literal>index</literal>:
+ <variablelist>
+
+ <varlistentry>
+ <term><literal>zebrasrv</literal></term>
+ <listitem>
+ <para>
+ The Z39.50 server and search engine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>zebraidx</literal></term>
+ <listitem>
+ <para>
+ The administrative indexing tool.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
- <varlistentry>
- <term><literal>zebrasrv</literal></term>
- <listitem>
- <para>
- The Z39.50 server and search engine.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>zebraidx</literal></term>
- <listitem>
- <para>
- The administrative indexing tool.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
-
- <para>
- You can now use Zebra. If you wish to install it system-wide, then
- as root type
- <screen>
- make install
- </screen>
- By default this will install the Zebra executables in
- <filename>/usr/local/bin</filename>,
- and the standard configuration files in
- <filename>/usr/local/share/zebra</filename>
- You can override this with the <literal>--prefix</literal> option
- to configure.
- </para>
-</chapter>
+ <para>
+ You can now use Zebra. If you wish to install it system-wide, then
+ as root type
+ <screen>
+ make install
+ </screen>
+ By default this will install the Zebra executables in
+ <filename>/usr/local/bin</filename>,
+ and the standard configuration files in
+ <filename>/usr/local/share/idzebra-2.0</filename>
+ You can override this with the <literal>--prefix</literal> option
+ to configure.
+ </para>
+ </sect1>
+
+ <sect1 id="installation.debian"><title>GNU/Debian</title>
+ <sect2 id="installation.debianlinux"><title>GNU/Debian Linux on
+ i686 Platform</title>
+ <para>
+ Index Data provides pre-compiled GNU/Debian i686 Linux packages
+ at our Debian package archive, both for
+ the Sarge and the Etch release.
+ </para>
+
+ <para>
+ To install these packages, you need to add two lines to your
+ <filename>/etc/apt/sources.list</filename> configuration file,
+ either the Sarge sources found at
+ <screen>
+ deb http://ftp.indexdata.dk/debian sarge main
+ deb-src http://ftp.indexdata.dk/debian sarge main
+ </screen>
+ or the Etch sources from
+ <screen>
+ deb http://ftp.indexdata.dk/debian etch main
+ deb-src http://ftp.indexdata.dk/debian etch main
+ </screen>
+ After refreshing the package cache with the command
+ <screen>
+ apt-get update
+ </screen>
+ as <literal>root</literal>, the
+ <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
+ easily installed issuing
+ <screen>
+ apt-get install idzebra-2.0 idzebra-2.0-doc
+ </screen>
+ </para>
+ </sect2>
+
+ <sect2 id="installation.debianother">
+ <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
+ <para>
+ These <ulink url="http://indexdata.dk/zebra/">Zebra</ulink>
+ packages are specifically compiled for
+ GNU/Debian Linux systems. Installation on other
+ GNU/Debian systems is possible by
+ re-compilation the Debian way: you need to add only the
+ <literal>deb-src</literal> sources lines to the
+ <filename>/etc/apt/sources.list</filename> configuration file,
+ that is either the Sarge sources
+ <screen>
+ deb-src http://ftp.indexdata.dk/debian sarge main
+ </screen>
+ or the Etch sources
+ <screen>
+ deb-src http://ftp.indexdata.dk/debian etch main
+ </screen>
+ After refreshing the package cache with the command
+ <screen>
+ apt-get update
+ apt-get build-dep idzebra-2.0
+ </screen>
+ as <literal>root</literal>, the
+ <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
+ recompiled and installed issuing
+ <screen>
+ apt-get source --compile idzebra-2.0
+ </screen>
+ as normal user.
+ The compiled GNU/Debian packages can then be
+ installed as <literal>root</literal> issuing
+ <screen>
+ dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
+ </screen>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="installation.win32"><title>WIN32</title>
+ <para>The easiest way to install Zebra on Windows is by downloading
+ an installer from
+ <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
+ The installer comes with source too - in case you wish to
+ compile Zebra with different Compiler options.
+ </para>
+
+ <para>
+ Zebra is shipped with "makefiles" for the NMAKE tool that comes
+ with <ulink url="http://msdn.microsoft.com/vstudio/">
+ Microsoft Visual C++</ulink>.
+ Version 6 has been tested. We expect that zebra compiles
+ with version 5 as well.
+ </para>
+ <para>
+ Start a command prompt and switch the sub directory
+ <filename>WIN</filename> where the file <filename>makefile</filename>
+ is located. Customize the installation by editing the
+ <filename>makefile</filename> file (for example by using notepad).
+
+ The following summarizes the most important settings in that file:
+
+ <variablelist>
+ <varlistentry><term><literal>DEBUG</literal></term>
+ <listitem><para>
+ If set to 1, the software is
+ compiled with debugging libraries (code generation is
+ multi-threaded debug DLL).
+ If set to 0, the software is compiled with release libraries
+ (code generation is multi-threaded DLL).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>YAZDIR</literal></term>
+ <listitem><para>
+ Directory of YAZ source. Zebra's makefile expects to find
+ <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
+ in <replaceable>yazdir</replaceable><literal>/lib</literal> and
+ <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>HAVE_EXPAT</literal>,
+ <literal>EXPAT_DIR</literal></term>
+ <listitem><para>
+ If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
+ with <ulink url="http://expat.sourceforge.net/">Expat</ulink> support. In this configuration, set
+ <literal>ZEBRA_DIR</literal> to the <ulink url="http://expat.sourceforge.net/">Expat</ulink> source directory.
+ Windows version of Expat can be downloaded from
+ <ulink url="http://sourceforge.net/projects/expat/">
+ SourceForge
+ </ulink>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>HAVE_ICONV</literal>,
+ <literal>ICONV_DIR</literal></term>
+ <listitem><para>
+ If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
+ with iconv support. In this configuration, set
+ <literal>ICONV_DIR</literal> to the iconv source directory.
+ Iconv binaries can be downloaded from
+ <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
+ this site
+ </ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>BZIP2INCLUDE</literal>,
+ <literal>BZIP2LIB</literal>,
+ <literal>BZIP2DEF</literal>
+ </term>
+ <listitem><para>
+ Define these symbols if Zebra is to be compiled with
+ <ulink url="http://sources.redhat.com/bzip2/">BZIP2</ulink>
+ record compression support.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <warning>
+ <para>
+ The <literal>DEBUG</literal> setting in the makefile for Zebra must
+ be set to the same value as <literal>DEBUG</literal> setting in the
+ makefile for YAZ.
+ If not, the Zebra server/indexer will crash.
+ </para>
+ </warning>
+ <para>
+ When satisfied with the settings in the makefile, type
+ <screen>
+ nmake
+ </screen>
+ </para>
+ <note>
+ <para>
+ If the <filename>nmake</filename> command is not found on your system
+ you probably haven't defined the environment variables required to
+ use that tool. To fix that, find and run the batch file
+ <filename>vcvars32.bat</filename>. You need to run it from within
+ the command prompt or set the environment variables "globally";
+ otherwise it doesn't work.
+ </para>
+ </note>
+ <para>
+ If you wish to recompile Zebra - for example if you modify
+ settings in the <filename>makefile</filename> you can delete
+ object files, etc by running.
+ <screen>
+ nmake clean
+ </screen>
+ </para>
+ <para>
+ The following files are generated upon successful compilation:
+
+ <variablelist>
+ <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
+ <listitem><para>
+ The Zebra indexer.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
+ <listitem><para>
+ The Zebra server.
+ </para></listitem></varlistentry>
+
+ </variablelist>
+
+ </para>
+ </sect1>
+
+
+ <sect1 id="installation-upgrade">
+ <title>Upgrading from Zebra version 1.3.x</title>
+ <para>
+ Zebra's installation directories have changed a bit. In addition,
+ the new loadable modules must be defined in the
+ master <filename>zebra.cfg</filename> configuration file. The old
+ version 1.3.x configuration options
+ <screen>
+ # profilePath - where to look for config files
+ profilePath: some/local/path:/usr/share/idzebra/tab
+ </screen>
+ must be changed to
+ <screen>
+ # profilePath - where to look for config files
+ profilePath: some/local/path:/usr/share/idzebra-2.0/tab
+
+ # modulePath - where to look for loadable zebra modules
+ modulePath: /usr/lib/idzebra-2.0/
+ </screen>
+ </para>
+ <para>
+ The internal binary register structures have changed; all Zebra
+ databases must be re-indexed after upgrade.
+ </para>
+ <para>
+ The attribute set defintion files may no longer contain
+ redirection to other fields.
+ For example the following snippet of
+ a custom <filename>custom/bib1.att</filename>
+ Bib-1 attribute set definition file is no
+ longer supported:
+ <screen>
+ att 1016 Any 1016,4,1005,62
+ </screen>
+ and should be changed to
+ <screen>
+ att 1016 Any
+ </screen>
+ </para>
+ <para>
+ Similar behaviour can be expressed in the new release by defining
+ a new index <literal>Any:w</literal> in all GRS
+ <filename>*.abs</filename> record indexing configuration files.
+ The above example configuration needs to make the changes
+ from version 1.3.x indexing instructions
+ <screen>
+ xelm /*/alternative Body-of-text:w,Title:s,Title:w
+ xelm /*/title Body-of-text:w,Title:s,Title:w
+ </screen>
+ to version 2.0.0 indexing instructions
+ <screen>
+ xelm /*/alternative Any:w,Body-of-text:w,Title:s,Title:w
+ xelm /*/title Any:w,Body-of-text:w,Title:s,Title:w
+ </screen>
+ </para>
+ <para>
+ It is also possible to map the numerical attribute value
+ <literal>@attr 1=1016</literal> onto another already existing huge
+ index, in this example, one could for example use the mapping
+ <screen>
+ att 1016 Body-of-text
+ </screen>
+ with equivalent outcome without editing all GRS
+ <filename>*.abs</filename> record indexing configuration files.
+ </para>
+
+ <para>
+ Server installations which use the special
+ <literal>IDXPATH</literal> attribute set must add the following
+ line to the <filename>zebra.cfg</filename> configuration file:
+ <screen>
+ attset: idxpath.att
+ </screen>
+ </para>
+ </sect1>
+
+ </chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml