[idzebra-moved-to-github.git] / doc / installation.xml

 <chapter id="installation">
  <title>Installation</title>
  <para>
   &zebra; is written in &acro.ansi; C and was implemented with portability in mind. 
   We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and 
   <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
  </para>

  <para>
   The software is regularly tested on
   <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
   <ulink url="&url.redhat;">Red Hat Linux</ulink>,
   <ulink url="&url.gentoo;">Gentoo Linux</ulink>,
   <ulink url="&url.suse;">SuSE Linux</ulink>,
   <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
   <ulink url="&url.macosx;">MAC OSX</ulink>,
   <ulink url="&url.solaris;">SunOS 5.9
    (sparc)</ulink>,
   <ulink url="&url.windows2000;">Windows 2000</ulink>.
  </para>
  
  <para>
   &zebra; can be configured to use the following utilities (most of
   which are optional):

   <variablelist>
    <varlistentry>
     <term><ulink url="&url.yaz;">&yaz;</ulink>
      (required)</term>
     <listitem>
      <para>
       &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> / 
       <ulink url="&url.sru;">&acro.sru;</ulink>.
       Zebra also uses a lot of other utilities (not related to networking),
       such as memory management and XML support.
      </para>
      <para>
       For the <link linkend="record-model-domxml">DOM XML</link>
       / <link linkend="record-model-alvisxslt">ALVIS</link>
       record filters, &yaz; must be compiled with 
       <ulink url="&url.libxml2;">Libxml2</ulink>
       and
       <ulink url="&url.libxslt;">Libxslt</ulink>
       support and Libxml2 must be version 2.6.15 or later.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><ulink url="&url.libiconv;">iconv</ulink>
      (optional)</term>
     <listitem>
      <para>
       Character set conversion. This is required if you're
       going to use any other character set than UTF-8 and ISO-8859-1
       for records. Note that some Unixes has iconv built-in.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><ulink url="&url.expat;">Expat</ulink>
      (optional)</term>
     <listitem>
      <para>
       &acro.xml; parser. If you're going to index real &acro.xml; you should
       install this (filter grs.xml). On most systems you should be able
       to find binary Expat packages.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
     <listitem>
      <para>
       Tcl is required if you  need to use the Tcl record filter
       for &zebra;. You can find binary packages for Tcl for many
       Unices and Windows.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>
      <ulink url="&url.autoconf;">Autoconf</ulink>,
      <ulink url="&url.automake;">Automake</ulink>
      (optional)</term>
     <listitem>
      <para>
       GNU Automake and Autoconf are only required if you're
       using the CVS version of &zebra;. You do not need these
       if you have fetched a &zebra; tar.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term><ulink url="&url.docbook;">Docbook</ulink>
      and friends (optional)</term>
     <listitem>
      <para>
       These tools are only required if you're writing
       documentation for &zebra;. You need the following
       Debian packages: docbook, docbook-xml, docbook-xsl,
       docbook-utils, xsltproc.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <section id="installation-unix"><title>UNIX</title>
   <para>
    On Unix, GCC works fine, but any native
    C compiler should be possible to use as long as it is 
    &acro.ansi; C compliant.
   </para>
   
   <para>
    Unpack the distribution archive. The <literal>configure</literal>
    shell script attempts to guess correct values for various
    system-dependent variables used during compilation.
    It uses those values to create a <literal>Makefile</literal> in each
    directory of &zebra;.
   </para>
   
   <para>
    To run the configure script type:
    
    <screen>
     ./configure
    </screen>
    
   </para>
   
   <para>
    The configure script attempts to use C compiler specified by
    the <literal>CC</literal> environment variable.
    If this is not set, <literal>cc</literal> or GNU C will be used.
    The <literal>CFLAGS</literal> environment variable holds
    options to be passed to the C compiler. If you're using a
    Bourne-shell compatible shell you may pass something like this:
    
    <screen>
     CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
    </screen>
   </para>
   <para>
    The configure script support various options: you can see what they
    are with
    <screen>
     ./configure --help
    </screen>
   </para>
   
   <para>
    Once the build environment is configured, build the software by
    typing:
    <screen>
     make
    </screen>
   </para>
   
   <para>
    If the build is successful, two executables are created in the
    sub-directory <literal>index</literal>:
    <variablelist>
     
     <varlistentry>
      <term><literal>zebrasrv</literal></term>
      <listitem>
       <para>
        The &acro.z3950; server and search engine.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
     <term><literal>zebraidx</literal></term>
      <listitem>
       <para>
        The administrative indexing tool.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
     <term><literal>index/*.so</literal></term>
      <listitem>
       <para>
        The <literal>.so</literal>-files are &zebra; record filter modules.
        There are modules for reading 
        &acro.marc; (<filename>mod-grs-marc.so</filename>),
        &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc. 
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>

   <note>
    <para>
     Using configure option <literal>--disable-shared</literal> builds
     &zebra; statically and links "in" &zebra; filter code statically, i.e.
     no <literal>.so-files</literal> are generated
    </para>
   </note>

   <para>
    You can now use &zebra;. If you wish to install it system-wide, then
    as root type
    <screen>
     make install
    </screen>
    By default this will install the &zebra; executables in 
    <filename>/usr/local/bin</filename>,
    and the standard configuration files in 
    <filename>/usr/local/share/idzebra-2.0</filename>. If
    shared modules are built, these are installed in
    <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
    You can override this with the <literal>--prefix</literal> option
    to configure.
   </para>
  </section>

  <section id="installation-debian"><title>GNU/Debian</title>
   <section id="installation-debian-linux"><title>GNU/Debian Linux on
   i686 Platform</title>
    <para>
     Index Data provides pre-compiled GNU/Debian i686 Linux packages
     at our Debian package archive, both for
     the Sarge and the Etch release. 
    </para>
    
    <para>
     To install these packages, you need to add two lines to your
     <filename>/etc/apt/sources.list</filename> configuration file,
     either the Sarge sources found at
     <screen>
      deb http://ftp.indexdata.dk/debian sarge main
      deb-src http://ftp.indexdata.dk/debian sarge main
     </screen>
     or the Etch sources from 
     <screen>
      deb http://ftp.indexdata.dk/debian etch main
      deb-src http://ftp.indexdata.dk/debian etch main
     </screen>
     After refreshing the package cache with the command
     <screen>
      apt-get update
     </screen>
     as <literal>root</literal>, the 
     <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
     easily installed issuing
     <screen>
      apt-get install idzebra-2.0 idzebra-2.0-doc
     </screen>
    </para>
   </section>
   
   <section id="installation-debia-nother">
    <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
    <para>
     These <ulink url="&url.idzebra;">&zebra;</ulink>
     packages are specifically compiled for
     GNU/Debian Linux systems. Installation on other 
     GNU/Debian systems is possible by
     re-compilation the Debian way: you need to add only the 
     <literal>deb-src</literal> sources lines to the 
     <filename>/etc/apt/sources.list</filename> configuration file,
     that is either the Sarge sources
     <screen>
      deb-src http://ftp.indexdata.dk/debian sarge main
     </screen>
     or the Etch sources
     <screen>
      deb-src http://ftp.indexdata.dk/debian etch main
     </screen>
     After refreshing the package cache with the command
     <screen>
      apt-get update
      apt-get build-dep idzebra-2.0
     </screen>
     as <literal>root</literal>, the 
     <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
     recompiled and installed issuing
     <screen>
      fakeroot apt-get source --compile idzebra-2.0
     </screen>
     as normal user.
     The compiled GNU/Debian packages can then be
     installed as <literal>root</literal> issuing
     <screen>
      dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
     </screen>
    </para>
   </section>
  </section>

  <section id="installation-win32"><title>WIN32</title>
   <para>The easiest way to install &zebra; on Windows is by downloading
    an installer from 
    <ulink url="&url.idzebra.download.win32;">here</ulink>.
    The installer comes with source too - in case you wish to
    compile &zebra; with different Compiler options.
   </para>
   
   <para>
    &zebra; is shipped with "makefiles" for the NMAKE tool that comes
    with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
    Version 2003 and 2005 has been tested. We expect that zebra compiles
    with version 6 as well.
   </para>
   <para>
    Start a command prompt and switch the sub directory
    <filename>WIN</filename> where the file <filename>makefile</filename>
    is located. Customize the installation by editing the
    <filename>makefile</filename> file (for example by using notepad).
    
    The following summarizes the most important settings in that file:
    
    <variablelist>
     <varlistentry><term><literal>DEBUG</literal></term>
      <listitem><para>
        If set to 1, the software is
        compiled with debugging libraries (code generation is
        multi-threaded debug DLL).
        If set to 0, the software is compiled with release libraries
        (code generation is multi-threaded DLL).
       </para></listitem>
     </varlistentry>
     
     <varlistentry>
      <term><literal>YAZDIR</literal></term>
      <listitem><para>
        Directory of &yaz; source. &zebra;'s makefile expects to find
        <filename>yaz.lib</filename>, <filename>yaz.dll</filename> 
        in <replaceable>yazdir</replaceable><literal>/lib</literal> and
        <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><literal>HAVE_EXPAT</literal>,
       <literal>EXPAT_DIR</literal></term>
      <listitem><para>
        If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
        with <ulink url="&url.expat;">Expat</ulink> support.
        In this configuration, set 
        <literal>ZEBRA_DIR</literal> to the Expat source directory.
        Windows version of Expat can be downloaded from
        <ulink url="&url.expat;">SourceForge</ulink>.
       </para></listitem>
     </varlistentry>
     
     <varlistentry>
      <term><literal>HAVE_ICONV</literal>,
       <literal>ICONV_DIR</literal></term>
       <listitem><para>
        If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
        with iconv support. In this configuration, set 
        <literal>ICONV_DIR</literal> to the iconv source directory.
        Iconv binaries can be downloaded from
        <ulink url="&url.libxml2.download.win32;">this site</ulink>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry>
      <term><literal>BZIP2INCLUDE</literal>,
       <literal>BZIP2LIB</literal>,
       <literal>BZIP2DEF</literal>
      </term>
      <listitem><para>
        Define these symbols if &zebra; is to be compiled with
        <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
       </para></listitem>
     </varlistentry>
     
    </variablelist>
   </para>
   <warning>
    <para>
     The <literal>DEBUG</literal> setting in the makefile for &zebra; must
     be set to the same value as <literal>DEBUG</literal> setting in the
     makefile for &yaz;.
     If not, the &zebra; server/indexer will crash.
    </para>
   </warning>
   <para>
    When satisfied with the settings in the makefile, type
    <screen>
     nmake
    </screen>
   </para>
   <note>
    <para>
     If the <filename>nmake</filename> command is not found on your system
     you probably haven't defined the environment variables required to
     use that tool. To fix that, find and run the batch file
     <filename>vcvars32.bat</filename>. You need to run it from within
     the command prompt or set the environment variables "globally";
     otherwise it doesn't work.
    </para>
   </note>
   <para>
    If you wish to recompile &zebra; - for example if you modify
     settings in the <filename>makefile</filename> you can delete
    object files, etc by running.
    <screen>
     nmake clean
    </screen>
   </para>
   <para>
    The following files are generated upon successful compilation:
    
    <variablelist>
     <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
      <listitem><para>
        The &zebra; indexer.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
      <listitem><para>
        The &zebra; server.
       </para></listitem></varlistentry>
     
    </variablelist>
    
   </para>
  </section>


  <section id="installation-upgrade">
   <title>Upgrading from &zebra; version 1.3.x</title>
   <para>
    &zebra;'s installation directories have changed a bit. In addition,
    the new loadable modules must be defined in the 
    master <filename>zebra.cfg</filename> configuration file. The old
    version 1.3.x configuration options
    <screen>
     # profilePath - where to look for config files
     profilePath: some/local/path:/usr/share/idzebra/tab
    </screen>
    must be changed to 
    <screen>
     # profilePath - where to look for config files
     profilePath: some/local/path:/usr/share/idzebra-2.0/tab

     # modulePath - where to look for loadable zebra modules
     modulePath: /usr/lib/idzebra-2.0/modules
    </screen>
   </para>
   <note>
    <para>
     The internal binary register structures have changed; all &zebra;
     databases must be re-indexed after upgrade.
    </para>
   </note>
   <para>
    The attribute set definition files may no longer contain
    redirection to other fields. 
    For example the following snippet of
    a custom <filename>custom/bib1.att</filename> 
    &acro.bib1; attribute set definition file is no
    longer supported:
    <screen>
     att 1016            Any            1016,4,1005,62
    </screen>
    and should be changed to 
    <screen>
     att 1016            Any
    </screen>
   </para>
   <para>
    Similar behaviour can be expressed in the new release by defining
    a new index <literal>Any:w</literal> in all &acro.grs1;
    <filename>*.abs</filename> record indexing configuration files.
    The above example configuration needs to make the changes
    from version 1.3.x indexing instructions
    <screen>
     xelm /*/alternative  Body-of-text:w,Title:s,Title:w
     xelm /*/title        Body-of-text:w,Title:s,Title:w
    </screen>
    to version 2.0.0 indexing instructions
    <screen>
     xelm /*/alternative  Any:w,Body-of-text:w,Title:s,Title:w
     xelm /*/title        Any:w,Body-of-text:w,Title:s,Title:w
    </screen>
   </para>
   <para>
    It is also possible to map the numerical attribute value  
    <literal>@attr 1=1016</literal> onto another already existing huge
    index, in this example, one could for example use the mapping
    <screen>
     att 1016            Body-of-text
    </screen>
    with equivalent outcome without editing all  &acro.grs1;
    <filename>*.abs</filename> record indexing configuration files.
   </para>

   <para>
    Server installations which use the special
    <literal>&acro.idxpath;</literal> attribute set must add the following
    line to the <filename>zebra.cfg</filename> configuration file:
    <screen>
     attset: idxpath.att
    </screen>
    </para>
  </section>
  
 </chapter>
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document: "zebra.xml"
 sgml-local-catalogs: nil
 sgml-namecase-general:t
 End:
 -->