doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.30 2006-09-15 09:21:52 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="&url.gcc;">GCC</ulink> on UNIX and
   7    <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
   8   </para>
   9
  10   <para>
  11    The software is regularly tested on
  12    <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
  13    <ulink url="&url.redhat;">Redhat Linux</ulink>,
  14    <ulink url="&url.gentoo;">Gentoo Linux</ulink>,
  15    <ulink url="&url.suse;">SuSE Linux</ulink>,
  16    <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
  17    <ulink url="&url.macosx;">MAC OSX</ulink>,
  18    <ulink url="&url.solaris;">SunOS 5.8
  19     (sparc)</ulink>,
  20    <ulink url="&url.windows2000;">Windows 2000</ulink>.
  21   </para>
  22
  23   <para>
  24    Zebra can be configured to use the following utilities (most of
  25    which are optional):
  26
  27    <variablelist>
  28     <varlistentry>
  29      <term><ulink url="&url.yaz;">yaz</ulink>
  30       (required)</term>
  31      <listitem>
  32       <para>
  33        Zebra uses YAZ to support <ulink url="&url.z39.50;">Z39.50</ulink> /
  34         <ulink url="&url.sru;">SRU</ulink>.
  35         Also the memory management utilites from YAZ is used by Zebra.
  36       </para>
  37      </listitem>
  38     </varlistentry>
  39     <varlistentry>
  40      <term><ulink url="&url.libiconv;">iconv</ulink>
  41       (optional)</term>
  42      <listitem>
  43       <para>
  44        Character set conversion. This is required if you're
  45        going to use any other character set than UTF-8 and ISO-8859-1
  46        for records. Note that some Unixes has iconv built-in.
  47       </para>
  48      </listitem>
  49     </varlistentry>
  50     <varlistentry>
  51      <term><ulink url="&url.expat;">Expat</ulink>
  52       (optional)</term>
  53      <listitem>
  54       <para>
  55        XML parser. If you're going to index real XML you should
  56        install this (filter grs.xml). On most systems you should be able
  57        to find binary Expat packages.
  58       </para>
  59      </listitem>
  60     </varlistentry>
  61
  62     <varlistentry>
  63      <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
  64      <listitem>
  65       <para>
  66        Tcl is required if you  need to use the Tcl record filter
  67        for Zebra. You can find binary packages for Tcl for many
  68        Unices and Windows.
  69       </para>
  70      </listitem>
  71     </varlistentry>
  72
  73     <varlistentry>
  74      <term>
  75       <ulink url="&url.autoconf;">Autoconf</ulink>,
  76       <ulink url="&url.automake;">Automake</ulink>
  77       (optional)</term>
  78      <listitem>
  79       <para>
  80        GNU Automake and Autoconf are only required if you're
  81        using the CVS version of Zebra. You do not need these
  82        if you have fetched a Zebra tar.
  83       </para>
  84      </listitem>
  85     </varlistentry>
  86
  87     <varlistentry>
  88      <term><ulink url="&url.docbook;">Docbook</ulink>
  89       and friends (optional)</term>
  90      <listitem>
  91       <para>
  92        These tools are only required if you're writing
  93        documentation for Zebra. You need the following
  94        Debian packages: jadetex, docbook, docbook-dsssl,
  95        docbook-xml, docbook-utils.
  96       </para>
  97      </listitem>
  98     </varlistentry>
  99    </variablelist>
 100   </para>
 101
 102   <section id="installation-unix"><title>UNIX</title>
 103    <para>
 104     On Unix, GCC works fine, but any native
 105     C compiler should be possible to use as long as it is
 106     ANSI C compliant.
 107    </para>
 108
 109    <para>
 110     Unpack the distribution archive. The <literal>configure</literal>
 111     shell script attempts to guess correct values for various
 112     system-dependent variables used during compilation.
 113     It uses those values to create a <literal>Makefile</literal> in each
 114     directory of Zebra.
 115    </para>
 116
 117    <para>
 118     To run the configure script type:
 119
 120     <screen>
 121      ./configure
 122     </screen>
 123
 124    </para>
 125
 126    <para>
 127     The configure script attempts to use C compiler specified by
 128     the <literal>CC</literal> environment variable.
 129     If this is not set, <literal>cc</literal> or GNU C will be used.
 130     The <literal>CFLAGS</literal> environment variable holds
 131     options to be passed to the C compiler. If you're using a
 132     Bourne-shell compatible shell you may pass something like this:
 133
 134     <screen>
 135      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
 136     </screen>
 137    </para>
 138    <para>
 139     The configure script support various options: you can see what they
 140     are with
 141     <screen>
 142      ./configure --help
 143     </screen>
 144    </para>
 145
 146    <para>
 147     Once the build environment is configured, build the software by
 148     typing:
 149     <screen>
 150      make
 151     </screen>
 152    </para>
 153
 154    <para>
 155     If the build is successful, two executables are created in the
 156     sub-directory <literal>index</literal>:
 157     <variablelist>
 158
 159      <varlistentry>
 160       <term><literal>zebrasrv</literal></term>
 161       <listitem>
 162        <para>
 163         The Z39.50 server and search engine.
 164        </para>
 165       </listitem>
 166      </varlistentry>
 167      <varlistentry>
 168      <term><literal>zebraidx</literal></term>
 169       <listitem>
 170        <para>
 171         The administrative indexing tool.
 172        </para>
 173       </listitem>
 174      </varlistentry>
 175     </variablelist>
 176    </para>
 177
 178    <para>
 179     You can now use Zebra. If you wish to install it system-wide, then
 180     as root type
 181     <screen>
 182      make install
 183     </screen>
 184     By default this will install the Zebra executables in
 185     <filename>/usr/local/bin</filename>,
 186     and the standard configuration files in
 187     <filename>/usr/local/share/idzebra-2.0</filename>
 188     You can override this with the <literal>--prefix</literal> option
 189     to configure.
 190    </para>
 191   </section>
 192
 193   <section id="installation-debian"><title>GNU/Debian</title>
 194    <section id="installation-debian-linux"><title>GNU/Debian Linux on
 195    i686 Platform</title>
 196     <para>
 197      Index Data provides pre-compiled GNU/Debian i686 Linux packages
 198      at our Debian package archive, both for
 199      the Sarge and the Etch release.
 200     </para>
 201
 202     <para>
 203      To install these packages, you need to add two lines to your
 204      <filename>/etc/apt/sources.list</filename> configuration file,
 205      either the Sarge sources found at
 206      <screen>
 207       deb http://ftp.indexdata.dk/debian sarge main
 208       deb-src http://ftp.indexdata.dk/debian sarge main
 209      </screen>
 210      or the Etch sources from
 211      <screen>
 212       deb http://ftp.indexdata.dk/debian etch main
 213       deb-src http://ftp.indexdata.dk/debian etch main
 214      </screen>
 215      After refreshing the package cache with the command
 216      <screen>
 217       apt-get update
 218      </screen>
 219      as <literal>root</literal>, the
 220      <ulink url="&url.idzebra;">Zebra</ulink> indexer is
 221      easily installed issuing
 222      <screen>
 223       apt-get install idzebra-2.0 idzebra-2.0-doc
 224      </screen>
 225     </para>
 226    </section>
 227
 228    <section id="installation-debia-nother">
 229     <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
 230     <para>
 231      These <ulink url="&url.idzebra;">Zebra</ulink>
 232      packages are specifically compiled for
 233      GNU/Debian Linux systems. Installation on other
 234      GNU/Debian systems is possible by
 235      re-compilation the Debian way: you need to add only the
 236      <literal>deb-src</literal> sources lines to the
 237      <filename>/etc/apt/sources.list</filename> configuration file,
 238      that is either the Sarge sources
 239      <screen>
 240       deb-src http://ftp.indexdata.dk/debian sarge main
 241      </screen>
 242      or the Etch sources
 243      <screen>
 244       deb-src http://ftp.indexdata.dk/debian etch main
 245      </screen>
 246      After refreshing the package cache with the command
 247      <screen>
 248       apt-get update
 249       apt-get build-dep idzebra-2.0
 250      </screen>
 251      as <literal>root</literal>, the
 252      <ulink url="&url.idzebra;">Zebra</ulink> indexer is
 253      recompiled and installed issuing
 254      <screen>
 255       apt-get source --compile idzebra-2.0
 256      </screen>
 257      as normal user.
 258      The compiled GNU/Debian packages can then be
 259      installed as <literal>root</literal> issuing
 260      <screen>
 261       dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
 262      </screen>
 263     </para>
 264    </section>
 265   </section>
 266
 267   <section id="installation-win32"><title>WIN32</title>
 268    <para>The easiest way to install Zebra on Windows is by downloading
 269     an installer from
 270     <ulink url="http://ftp.indexdata.dk/pub/zebra/win32/">here</ulink>.
 271     The installer comes with source too - in case you wish to
 272     compile Zebra with different Compiler options.
 273    </para>
 274
 275    <para>
 276     Zebra is shipped with "makefiles" for the NMAKE tool that comes
 277     with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
 278     Version 2003 and 2005 has been tested. We expect that zebra compiles
 279     with version 6 as well.
 280    </para>
 281    <para>
 282     Start a command prompt and switch the sub directory
 283     <filename>WIN</filename> where the file <filename>makefile</filename>
 284     is located. Customize the installation by editing the
 285     <filename>makefile</filename> file (for example by using notepad).
 286
 287     The following summarizes the most important settings in that file:
 288
 289     <variablelist>
 290      <varlistentry><term><literal>DEBUG</literal></term>
 291       <listitem><para>
 292         If set to 1, the software is
 293         compiled with debugging libraries (code generation is
 294         multi-threaded debug DLL).
 295         If set to 0, the software is compiled with release libraries
 296         (code generation is multi-threaded DLL).
 297        </para></listitem>
 298      </varlistentry>
 299
 300      <varlistentry>
 301       <term><literal>YAZDIR</literal></term>
 302       <listitem><para>
 303         Directory of YAZ source. Zebra's makefile expects to find
 304         <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
 305         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
 306         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
 307        </para>
 308       </listitem>
 309      </varlistentry>
 310
 311      <varlistentry>
 312       <term><literal>HAVE_EXPAT</literal>,
 313        <literal>EXPAT_DIR</literal></term>
 314       <listitem><para>
 315         If <literal>HAVE_EXPAT</literal> is set to 1, Zebra is compiled
 316         with <ulink url="&url.expat;">Expat</ulink> support.
 317         In this configuration, set
 318         <literal>ZEBRA_DIR</literal> to the Expat source directory.
 319         Windows version of Expat can be downloaded from
 320         <ulink url="&url.expat;">SourceForge</ulink>.
 321        </para></listitem>
 322      </varlistentry>
 323
 324      <varlistentry>
 325       <term><literal>HAVE_ICONV</literal>,
 326        <literal>ICONV_DIR</literal></term>
 327        <listitem><para>
 328         If <literal>HAVE_ICONV</literal> is set to 1, Zebra is compiled
 329         with iconv support. In this configuration, set
 330         <literal>ICONV_DIR</literal> to the iconv source directory.
 331         Iconv binaries can be downloaded from
 332         <ulink url="&url.libxml2.download.win32;">this site</ulink>.
 333        </para>
 334       </listitem>
 335      </varlistentry>
 336
 337      <varlistentry>
 338       <term><literal>BZIP2INCLUDE</literal>,
 339        <literal>BZIP2LIB</literal>,
 340        <literal>BZIP2DEF</literal>
 341       </term>
 342       <listitem><para>
 343         Define these symbols if Zebra is to be compiled with
 344         <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
 345        </para></listitem>
 346      </varlistentry>
 347
 348     </variablelist>
 349    </para>
 350    <warning>
 351     <para>
 352      The <literal>DEBUG</literal> setting in the makefile for Zebra must
 353      be set to the same value as <literal>DEBUG</literal> setting in the
 354      makefile for YAZ.
 355      If not, the Zebra server/indexer will crash.
 356     </para>
 357    </warning>
 358    <para>
 359     When satisfied with the settings in the makefile, type
 360     <screen>
 361      nmake
 362     </screen>
 363    </para>
 364    <note>
 365     <para>
 366      If the <filename>nmake</filename> command is not found on your system
 367      you probably haven't defined the environment variables required to
 368      use that tool. To fix that, find and run the batch file
 369      <filename>vcvars32.bat</filename>. You need to run it from within
 370      the command prompt or set the environment variables "globally";
 371      otherwise it doesn't work.
 372     </para>
 373    </note>
 374    <para>
 375     If you wish to recompile Zebra - for example if you modify
 376      settings in the <filename>makefile</filename> you can delete
 377     object files, etc by running.
 378     <screen>
 379      nmake clean
 380     </screen>
 381    </para>
 382    <para>
 383     The following files are generated upon successful compilation:
 384
 385     <variablelist>
 386      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 387       <listitem><para>
 388         The Zebra indexer.
 389        </para></listitem></varlistentry>
 390
 391      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 392       <listitem><para>
 393         The Zebra server.
 394        </para></listitem></varlistentry>
 395
 396     </variablelist>
 397
 398    </para>
 399   </section>
 400
 401
 402   <section id="installation-upgrade">
 403    <title>Upgrading from Zebra version 1.3.x</title>
 404    <para>
 405     Zebra's installation directories have changed a bit. In addition,
 406     the new loadable modules must be defined in the
 407     master <filename>zebra.cfg</filename> configuration file. The old
 408     version 1.3.x configuration options
 409     <screen>
 410      # profilePath - where to look for config files
 411      profilePath: some/local/path:/usr/share/idzebra/tab
 412     </screen>
 413     must be changed to
 414     <screen>
 415      # profilePath - where to look for config files
 416      profilePath: some/local/path:/usr/share/idzebra-2.0/tab
 417
 418      # modulePath - where to look for loadable zebra modules
 419      modulePath: /usr/lib/idzebra-2.0/modules
 420     </screen>
 421    </para>
 422    <note>
 423     <para>
 424      The internal binary register structures have changed; all Zebra
 425      databases must be re-indexed after upgrade.
 426     </para>
 427    </note>
 428    <para>
 429     The attribute set defintion files may no longer contain
 430     redirection to other fields.
 431     For example the following snippet of
 432     a custom <filename>custom/bib1.att</filename>
 433     Bib-1 attribute set definition file is no
 434     longer supported:
 435     <screen>
 436      att 1016            Any            1016,4,1005,62
 437     </screen>
 438     and should be changed to
 439     <screen>
 440      att 1016            Any
 441     </screen>
 442    </para>
 443    <para>
 444     Similar behaviour can be expressed in the new release by defining
 445     a new index <literal>Any:w</literal> in all GRS
 446     <filename>*.abs</filename> record indexing configuration files.
 447     The above example configuration needs to make the changes
 448     from version 1.3.x indexing instructions
 449     <screen>
 450      xelm /*/alternative  Body-of-text:w,Title:s,Title:w
 451      xelm /*/title        Body-of-text:w,Title:s,Title:w
 452     </screen>
 453     to version 2.0.0 indexing instructions
 454     <screen>
 455      xelm /*/alternative  Any:w,Body-of-text:w,Title:s,Title:w
 456      xelm /*/title        Any:w,Body-of-text:w,Title:s,Title:w
 457     </screen>
 458    </para>
 459    <para>
 460     It is also possible to map the numerical attribute value
 461     <literal>@attr 1=1016</literal> onto another already existing huge
 462     index, in this example, one could for example use the mapping
 463     <screen>
 464      att 1016            Body-of-text
 465     </screen>
 466     with equivalent outcome without editing all  GRS
 467     <filename>*.abs</filename> record indexing configuration files.
 468    </para>
 469
 470    <para>
 471     Server installations which use the special
 472     <literal>IDXPATH</literal> attribute set must add the following
 473     line to the <filename>zebra.cfg</filename> configuration file:
 474     <screen>
 475      attset: idxpath.att
 476     </screen>
 477     </para>
 478   </section>
 479
 480  </chapter>
 481  <!-- Keep this comment at the end of the file
 482  Local variables:
 483  mode: sgml
 484  sgml-omittag:t
 485  sgml-shorttag:t
 486  sgml-minimize-attributes:nil
 487  sgml-always-quote-attributes:t
 488  sgml-indent-step:1
 489  sgml-indent-data:t
 490  sgml-parent-document: "zebra.xml"
 491  sgml-local-catalogs: nil
 492  sgml-namecase-general:t
 493  End:
 494  -->