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      amd64/i386 Platform</title>
 228     <para>
 229      Index Data provides pre-compiled GNU/Debian and Ubuntu packages
 230      at our Debian package archive, both for recent releases.
 231     </para>
 232
 233     <para>
 234      For Debian, refer to
 235      <ulink url="http://ftp.indexdata.dk/pub/zebra/debian/README"/>
 236      for how to configure APT. For Ubuntu, refer to
 237      <ulink url="http://ftp.indexdata.dk/pub/zebra/ubuntu/README"/>.
 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>GNU/Debian and Ubuntu on other architectures</title>
 253     <para>
 254      These <ulink url="&url.idzebra;">&zebra;</ulink>
 255      packages are specifically compiled for
 256      GNU/Debian Linux systems and Ubuntu. 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      After refreshing the package cache with the command
 262      <screen>
 263       apt-get update
 264       apt-get build-dep idzebra-2.0
 265      </screen>
 266      as <literal>root</literal>, the
 267      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
 268      recompiled and installed issuing
 269      <screen>
 270       fakeroot apt-get source --compile idzebra-2.0
 271      </screen>
 272      as normal user.
 273      The compiled GNU/Debian packages can then be
 274      installed as <literal>root</literal> issuing
 275      <screen>
 276       dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
 277      </screen>
 278     </para>
 279    </section>
 280   </section>
 281
 282   <section id="installation-win32"><title>WIN32</title>
 283    <para>The easiest way to install &zebra; on Windows is by downloading
 284     an installer from
 285     <ulink url="&url.idzebra.download.win32;">here</ulink>.
 286     The installer comes with source too - in case you wish to
 287     compile &zebra; with different Compiler options.
 288    </para>
 289
 290    <para>
 291     &zebra; is shipped with "makefiles" for the NMAKE tool that comes
 292     with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
 293     Version 2003, 2005 and 2008 has been tested.
 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         YAZ<filename>.lib</filename>, YAZ<filename>.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="&url.expat;">Expat</ulink> support.
 331         In this configuration, set
 332         <literal>ZEBRA_DIR</literal> to the Expat source directory.
 333         Windows version of Expat can be downloaded from
 334         <ulink url="&url.expat;">SourceForge</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="&url.libxml2.download.win32;">this site</ulink>.
 347        </para>
 348       </listitem>
 349      </varlistentry>
 350
 351      <varlistentry>
 352       <term><literal>BZIP2INCLUDE</literal>,
 353        <literal>BZIP2LIB</literal>,
 354        <literal>BZIP2DEF</literal>
 355       </term>
 356       <listitem><para>
 357         Define these symbols if &zebra; is to be compiled with
 358         <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
 359        </para></listitem>
 360      </varlistentry>
 361
 362     </variablelist>
 363    </para>
 364    <warning>
 365     <para>
 366      The <literal>DEBUG</literal> setting in the makefile for &zebra; must
 367      be set to the same value as <literal>DEBUG</literal> setting in the
 368      makefile for &yaz;.
 369      If not, the &zebra; server/indexer will crash.
 370     </para>
 371    </warning>
 372    <para>
 373     When satisfied with the settings in the makefile, type
 374     <screen>
 375      nmake
 376     </screen>
 377    </para>
 378    <note>
 379     <para>
 380      If the <filename>nmake</filename> command is not found on your system
 381      you probably haven't defined the environment variables required to
 382      use that tool. To fix that, find and run the batch file
 383      <filename>vcvars32.bat</filename>. You need to run it from within
 384      the command prompt or set the environment variables "globally";
 385      otherwise it doesn't work.
 386     </para>
 387    </note>
 388    <para>
 389     If you wish to recompile &zebra; - for example if you modify
 390     settings in the <filename>makefile</filename> you can delete
 391     object files, etc by running.
 392     <screen>
 393      nmake clean
 394     </screen>
 395    </para>
 396    <para>
 397     The following files are generated upon successful compilation:
 398
 399     <variablelist>
 400      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
 401       <listitem><para>
 402         The &zebra; indexer.
 403        </para></listitem></varlistentry>
 404
 405      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
 406       <listitem><para>
 407         The &zebra; server.
 408        </para></listitem></varlistentry>
 409
 410     </variablelist>
 411
 412    </para>
 413   </section>
 414
 415
 416   <section id="installation-upgrade">
 417    <title>Upgrading from &zebra; version 1.3.x</title>
 418    <para>
 419     &zebra;'s installation directories have changed a bit. In addition,
 420     the new loadable modules must be defined in the
 421     master <filename>zebra.cfg</filename> configuration file. The old
 422     version 1.3.x configuration options
 423     <screen>
 424      # profilePath - where to look for config files
 425      profilePath: some/local/path:/usr/share/idzebra/tab
 426     </screen>
 427     must be changed to
 428     <screen>
 429      # profilePath - where to look for config files
 430      profilePath: some/local/path:/usr/share/idzebra-2.0/tab
 431
 432      # modulePath - where to look for loadable zebra modules
 433      modulePath: /usr/lib/idzebra-2.0/modules
 434     </screen>
 435    </para>
 436    <note>
 437     <para>
 438      The internal binary register structures have changed; all &zebra;
 439      databases must be re-indexed after upgrade.
 440     </para>
 441    </note>
 442    <para>
 443     The attribute set definition files may no longer contain
 444     redirection to other fields.
 445     For example the following snippet of
 446     a custom <filename>custom/bib1.att</filename>
 447     &acro.bib1; attribute set definition file is no
 448     longer supported:
 449     <screen>
 450      att 1016            Any            1016,4,1005,62
 451     </screen>
 452     and should be changed to
 453     <screen>
 454      att 1016            Any
 455     </screen>
 456    </para>
 457    <para>
 458     Similar behaviour can be expressed in the new release by defining
 459     a new index <literal>Any:w</literal> in all &acro.grs1;
 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    <para>
 474     It is also possible to map the numerical attribute value
 475     <literal>@attr 1=1016</literal> onto another already existing huge
 476     index, in this example, one could for example use the mapping
 477     <screen>
 478      att 1016            Body-of-text
 479     </screen>
 480     with equivalent outcome without editing all  &acro.grs1;
 481     <filename>*.abs</filename> record indexing configuration files.
 482    </para>
 483
 484    <para>
 485     Server installations which use the special
 486     <literal>&acro.idxpath;</literal> attribute set must add the following
 487     line to the <filename>zebra.cfg</filename> configuration file:
 488     <screen>
 489      attset: idxpath.att
 490     </screen>
 491    </para>
 492   </section>
 493
 494  </chapter>
 495  <!-- Keep this comment at the end of the file
 496  Local variables:
 497  mode: sgml
 498  sgml-omittag:t
 499  sgml-shorttag:t
 500  sgml-minimize-attributes:nil
 501  sgml-always-quote-attributes:t
 502  sgml-indent-step:1
 503  sgml-indent-data:t
 504  sgml-parent-document: "idzebra.xml"
 505  sgml-local-catalogs: nil
 506  sgml-namecase-general:t
 507  End:
 508  -->