<!-- $Id: installation.xml,v 1.6 2001/10/24 21:30:47 adam Exp $ -->
 <chapter id="installation"><title>Compilation and Installation</title>
  
 <sect1><title>Introduction</title>
  <para>
   The latest version of the software will generally be found at:
  </para>
  <para>
   <ulink url="http://ftp.indexdata.dk/pub/yaz/">
    http://ftp.indexdata.dk/pub/yaz/</ulink>
  </para>
  <para>
   We have tried our best to keep the software portable, and on many
   platforms, you should be able to compile everything with little or
   no changes.
   So far, the software has been ported to the following platforms with
   little or no difficulties.
   
   <itemizedlist>
    <listitem><para>Unix systems</para>
     <itemizedlist>
      <listitem><para>HP/UX</para></listitem>
      <listitem><para>SunOS/Solaris</para></listitem>
      <listitem><para>DEC Unix</para></listitem>
      <listitem><para>OpenBSD/FreeBSD</para></listitem>
      <listitem><para>Linux</para></listitem>
      <listitem><para>IBM AIX</para></listitem>
      <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
       </para></listitem>
      <listitem><para>SGI/IRIX</para></listitem>
      <listitem><para>DDE Supermax</para></listitem>
     </itemizedlist></listitem>
    <listitem><para>Non-unix systems</para>
     <itemizedlist>
      <listitem><para>Apple Macintosh (using the Codewarrior programming
	environment and the GUSI socket libraries)</para></listitem>
      <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
      <listitem><para>IBM AS/400</para></listitem>
     </itemizedlist></listitem>
   </itemizedlist>
   
  </para>
  <para>
   If you move the software to other platforms, we'd be grateful if you'd
   let us know about it. If you run into difficulties, we will try to help
   if we can, and if you solve the problems, we would be happy to include
   your fixes in the next release. So far, we have mostly avoided
   &num;ifdefs for individual platforms, and we'd like to keep it that
   way as far as it makes sense.
  </para>
  
  <para>
   We maintain a mailing-list for the purpose of announcing new releases and
   bug-fixes, as well as general discussion. Subscribe by sending mail to
   <ulink url="mailto:yaz-request@indexdata.dk">
    yaz-request@indexdata.dk
   </ulink>.
   General questions and problems can be directed at 
   <ulink url="mailto:yaz-help@indexdata.dk">
    yaz-help@indexdata.dk
   </ulink>, or the address given at the top of this document.
  </para>
  
  </sect1>
  <sect1 id="installation.unix"><title>UNIX</title>
   
   <para>
    Note that if your system doesn't have a native ANSI C compiler, you may
    have to acquire one separately. We recommend
    <ulink url="http://gcc.gnu.org">GCC</ulink>.
   </para>
   <para>
    For UNIX, the GNU tools
    <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
    <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
    <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
    is used to generate Makefiles and configure &yaz; for the system.
    You do <emphasis>not</emphasis> these tools unless you're using the
    CVS version of &yaz;.
    Generally it should be sufficient to run configure without options,
    like this:
   </para>
   
   <screen>
    ./configure
   </screen>
   
   <para>
    The configure script attempts to use use the C compiler specified by
    the <literal>CC</literal> environment variable. If not set, GNU C will be
    used if it is available. The <literal>CFLAGS</literal> environment
    variable holds options to be passed to the C compiler. If you're using
    Bourne-compatible shell you may pass something like this to use a
    particular C compiler with optimization enabled:
   </para>
   
   <screen>
    CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
   </screen>
   
   <para>
    To customize &yaz; the configure script also accepts a set of options.
    The most important are:
    
    <variablelist>
     <varlistentry><term><literal>--prefix </literal>path</term>
      <listitem><para>Specifies installation prefix. This is
	only needed if you run <literal>make install</literal> later to
	perform a "system" installation. The prefix is
	<literal>/usr/local</literal> if not specified.
       </para></listitem>
     </varlistentry>
     <varlistentry><term><literal>--enable-tcpd</literal></term>
      <listitem><para>The front end server will be built using Wietse's
        <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
        TCP wrapper library</ulink>. It allows you to allow/deny
        clients depending on IP number. The TCP wrapper library is
        commonly used in Linux/BSD distributions.
       </para></listitem>
     </varlistentry>
     <varlistentry><term><literal>--enable-threads</literal></term>
      <listitem><para>&yaz; will be built using POSIX threads.
	Specifically, <constant>_REENTRANT</constant> will be defined during
	compilation.
       </para></listitem>
     </varlistentry>
    </variablelist>
    
   </para>
   <para>
    When configured, build the software by typing:
    <screen>
     make
    </screen>
    
   </para>
   
   <para>
    The following files are generated by the make process:
    <variablelist>
     <varlistentry><term><filename>lib/libyaz.la</filename></term>
      <listitem><para>
	Main &yaz; library. This is no ordinary library. It's
        a Libtool archive.
        By default, &yaz; creates a static library in 
        <filename>lib/.libs/libyaz.a</filename>.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>lib/libyazthread.la</filename></term>
      <listitem><para>
        When threading is supported/enabled by configure this GNU libtool
        library is created. It includes functions that allows &yaz;
        to use threads.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
      <listitem><para>Test Z39.50 server. 
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>client/yaz-client</filename></term>
      <listitem><para>Z39.50 client for testing the protocol.
       See chapter <link linkend="client">
       YAZ client</link> for more information.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>yaz-config</filename></term>
      <listitem><para>A Bourne-shell script, generate by configure, that
        specifies how external applications should compile - and link with
        &yaz;.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>yaz-comp</filename></term>
      <listitem><para>The ASN.1 compiler for &yaz;. Requires the
	Tcl Shell, <application>tclsh</application>, in
        <literal>PATH</literal> to operate.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>zoom/zoomsh</filename></term>
      <listitem><para>
        A simple shell implemented on top of the 
       <link linkend="zoom">ZOOM</link> functions.
        The shell is a command line application that allows you to enter
        simple commands perform to perform ZOOM operations.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>zoom/zoomtst1</filename>, 
      <filename>zoom/zoomtst2</filename>, ..</term>
      <listitem><para>
        Several small applications that demonstrates the use of ZOOM.
       </para></listitem></varlistentry>
    </variablelist>
    
   </para>
   
   <para>
    If you wish to install &yaz; in system directories such as 
    <filename>/usr/local/bin</filename>,
    <filename>/usr/local/lib</filename> you can type:
   </para>
   
   <screen>
    make install
   </screen>
   
   <para>
    You probably need to have root access in order to perform this.
    You must specify the <literal>--prefix</literal> option for configure if
    you wish to install &yaz; in other directories than the default 
    <filename>/usr/local/</filename>.
   </para>
   
   <para>
    If you wish to perform an un-installation of &yaz; use:
   </para>
   
   <screen>
    make uninstall
   </screen>
   
   <para>
    This will only work if you haven't reconfigured &yaz; (and therefore
    changed installation prefix). Note that uninstall will not
    remove directories created by make install, e.g.
    <filename>/usr/local/include/yaz</filename>.
   </para>
   
  </sect1>
  <sect1 id="installation.win32"><title>WIN32</title>
   
   <para>
    &yaz; is shipped with "makefiles" for the NMAKE tool that comes
    with Microsoft Visual C++. Version 6 has been tested. We expect that
    &yaz; should compile with version 5 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 summarises 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>TCL</literal></term>
      <listitem><para>
	 Specifies the name of the Tcl shell (EXE-file).
	 You do not need setting this or installing Tcl unless you wish
	 to change or add ASN.1 for &yaz;.
       </para></listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    When satisfied with the settings in the makefile type
    <screen>
     nmake
    </screen>
    If command <filename>nmake</filename> 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>
   <para>
    If you wish to recompile &yaz; - 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/yaz.dll</filename></term>
      <listitem><para>
	&yaz; multi-threaded Dynamic Link Library.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>lib/yaz.lib</filename></term>
      <listitem><para>
	Import library for <filename>yaz.dll</filename>.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
      <listitem><para>
        &yaz; Z39.50 client application. It's a WIN32 console application.
        See chapter <link linkend="client">YAZ client</link> for more
        information.
       </para></listitem></varlistentry>
     
     <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
      <listitem><para>
	Z39.50 multi-threaded test/example server. It's a WIN32
        console application.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
      <listitem><para>
        Simple console application implemented on top of the
        <link linkend="zoom">ZOOM</link> functions.
        The application is a command line shell that allows you to enter
        simple commands perform to perform ZOOM operations.
       </para></listitem></varlistentry>

     <varlistentry><term><filename>bin/zoomtst1.exe</filename>, 
      <filename>bin/zoomtst2.exe</filename>, ..</term>
      <listitem><para>
        Several small applications that demonstrates the use of ZOOM.
       </para></listitem></varlistentry>

    </variablelist>
    
   </para>
  </sect1>
 </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: "yaz.xml"
 sgml-local-catalogs: "../../docbook/docbook.cat"
 sgml-namecase-general:t
 End:
 -->
 
