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