doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.23 2006-06-27 12:37:43 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/ <ulink url="http://www.loc.gov/standards/sru/srw/">SRW</ulink>. 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 on
 208    i686 Platform</title>
 209     <para>
 210      Index Data provides pre-compiled <literal>GNU/Debian i686
 211       Linux</literal> packages at our Debian package archive, both for
 212      the <literal>Sarge</literal> and the <literal>Etch</literal> release.
 213     </para>
 214
 215     <para>
 216      To install these packages, you need to add two lines to your
 217      <literal>/etc/apt/sources.list</literal> configuration file,
 218      either the <literal>Sarge</literal> sources found at
 219      <screen>
 220       deb http://ftp.indexdata.dk/t/debian sarge main
 221       deb-src http://ftp.indexdata.dk/t/debian sarge main
 222      </screen>
 223      or the <literal>Etch</literal> sources from
 224      <screen>
 225       deb http://ftp.indexdata.dk/t/debian etch main
 226       deb-src http://ftp.indexdata.dk/t/debian etch main
 227      </screen>
 228      After refreshing the package cache with the command
 229      <screen>
 230       apt-get update
 231      </screen>
 232      as <literal>root</literal>, the
 233      <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
 234      easily installed issuing
 235      <screen>
 236       apt-get install idzebra idzebra-doc
 237      </screen>
 238     </para>
 239    </sect2>
 240
 241    <sect2 id="installation.debianother">
 242     <title>GNU/Debian On Other Platforms</title>
 243     <para>
 244      These <ulink url="http://indexdata.dk/zebra/">Zebra</ulink>
 245      packages are specifically compiled for
 246      <literal>GNU/Debian Linux</literal> systems. Installation on other
 247      <literal>GNU/Debian</literal> systems is possible by
 248      re-compilation the Debian way: you need to add only the
 249      <literal>deb-src</literal> sources lines to the
 250      <literal>/etc/apt/sources.list</literal> configuration file,
 251      that is either the <literal>Sarge</literal> sources
 252      <screen>
 253       deb-src http://ftp.indexdata.dk/t/debian sarge main
 254      </screen>
 255      or the <literal>Etch</literal> sources
 256      <screen>
 257       deb-src http://ftp.indexdata.dk/t/debian etch main
 258      </screen>
 259      After refreshing the package cache with the command
 260      <screen>
 261       apt-get update
 262      </screen>
 263      as <literal>root</literal>, the
 264      <ulink url="http://indexdata.dk/zebra/">Zebra</ulink> indexer is
 265      recompiled and installed issuing
 266      <screen>
 267       apt-get build-dep idzebra
 268       apt-get source --compile idzebra
 269      </screen>
 270      as normal user.
 271      The compiled <literal>GNU/Debian</literal> packages can then be
 272      installed as <literal>root</literal> issuing
 273      <screen>
 274       dpkg -i install idzebra*.deb idzebra-doc*.deb
 275      </screen>
 276     </para>
 277    </sect2>
 278   </sect1>
 279
 280   <sect1 id="installation.win32"><title>WIN32</title>
 281    <para>The easiest way to install Zebra on Windows is by downloading
 282     an installer from
 283     <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
 284     The installer comes with source too - in case you wish to
 285     compile Zebra with different Compiler options.
 286    </para>
 287
 288    <para>
 289     Zebra is shipped with "makefiles" for the NMAKE tool that comes
 290     with <ulink url="http://msdn.microsoft.com/vstudio/">
 291      Microsoft Visual C++</ulink>.
 292     Version 6 has been tested. We expect that zebra compiles
 293     with version 5 as well.
 294    </para>
 295    <para>
 296     Start a command prompt and switch the sub directory
 297     <filename>WIN</filename> where the file <filename>makefile</filename>
 298     is located. Customize the installation by editing the
 299     <filename>makefile</filename> file (for example by using notepad).
 300
 301     The following summarizes the most important settings in that file:
 302
 303     <variablelist>
 304      <varlistentry><term><literal>DEBUG</literal></term>
 305       <listitem><para>
 306         If set to 1, the software is
 307         compiled with debugging libraries (code generation is
 308         multi-threaded debug DLL).
 309         If set to 0, the software is compiled with release libraries
 310         (code generation is multi-threaded DLL).
 311        </para></listitem>
 312      </varlistentry>
 313
 314      <varlistentry>
 315       <term><literal>YAZDIR</literal></term>
 316       <listitem><para>
 317         Directory of YAZ source. Zebra's makefile expects to find
 318         <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
 319         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
 320         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
 321        </para>
 322       </listitem>
 323      </varlistentry>
 324
 325      <varlistentry>
 326       <term><literal>HAVE_EXPAT</literal>,
 327        <literal>EXPAT_DIR</literal></term>
 328       <listitem><para>
 329         If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
 330         with <ulink url="http://expat.sourceforge.net/">Expat</ulink> support. In this configuration, set
 331         <literal>ZEBRA_DIR</literal> to the <ulink url="http://expat.sourceforge.net/">Expat</ulink> source directory.
 332         Windows version of Expat can be downloaded from
 333         <ulink url="http://sourceforge.net/projects/expat/">
 334          SourceForge
 335         </ulink>.
 336        </para></listitem>
 337      </varlistentry>
 338
 339      <varlistentry>
 340       <term><literal>HAVE_ICONV</literal>,
 341        <literal>ICONV_DIR</literal></term>
 342        <listitem><para>
 343         If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
 344         with iconv support. In this configuration, set
 345         <literal>ICONV_DIR</literal> to the iconv source directory.
 346         Iconv binaries can be downloaded from
 347         <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
 348          this site
 349         </ulink>.
 350        </para>
 351       </listitem>
 352      </varlistentry>
 353
 354      <varlistentry>
 355       <term><literal>BZIP2INCLUDE</literal>,
 356        <literal>BZIP2LIB</literal>,
 357        <literal>BZIP2DEF</literal>
 358       </term>
 359       <listitem><para>
 360         Define these symbols if Zebra is to be compiled with
 361         <ulink url="http://sources.redhat.com/bzip2/">BZIP2</ulink>
 362         record compression support.
 363        </para></listitem>
 364      </varlistentry>
 365
 366     </variablelist>
 367    </para>
 368    <warning>
 369     <para>
 370      The <literal>DEBUG</literal> setting in the makefile for Zebra must
 371      be set to the same value as <literal>DEBUG</literal> setting in the
 372      makefile for YAZ.
 373      If not, the Zebra server/indexer will crash.
 374     </para>
 375    </warning>
 376    <para>
 377     When satisfied with the settings in the makefile, type
 378     <screen>
 379      nmake
 380     </screen>
 381    </para>
 382    <note>
 383     <para>
 384      If the <filename>nmake</filename> command is not found on your system
 385      you probably haven't defined the environment variables required to
 386      use that tool. To fix that, find and run the batch file
 387      <filename>vcvars32.bat</filename>. You need to run it from within
 388      the command prompt or set the environment variables "globally";
 389      otherwise it doesn't work.
 390     </para>
 391    </note>
 392    <para>
 393     If you wish to recompile Zebra - for example if you modify
 394      settings in the <filename>makefile</filename> you can delete
 395     object files, etc by running.
 396     <screen>
 397      nmake clean
 398     </screen>
 399    </para>
 400    <para>
 401     The following files are generated upon successful compilation:
 402
 403     <variablelist>
 404      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 405       <listitem><para>
 406         The Zebra indexer.
 407        </para></listitem></varlistentry>
 408
 409      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 410       <listitem><para>
 411         The Zebra server.
 412        </para></listitem></varlistentry>
 413
 414     </variablelist>
 415
 416    </para>
 417   </sect1>
 418
 419
 420   <sect1 id="installation-upgrade">
 421    <title>Upgrading from Zebra version 1.3.x</title>
 422    <para>
 423     Zebra's installation directories have changed a bit. In addition,
 424     the new loadable modules must be defined in the
 425     master <filename>zebra.cfg</filename> configuration file. The old
 426     version 1.3.x configuration options
 427     <screen>
 428      # profilePath - where to look for config files
 429      profilePath: some/local/path:/usr/share/idzebra/tab
 430     </screen>
 431     must be changed to
 432     <screen>
 433      # profilePath - where to look for config files
 434      profilePath: some/local/path:/usr/share/idzebra2.0/tab
 435
 436      # modulePath - where to look for loadable zebra modules
 437      modulePath: /usr/lib/idzebra2.0/
 438     </screen>
 439    </para>
 440    <para>
 441     The internal binary register structures have changed; all Zebra
 442     databases must be re-indexed after upgrade.
 443    </para>
 444    <para>
 445     The attribute set defintion files may no longer contain
 446     redirection to other fields.
 447     For example the following snippet of
 448     a custom <filename>custom/bib1.att</filename>
 449     <literal>Bib-1</literal> attribute set definition file is no
 450     longer supported:
 451     <screen>
 452      att 1016            Any            1016,4,1005,62
 453     </screen>
 454     and should be changed to
 455     <screen>
 456      att 1016            Any
 457     </screen>
 458     Similar behaviour can be expressed in the new release by defining
 459     a new index <literal>Any:w</literal> in all GRS
 460     <filename>*.abs</filename> record indexing configuration files.
 461     The above example configuration needs to make the changes
 462     from version 1.3.x indexing instructions
 463     <screen>
 464      xelm /*/alternative  Body-of-text:w,Title:s,Title:w
 465      xelm /*/title        Body-of-text:w,Title:s,Title:w
 466     </screen>
 467     to version 2.0.0 indexing instructions
 468     <screen>
 469      xelm /*/alternative  Any:w,Body-of-text:w,Title:s,Title:w
 470      xelm /*/title        Any:w,Body-of-text:w,Title:s,Title:w
 471     </screen>
 472    </para>
 473   </sect1>
 474
 475  </chapter>
 476  <!-- Keep this comment at the end of the file
 477  Local variables:
 478  mode: sgml
 479  sgml-omittag:t
 480  sgml-shorttag:t
 481  sgml-minimize-attributes:nil
 482  sgml-always-quote-attributes:t
 483  sgml-indent-step:1
 484  sgml-indent-data:t
 485  sgml-parent-document: "zebra.xml"
 486  sgml-local-catalogs: nil
 487  sgml-namecase-general:t
 488  End:
 489  -->