doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.13 2003-03-31 20:57:29 adam Exp $ -->
   2  <chapter id="installation">
   3   <title>Installation</title>
   4   <para>
   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>
   9    on Windows.
  10   </para>
  11
  12   <para>
  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.netbsd.org/Ports/cobalt/">NetBSD (Cobalt)</ulink>,
  19    <ulink url="http://www.freebsd.org/">FreeBSD (i386)</ulink>,
  20    <ulink url="http://www.apple.com/macosx/">MAC OSX</ulink>,
  21    <ulink url="http://wwws.sun.com/software/solaris/">SunOS 5.8
  22     (sparc)</ulink>,
  23    <ulink url="http://www.microsoft.com/windows2000/">Windows 2000 SP3</ulink>.
  24   </para>
  25
  26   <para>
  27    Zebra can be configured to use the following utilities (most of
  28    which are optional):
  29
  30    <variablelist>
  31     <varlistentry>
  32      <term><ulink url="http://www.indexdata.dk/yaz/">yaz</ulink>
  33       (required)</term>
  34      <listitem>
  35       <para>
  36        Zebra uses YAZ to support Z39.50/SRW. Also the memory management
  37        utilites from YAZ is used by Zebra.
  38       </para>
  39      </listitem>
  40     </varlistentry>
  41     <varlistentry>
  42      <term><ulink url="http://www.gnu.org/software/libiconv/">iconv</ulink>
  43       (optional)</term>
  44      <listitem>
  45       <para>
  46        Character set conversion. This is required if you're
  47        going to use any other character set than UTF-8 and ISO-8859-1
  48        for records. Note that some Unixes has iconv built-in.
  49       </para>
  50      </listitem>
  51     </varlistentry>
  52     <varlistentry>
  53      <term><ulink url="http://expat.sourceforge.net/">Expat</ulink>
  54       (optional)</term>
  55      <listitem>
  56       <para>
  57        XML parser. If you're going to index real XML you should
  58        install this (filter grs.xml). On most systems you should be able
  59        to find binary Expat packages.
  60       </para>
  61      </listitem>
  62     </varlistentry>
  63
  64     <varlistentry>
  65      <term><ulink url="http://www.perl.com/">Perl</ulink> (optional)</term>
  66      <listitem>
  67       <para>
  68        Perl is required if you're going to use the Zebra perl
  69        filter facility or the Zebra perl API. Perl is preinstalled
  70        on many Unixes. We've not tried the Perl extension on
  71        Windows ourselves.
  72       </para>
  73      </listitem>
  74     </varlistentry>
  75
  76     <varlistentry>
  77      <term><ulink url="http://www.tcl.tk/">Tcl</ulink> (optional)</term>
  78      <listitem>
  79       <para>
  80        Tcl is required if you  need to use the Tcl record filter
  81        for Zebra. You can find binary packages for Tcl for many
  82        Unices and Windows.
  83       </para>
  84      </listitem>
  85     </varlistentry>
  86
  87     <varlistentry>
  88      <term>
  89       <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
  90       <ulink url="http://www.gnu.org/software/automake/">Automake</ulink>
  91       (optional)</term>
  92      <listitem>
  93       <para>
  94        GNU Automake and Autoconf are only required if you're
  95        using the CVS version of Zebra. You do not need these
  96        if you have fetched a Zebra tar.
  97       </para>
  98      </listitem>
  99     </varlistentry>
 100
 101     <varlistentry>
 102      <term><ulink url="http://docbook.org/">Docbook</ulink>
 103       and friends (optional)</term>
 104      <listitem>
 105       <para>
 106        These tools are only required if you're writing
 107        documentation for Zebra. You need the following
 108        Debian packages: jadetex, docbook, docbook-dsssl,
 109        docbook-xml, docbook-utils.
 110       </para>
 111      </listitem>
 112     </varlistentry>
 113    </variablelist>
 114   </para>
 115
 116   <sect1 id="installation.unix"><title>UNIX</title>
 117    <para>
 118     On Unix, <literal>gcc</literal> works fine, but any native
 119     C compiler should be possible to use as long as it is
 120     ANSI C compliant.
 121    </para>
 122
 123    <para>
 124     Unpack the distribution archive. The <literal>configure</literal>
 125     shell script attempts to guess correct values for various
 126     system-dependent variables used during compilation.
 127     It uses those values to create a <literal>Makefile</literal> in each
 128     directory of Zebra.
 129    </para>
 130
 131    <para>
 132     To run the configure script type:
 133
 134     <screen>
 135      ./configure
 136     </screen>
 137
 138    </para>
 139
 140    <para>
 141     The configure script attempts to use C compiler specified by
 142     the <literal>CC</literal> environment variable.
 143     If this is not set, <literal>cc</literal> or GNU C will be used.
 144     The <literal>CFLAGS</literal> environment variable holds
 145     options to be passed to the C compiler. If you're using a
 146     Bourne-shell compatible shell you may pass something like this:
 147
 148     <screen>
 149      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
 150     </screen>
 151    </para>
 152    <para>
 153     The configure script support various options: you can see what they
 154     are with
 155     <screen>
 156      ./configure --help
 157     </screen>
 158    </para>
 159
 160    <para>
 161     Once the build environment is configured, build the software by
 162     typing:
 163     <screen>
 164      make
 165     </screen>
 166    </para>
 167
 168    <para>
 169     If the build is successful, two executables are created in the
 170     sub-directory <literal>index</literal>:
 171     <variablelist>
 172
 173      <varlistentry>
 174       <term><literal>zebrasrv</literal></term>
 175       <listitem>
 176        <para>
 177         The Z39.50 server and search engine.
 178        </para>
 179       </listitem>
 180      </varlistentry>
 181      <varlistentry>
 182      <term><literal>zebraidx</literal></term>
 183       <listitem>
 184        <para>
 185         The administrative indexing tool.
 186        </para>
 187       </listitem>
 188      </varlistentry>
 189     </variablelist>
 190    </para>
 191
 192    <para>
 193     You can now use Zebra. If you wish to install it system-wide, then
 194     as root type
 195     <screen>
 196      make install
 197     </screen>
 198     By default this will install the Zebra executables in
 199     <filename>/usr/local/bin</filename>,
 200     and the standard configuration files in
 201     <filename>/usr/local/share/idzebra</filename>
 202     You can override this with the <literal>--prefix</literal> option
 203     to configure.
 204    </para>
 205   </sect1>
 206   <sect1 id="installation.win32"><title>WIN32</title>
 207    <para>The easiest way to install Zebra on Windows is by downloading
 208     an installer from
 209     <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
 210     The installer comes with source too - in case you wish to
 211     compile Zebra with different Compiler options.
 212    </para>
 213
 214    <para>
 215     Zebra is shipped with "makefiles" for the NMAKE tool that comes
 216     with <ulink url="http://msdn.microsoft.com/vstudio/">
 217      Microsoft Visual C++</ulink>.
 218     Version 6 has been tested. We expect that zebra compiles
 219     with version 5 as well.
 220    </para>
 221    <para>
 222     Start a command prompt and switch the sub directory
 223     <filename>WIN</filename> where the file <filename>makefile</filename>
 224     is located. Customize the installation by editing the
 225     <filename>makefile</filename> file (for example by using notepad).
 226
 227     The following summarizes the most important settings in that file:
 228
 229     <variablelist>
 230      <varlistentry><term><literal>DEBUG</literal></term>
 231       <listitem><para>
 232         If set to 1, the software is
 233         compiled with debugging libraries (code generation is
 234         multi-threaded debug DLL).
 235         If set to 0, the software is compiled with release libraries
 236         (code generation is multi-threaded DLL).
 237        </para></listitem>
 238      </varlistentry>
 239
 240      <varlistentry>
 241       <term><literal>YAZDIR</literal></term>
 242       <listitem><para>
 243         Directory of YAZ source. Zebra's makefile expects to find
 244         <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
 245         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
 246         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
 247        </para>
 248       </listitem>
 249      </varlistentry>
 250
 251      <varlistentry>
 252       <term><literal>HAVE_EXPAT</literal>,
 253        <literal>EXPAT_DIR</literal></term>
 254       <listitem><para>
 255         If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
 256         with Expat support. In this configuration, set
 257         <literal>ZEBRA_DIR</literal> to the Expat source directory.
 258        </para></listitem>
 259      </varlistentry>
 260
 261      <varlistentry>
 262       <term><literal>HAVE_ICONV</literal>,
 263        <literal>ICONV_DIR</literal></term>
 264        <listitem><para>
 265         If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
 266         with iconv support. In this configuration, set
 267         <literal>ICONV_DIR</literal> to the iconv source directory.
 268
 269         iconv binaries can be downloaded from
 270         <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
 271          this site</ulink>.
 272         </para>
 273       </listitem>
 274      </varlistentry>
 275
 276      <varlistentry>
 277       <term><literal>BZIP2INCLUDE</literal>,
 278        <literal>BZIP2LIB</literal>,
 279        <literal>BZIP2DEF</literal>
 280       </term>
 281       <listitem><para>
 282         Define these symbols if Zebra is to be compiled with
 283         BZIP2 record compression support.
 284        </para></listitem>
 285      </varlistentry>
 286
 287     </variablelist>
 288    </para>
 289    <warning>
 290     <para>
 291      The <literal>DEBUG</literal> setting in the makefile for Zebra must
 292      be set to the same value as <literal>DEBUG</literal> setting in the
 293      makefile for YAZ.
 294      If not, the Zebra server/indexer will crash.
 295     </para>
 296    </warning>
 297    <para>
 298     When satisfied with the settings in the makefile, type
 299     <screen>
 300      nmake
 301     </screen>
 302    </para>
 303    <note>
 304     <para>
 305      If the <filename>nmake</filename> command is not found on your system
 306      you probably haven't defined the environment variables required to
 307      use that tool. To fix that, find and run the batch file
 308      <filename>vcvars32.bat</filename>. You need to run it from within
 309      the command prompt or set the environment variables "globally";
 310      otherwise it doesn't work.
 311     </para>
 312    </note>
 313    <para>
 314     If you wish to recompile Zebra - for example if you modify
 315      settings in the <filename>makefile</filename> you can delete
 316     object files, etc by running.
 317     <screen>
 318      nmake clean
 319     </screen>
 320    </para>
 321    <para>
 322     The following files are generated upon successful compilation:
 323
 324     <variablelist>
 325      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 326       <listitem><para>
 327         The Zebra indexer.
 328        </para></listitem></varlistentry>
 329
 330      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 331       <listitem><para>
 332         The Zebra server.
 333        </para></listitem></varlistentry>
 334
 335     </variablelist>
 336
 337    </para>
 338   </sect1>
 339  </chapter>
 340  <!-- Keep this comment at the end of the file
 341  Local variables:
 342  mode: sgml
 343  sgml-omittag:t
 344  sgml-shorttag:t
 345  sgml-minimize-attributes:nil
 346  sgml-always-quote-attributes:t
 347  sgml-indent-step:1
 348  sgml-indent-data:t
 349  sgml-parent-document: "zebra.xml"
 350  sgml-local-catalogs: nil
 351  sgml-namecase-general:t
 352  End:
 353  -->