doc/installation.xml

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