doc/installation.xml

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