doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.35 2007-02-02 11:10:08 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="&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.9
  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;">&z3950;</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: docbook, docbook-xml, docbook-xsl,
  95        docbook-utils, xsltproc.
  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 &z3950; 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
 176      <varlistentry>
 177      <term><literal>index/*.so</literal></term>
 178       <listitem>
 179        <para>
 180         The <literal>.so</literal>-files are &zebra; record filter modules.
 181         There are modules for reading
 182         &marc; (<filename>mod-grs-marc.so</filename>),
 183         &xml; (<filename>mod-grs-xml.so</filename>) , etc.
 184        </para>
 185       </listitem>
 186      </varlistentry>
 187
 188     </variablelist>
 189    </para>
 190
 191    <note>
 192     <para>
 193      Using configure option <literal>--disable-shared</literal> builds
 194      &zebra; statically and links "in" &zebra; filter code statically, i.e.
 195      no <literal>.so-files</literal> are generated
 196     </para>
 197    </note>
 198
 199    <para>
 200     You can now use &zebra;. If you wish to install it system-wide, then
 201     as root type
 202     <screen>
 203      make install
 204     </screen>
 205     By default this will install the &zebra; executables in
 206     <filename>/usr/local/bin</filename>,
 207     and the standard configuration files in
 208     <filename>/usr/local/share/idzebra-2.0</filename>. If
 209     shared modules are built, these are installed in
 210     <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
 211     You can override this with the <literal>--prefix</literal> option
 212     to configure.
 213    </para>
 214   </section>
 215
 216   <section id="installation-debian"><title>GNU/Debian</title>
 217    <section id="installation-debian-linux"><title>GNU/Debian Linux on
 218    i686 Platform</title>
 219     <para>
 220      Index Data provides pre-compiled GNU/Debian i686 Linux packages
 221      at our Debian package archive, both for
 222      the Sarge and the Etch release.
 223     </para>
 224
 225     <para>
 226      To install these packages, you need to add two lines to your
 227      <filename>/etc/apt/sources.list</filename> configuration file,
 228      either the Sarge sources found at
 229      <screen>
 230       deb http://ftp.indexdata.dk/debian sarge main
 231       deb-src http://ftp.indexdata.dk/debian sarge main
 232      </screen>
 233      or the Etch sources from
 234      <screen>
 235       deb http://ftp.indexdata.dk/debian etch main
 236       deb-src http://ftp.indexdata.dk/debian etch main
 237      </screen>
 238      After refreshing the package cache with the command
 239      <screen>
 240       apt-get update
 241      </screen>
 242      as <literal>root</literal>, the
 243      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
 244      easily installed issuing
 245      <screen>
 246       apt-get install idzebra-2.0 idzebra-2.0-doc
 247      </screen>
 248     </para>
 249    </section>
 250
 251    <section id="installation-debia-nother">
 252     <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
 253     <para>
 254      These <ulink url="&url.idzebra;">&zebra;</ulink>
 255      packages are specifically compiled for
 256      GNU/Debian Linux systems. Installation on other
 257      GNU/Debian systems is possible by
 258      re-compilation the Debian way: you need to add only the
 259      <literal>deb-src</literal> sources lines to the
 260      <filename>/etc/apt/sources.list</filename> configuration file,
 261      that is either the Sarge sources
 262      <screen>
 263       deb-src http://ftp.indexdata.dk/debian sarge main
 264      </screen>
 265      or the Etch sources
 266      <screen>
 267       deb-src http://ftp.indexdata.dk/debian etch main
 268      </screen>
 269      After refreshing the package cache with the command
 270      <screen>
 271       apt-get update
 272       apt-get build-dep idzebra-2.0
 273      </screen>
 274      as <literal>root</literal>, the
 275      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
 276      recompiled and installed issuing
 277      <screen>
 278       fakeroot apt-get source --compile idzebra-2.0
 279      </screen>
 280      as normal user.
 281      The compiled GNU/Debian packages can then be
 282      installed as <literal>root</literal> issuing
 283      <screen>
 284       dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
 285      </screen>
 286     </para>
 287    </section>
 288   </section>
 289
 290   <section id="installation-win32"><title>WIN32</title>
 291    <para>The easiest way to install &zebra; on Windows is by downloading
 292     an installer from
 293     <ulink url="&url.idzebra.download.win32;">here</ulink>.
 294     The installer comes with source too - in case you wish to
 295     compile &zebra; with different Compiler options.
 296    </para>
 297
 298    <para>
 299     &zebra; is shipped with "makefiles" for the NMAKE tool that comes
 300     with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
 301     Version 2003 and 2005 has been tested. We expect that zebra compiles
 302     with version 6 as well.
 303    </para>
 304    <para>
 305     Start a command prompt and switch the sub directory
 306     <filename>WIN</filename> where the file <filename>makefile</filename>
 307     is located. Customize the installation by editing the
 308     <filename>makefile</filename> file (for example by using notepad).
 309
 310     The following summarizes the most important settings in that file:
 311
 312     <variablelist>
 313      <varlistentry><term><literal>DEBUG</literal></term>
 314       <listitem><para>
 315         If set to 1, the software is
 316         compiled with debugging libraries (code generation is
 317         multi-threaded debug DLL).
 318         If set to 0, the software is compiled with release libraries
 319         (code generation is multi-threaded DLL).
 320        </para></listitem>
 321      </varlistentry>
 322
 323      <varlistentry>
 324       <term><literal>YAZDIR</literal></term>
 325       <listitem><para>
 326         Directory of &yaz; source. &zebra;'s makefile expects to find
 327         <filename>yaz.lib</filename>, <filename>yaz.dll</filename>
 328         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
 329         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
 330        </para>
 331       </listitem>
 332      </varlistentry>
 333
 334      <varlistentry>
 335       <term><literal>HAVE_EXPAT</literal>,
 336        <literal>EXPAT_DIR</literal></term>
 337       <listitem><para>
 338         If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
 339         with <ulink url="&url.expat;">Expat</ulink> support.
 340         In this configuration, set
 341         <literal>ZEBRA_DIR</literal> to the Expat source directory.
 342         Windows version of Expat can be downloaded from
 343         <ulink url="&url.expat;">SourceForge</ulink>.
 344        </para></listitem>
 345      </varlistentry>
 346
 347      <varlistentry>
 348       <term><literal>HAVE_ICONV</literal>,
 349        <literal>ICONV_DIR</literal></term>
 350        <listitem><para>
 351         If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
 352         with iconv support. In this configuration, set
 353         <literal>ICONV_DIR</literal> to the iconv source directory.
 354         Iconv binaries can be downloaded from
 355         <ulink url="&url.libxml2.download.win32;">this site</ulink>.
 356        </para>
 357       </listitem>
 358      </varlistentry>
 359
 360      <varlistentry>
 361       <term><literal>BZIP2INCLUDE</literal>,
 362        <literal>BZIP2LIB</literal>,
 363        <literal>BZIP2DEF</literal>
 364       </term>
 365       <listitem><para>
 366         Define these symbols if &zebra; is to be compiled with
 367         <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
 368        </para></listitem>
 369      </varlistentry>
 370
 371     </variablelist>
 372    </para>
 373    <warning>
 374     <para>
 375      The <literal>DEBUG</literal> setting in the makefile for &zebra; must
 376      be set to the same value as <literal>DEBUG</literal> setting in the
 377      makefile for &yaz;.
 378      If not, the &zebra; server/indexer will crash.
 379     </para>
 380    </warning>
 381    <para>
 382     When satisfied with the settings in the makefile, type
 383     <screen>
 384      nmake
 385     </screen>
 386    </para>
 387    <note>
 388     <para>
 389      If the <filename>nmake</filename> command is not found on your system
 390      you probably haven't defined the environment variables required to
 391      use that tool. To fix that, find and run the batch file
 392      <filename>vcvars32.bat</filename>. You need to run it from within
 393      the command prompt or set the environment variables "globally";
 394      otherwise it doesn't work.
 395     </para>
 396    </note>
 397    <para>
 398     If you wish to recompile &zebra; - for example if you modify
 399      settings in the <filename>makefile</filename> you can delete
 400     object files, etc by running.
 401     <screen>
 402      nmake clean
 403     </screen>
 404    </para>
 405    <para>
 406     The following files are generated upon successful compilation:
 407
 408     <variablelist>
 409      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 410       <listitem><para>
 411         The &zebra; indexer.
 412        </para></listitem></varlistentry>
 413
 414      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 415       <listitem><para>
 416         The &zebra; server.
 417        </para></listitem></varlistentry>
 418
 419     </variablelist>
 420
 421    </para>
 422   </section>
 423
 424
 425   <section id="installation-upgrade">
 426    <title>Upgrading from &zebra; version 1.3.x</title>
 427    <para>
 428     &zebra;'s installation directories have changed a bit. In addition,
 429     the new loadable modules must be defined in the
 430     master <filename>zebra.cfg</filename> configuration file. The old
 431     version 1.3.x configuration options
 432     <screen>
 433      # profilePath - where to look for config files
 434      profilePath: some/local/path:/usr/share/idzebra/tab
 435     </screen>
 436     must be changed to
 437     <screen>
 438      # profilePath - where to look for config files
 439      profilePath: some/local/path:/usr/share/idzebra-2.0/tab
 440
 441      # modulePath - where to look for loadable zebra modules
 442      modulePath: /usr/lib/idzebra-2.0/modules
 443     </screen>
 444    </para>
 445    <note>
 446     <para>
 447      The internal binary register structures have changed; all &zebra;
 448      databases must be re-indexed after upgrade.
 449     </para>
 450    </note>
 451    <para>
 452     The attribute set defintion files may no longer contain
 453     redirection to other fields.
 454     For example the following snippet of
 455     a custom <filename>custom/bib1.att</filename>
 456     &bib1; attribute set definition file is no
 457     longer supported:
 458     <screen>
 459      att 1016            Any            1016,4,1005,62
 460     </screen>
 461     and should be changed to
 462     <screen>
 463      att 1016            Any
 464     </screen>
 465    </para>
 466    <para>
 467     Similar behaviour can be expressed in the new release by defining
 468     a new index <literal>Any:w</literal> in all &grs1;
 469     <filename>*.abs</filename> record indexing configuration files.
 470     The above example configuration needs to make the changes
 471     from version 1.3.x indexing instructions
 472     <screen>
 473      xelm /*/alternative  Body-of-text:w,Title:s,Title:w
 474      xelm /*/title        Body-of-text:w,Title:s,Title:w
 475     </screen>
 476     to version 2.0.0 indexing instructions
 477     <screen>
 478      xelm /*/alternative  Any:w,Body-of-text:w,Title:s,Title:w
 479      xelm /*/title        Any:w,Body-of-text:w,Title:s,Title:w
 480     </screen>
 481    </para>
 482    <para>
 483     It is also possible to map the numerical attribute value
 484     <literal>@attr 1=1016</literal> onto another already existing huge
 485     index, in this example, one could for example use the mapping
 486     <screen>
 487      att 1016            Body-of-text
 488     </screen>
 489     with equivalent outcome without editing all  &grs1;
 490     <filename>*.abs</filename> record indexing configuration files.
 491    </para>
 492
 493    <para>
 494     Server installations which use the special
 495     <literal>&idxpath;</literal> attribute set must add the following
 496     line to the <filename>zebra.cfg</filename> configuration file:
 497     <screen>
 498      attset: idxpath.att
 499     </screen>
 500     </para>
 501   </section>
 502
 503  </chapter>
 504  <!-- Keep this comment at the end of the file
 505  Local variables:
 506  mode: sgml
 507  sgml-omittag:t
 508  sgml-shorttag:t
 509  sgml-minimize-attributes:nil
 510  sgml-always-quote-attributes:t
 511  sgml-indent-step:1
 512  sgml-indent-data:t
 513  sgml-parent-document: "zebra.xml"
 514  sgml-local-catalogs: nil
 515  sgml-namecase-general:t
 516  End:
 517  -->