doc/installation.xml

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