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