doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.16 2006-01-17 12:06:53 marc 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://www.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
 206   <sect1 id="installation.debian"><title>GNU/Debian</title>
 207    <sect2 id="installation.debianlinux"><title>GNU/Debian Linux</title>
 208     <para>
 209      Index Data provides pre-compiled <literal>GNU/Debian
 210       Linux</literal> packages at our Debian package archive, both for
 211      the <literal>Sarge</literal> and the <literal>Etch</literal> release.
 212     </para>
 213
 214     <para>
 215      To install these packages, you need to add two lines to your
 216      <literal>/etc/apt/sources.list</literal> configuration file,
 217      either the <literal>Sarge</literal> sources found at
 218      <screen>
 219       deb http://www.indexdata.dk/debian indexdata/sarge released
 220       deb-src http://www.indexdata.dk/debian indexdata/sarge released
 221      </screen>
 222      or the <literal>Etch</literal> sources from
 223      <screen>
 224       deb http://www.indexdata.dk/debian indexdata/etch released
 225       deb-src http://www.indexdata.dk/debian indexdata/etch released
 226      </screen>
 227      After refreshing the package cache with the command
 228      <screen>
 229       apt-get update
 230      </screen>
 231      as <literal>root</literal>, the
 232      <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
 233      easily installed issuing
 234      <screen>
 235       apt-get install idzebra idzebra-doc
 236      </screen>
 237     </para>
 238    </sect2>
 239
 240    <sect2 id="installation.debianother">
 241     <title>GNU/Debian On Other Platforms</title>
 242     <para>
 243      These <ulink url="http://indexdata.dk/zebra/">Zebra</ulink>
 244      packages are specifically compiled for
 245      <literal>GNU/Debian Linux</literal> systems. Installation on other
 246      <literal>GNU/Debian</literal> systems is possible by
 247      re-compilation the Debian way: you need to add only the
 248      <literal>deb-src</literal> sources lines to the
 249      <literal>/etc/apt/sources.list</literal> configuration file,
 250      that is either the <literal>Sarge</literal> sources
 251      <screen>
 252       deb-src http://www.indexdata.dk/debian indexdata/sarge released
 253      </screen>
 254      or the <literal>Etch</literal> sources
 255      <screen>
 256       deb-src http://www.indexdata.dk/debian indexdata/etch released
 257      </screen>
 258      After refreshing the package cache with the command
 259      <screen>
 260       apt-get update
 261      </screen>
 262      as <literal>root</literal>, the
 263      <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
 264      recompiled and installed issuing
 265      <screen>
 266       apt-get build-dep idzebra
 267       apt-get source --compile idzebra
 268      </screen>
 269      as normal user.
 270      The compiled <literal>GNU/Debian</literal> packages can then be
 271      installed as <literal>root</literal> issuing
 272      <screen>
 273       dpkg -i install idzebra*.deb idzebra-doc*.deb
 274      </screen>
 275     </para>
 276    </sect2>
 277   </sect1>
 278
 279   <sect1 id="installation.win32"><title>WIN32</title>
 280    <para>The easiest way to install Zebra on Windows is by downloading
 281     an installer from
 282     <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
 283     The installer comes with source too - in case you wish to
 284     compile Zebra with different Compiler options.
 285    </para>
 286
 287    <para>
 288     Zebra is shipped with "makefiles" for the NMAKE tool that comes
 289     with <ulink url="http://msdn.microsoft.com/vstudio/">
 290      Microsoft Visual C++</ulink>.
 291     Version 6 has been tested. We expect that zebra compiles
 292     with version 5 as well.
 293    </para>
 294    <para>
 295     Start a command prompt and switch the sub directory
 296     <filename>WIN</filename> where the file <filename>makefile</filename>
 297     is located. Customize the installation by editing the
 298     <filename>makefile</filename> file (for example by using notepad).
 299
 300     The following summarizes the most important settings in that file:
 301
 302     <variablelist>
 303      <varlistentry><term><literal>DEBUG</literal></term>
 304       <listitem><para>
 305         If set to 1, the software is
 306         compiled with debugging libraries (code generation is
 307         multi-threaded debug DLL).
 308         If set to 0, the software is compiled with release libraries
 309         (code generation is multi-threaded DLL).
 310        </para></listitem>
 311      </varlistentry>
 312
 313      <varlistentry>
 314       <term><literal>YAZDIR</literal></term>
 315       <listitem><para>
 316         Directory of YAZ source. Zebra's makefile expects to find
 317         <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
 318         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
 319         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
 320        </para>
 321       </listitem>
 322      </varlistentry>
 323
 324      <varlistentry>
 325       <term><literal>HAVE_EXPAT</literal>,
 326        <literal>EXPAT_DIR</literal></term>
 327       <listitem><para>
 328         If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
 329         with Expat support. In this configuration, set
 330         <literal>ZEBRA_DIR</literal> to the Expat source directory.
 331         Windows version of Expat can be downloaded from
 332         <ulink url="http://sourceforge.net/projects/expat/">
 333          SourceForge
 334         </ulink>.
 335        </para></listitem>
 336      </varlistentry>
 337
 338      <varlistentry>
 339       <term><literal>HAVE_ICONV</literal>,
 340        <literal>ICONV_DIR</literal></term>
 341        <listitem><para>
 342         If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
 343         with iconv support. In this configuration, set
 344         <literal>ICONV_DIR</literal> to the iconv source directory.
 345         Iconv binaries can be downloaded from
 346         <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
 347          this site
 348         </ulink>.
 349        </para>
 350       </listitem>
 351      </varlistentry>
 352
 353      <varlistentry>
 354       <term><literal>BZIP2INCLUDE</literal>,
 355        <literal>BZIP2LIB</literal>,
 356        <literal>BZIP2DEF</literal>
 357       </term>
 358       <listitem><para>
 359         Define these symbols if Zebra is to be compiled with
 360         <ulink url="http://sources.redhat.com/bzip2/">BZIP2</ulink>
 361         record compression support.
 362        </para></listitem>
 363      </varlistentry>
 364
 365     </variablelist>
 366    </para>
 367    <warning>
 368     <para>
 369      The <literal>DEBUG</literal> setting in the makefile for Zebra must
 370      be set to the same value as <literal>DEBUG</literal> setting in the
 371      makefile for YAZ.
 372      If not, the Zebra server/indexer will crash.
 373     </para>
 374    </warning>
 375    <para>
 376     When satisfied with the settings in the makefile, type
 377     <screen>
 378      nmake
 379     </screen>
 380    </para>
 381    <note>
 382     <para>
 383      If the <filename>nmake</filename> command is not found on your system
 384      you probably haven't defined the environment variables required to
 385      use that tool. To fix that, find and run the batch file
 386      <filename>vcvars32.bat</filename>. You need to run it from within
 387      the command prompt or set the environment variables "globally";
 388      otherwise it doesn't work.
 389     </para>
 390    </note>
 391    <para>
 392     If you wish to recompile Zebra - for example if you modify
 393      settings in the <filename>makefile</filename> you can delete
 394     object files, etc by running.
 395     <screen>
 396      nmake clean
 397     </screen>
 398    </para>
 399    <para>
 400     The following files are generated upon successful compilation:
 401
 402     <variablelist>
 403      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 404       <listitem><para>
 405         The Zebra indexer.
 406        </para></listitem></varlistentry>
 407
 408      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 409       <listitem><para>
 410         The Zebra server.
 411        </para></listitem></varlistentry>
 412
 413     </variablelist>
 414
 415    </para>
 416   </sect1>
 417
 418
 419  </chapter>
 420  <!-- Keep this comment at the end of the file
 421  Local variables:
 422  mode: sgml
 423  sgml-omittag:t
 424  sgml-shorttag:t
 425  sgml-minimize-attributes:nil
 426  sgml-always-quote-attributes:t
 427  sgml-indent-step:1
 428  sgml-indent-data:t
 429  sgml-parent-document: "zebra.xml"
 430  sgml-local-catalogs: nil
 431  sgml-namecase-general:t
 432  End:
 433  -->