doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.2 2001-07-19 23:29:40 adam Exp $ -->
   2  <chapter><title>Compilation and Installation</title>
   3
   4   <para>
   5    The latest version of the software will generally be found at
   6   </para>
   7   <para>
   8    <ulink url="http://ftp.indexdata.dk/pub/yaz/">
   9     http://ftp.indexdata.dk/pub/yaz/</ulink>
  10   </para>
  11   <para>
  12    We have tried our best to keep the software portable, and on many
  13    platforms, you should be able to compile everything with little or
  14    no changes.
  15    So far, the software has been ported to the following platforms with
  16    little or no difficulties.
  17
  18    <itemizedlist>
  19     <listitem><para>Unix systems</para>
  20      <itemizedlist>
  21       <listitem><para>HP/UX</para></listitem>
  22       <listitem><para>SunOS/Solaris</para></listitem>
  23       <listitem><para>DEC Unix</para></listitem>
  24       <listitem><para>Linux</para></listitem>
  25       <listitem><para>IBM AIX</para></listitem>
  26       <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
  27        </para></listitem>
  28       <listitem><para>SGI/IRIX</para></listitem>
  29       <listitem><para>DDE Supermax</para></listitem>
  30      </itemizedlist></listitem>
  31     <listitem><para>Non-unix systems</para>
  32      <itemizedlist>
  33       <listitem><para>Apple Macintosh (using the Codewarrior programming
  34         environment and the GUSI socket libraries)</para></listitem>
  35       <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
  36       <listitem><para>IBM AS/400</para></listitem>
  37      </itemizedlist></listitem>
  38    </itemizedlist>
  39
  40   </para>
  41   <para>
  42    If you move the software to other platforms, we'd be grateful if you'd
  43    let us know about it. If you run into difficulties, we will try to help
  44    if we can, and if you solve the problems, we would be happy to include
  45    your fixes in the next release. So far, we have mostly avoided
  46    &num;ifdefs for individual platforms, and we'd like to keep it that
  47    way as far as it makes sense.
  48   </para>
  49
  50   <para>
  51    We maintain a mailing-list for the purpose of announcing new releases and
  52    bug-fixes, as well as general discussion. Subscribe by sending mail to
  53    <ulink url="mailto:yaz-request@indexdata.dk">
  54     yaz-request@indexdata.dk
  55    </ulink>.
  56    General questions and problems can be directed at
  57    <ulink url="mailto:yaz-help@indexdata.dk">
  58     yaz-help@indexdata.dk
  59    </ulink>, or the address given at the top of this document.
  60   </para>
  61
  62   <sect1><title>UNIX</title>
  63
  64    <para>
  65     Note that if your system doesn't have a native ANSI C compiler, you may
  66     have to acquire one separately. We recommend gcc.
  67    </para>
  68    <para>
  69     For UNIX we use GNU configure to create Makefiles for &yaz;.
  70     Generally it should be sufficient to run configure without options:
  71    </para>
  72
  73    <screen>
  74     ./configure
  75    </screen>
  76
  77    <para>
  78     The configure script attempts to use use the C compiler specified by
  79     the <literal>CC</literal> environment variable. If not set, GNU C will be
  80     used if it is available. The <literal>CFLAGS</literal> environment
  81     variable holds options to be passed to the C compiler. If you're using
  82     Bourne-compatible shell you may pass something like this to use a
  83     particular C compiler with optimization enabled:
  84    </para>
  85
  86    <screen>
  87     CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
  88    </screen>
  89
  90    <para>
  91     To customize &yaz; the configure script also accepts a set of options.
  92     The most important are:
  93
  94     <variablelist>
  95      <varlistentry><term><literal>--prefix </literal>path</term>
  96       <listitem><para>Specifies installation prefix. This is
  97         only needed if you run <literal>make install</literal> later to
  98         perform a "system" installation. The prefix is
  99         <literal>/usr/local</literal> if not specified.
 100        </para></listitem>
 101      </varlistentry>
 102      <varlistentry>
 103       <term><literal>--enable-comp </literal></term>
 104       <listitem><para> &yaz; will be built using the ASN.1 compiler for &yaz;
 105         (default). If you wish to use the old decoders (in sub directory asn)
 106         use <literal>--disable-comp</literal> instead.
 107        </para></listitem>
 108      </varlistentry>
 109      <varlistentry><term><literal>--enable-threads</literal></term>
 110       <listitem><para>&yaz; will be built using POSIX threads.
 111         Specifically, <constant>_REENTRANT</constant> will be defined during
 112         compilation.
 113        </para></listitem>
 114      </varlistentry>
 115     </variablelist>
 116
 117    </para>
 118    <para>
 119     When configured, build the software by typing:
 120     <screen>
 121      make
 122     </screen>
 123
 124    </para>
 125
 126    <para>
 127     The following files are generated by the make process:
 128     <variablelist>
 129      <varlistentry><term><filename>lib/libyaz.a</filename></term>
 130       <listitem><para>
 131         The &yaz; programmers' library.
 132        </para></listitem></varlistentry>
 133
 134      <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 135       <listitem><para>A test Z39.50 server.
 136        </para></listitem></varlistentry>
 137
 138      <varlistentry><term><filename>client/yaz-client</filename></term>
 139       <listitem><para>A command mode Z39.50 client.
 140        </para></listitem></varlistentry>
 141
 142      <varlistentry><term><filename>yaz-config</filename></term>
 143       <listitem><para>A Bourne-shell script that holds build
 144         settings for &yaz;.
 145        </para></listitem></varlistentry>
 146
 147      <varlistentry><term><filename>yaz-comp</filename></term>
 148       <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 149         Tcl Shell, <application>tclsh</application>, in current path to work.
 150        </para></listitem></varlistentry>
 151     </variablelist>
 152
 153    </para>
 154
 155    <para>
 156     If you wish to install &yaz; in system directories such as
 157     <filename>/usr/local/bin</filename>,
 158     <filename>/usr/local/lib</filename> you can type:
 159    </para>
 160
 161    <screen>
 162     make install
 163    </screen>
 164
 165    <para>
 166     You probably need to have root access in order to perform this.
 167     You must specify the <literal>--prefix</literal> option for configure if
 168     you wish to install &yaz; in other directories than the default
 169     <filename>/usr/local/</filename>.
 170    </para>
 171
 172    <para>
 173     If you wish to perform an un-installation of &yaz; use:
 174    </para>
 175
 176    <screen>
 177     make uninstall
 178    </screen>
 179
 180    <para>
 181     This will only work if you haven't reconfigured &yaz; (and therefore
 182     changed installation prefix). Note that uninstall will not
 183     remove directories created by make install, e.g.
 184     <filename>/usr/local/include/yaz</filename>.
 185    </para>
 186
 187   </sect1>
 188   <sect1><title>WIN32</title>
 189
 190    <para>
 191     &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 192     with Visual C++.
 193
 194     Start an MS-DOS prompt and switch the sub directory
 195     <filename>WIN</filename> where the file <filename>makefile</filename>
 196     is located. Customize the installation by editing the
 197     <filename>makefile</filename> file (for example by using notepad).
 198
 199     The following summarises the most important settings in that file:
 200
 201     <table frame="top"><title>WIN32 makefile settings</title>
 202      <tgroup cols="2">
 203       <thead>
 204        <row>
 205         <entry>Setting</entry>
 206         <entry>Description</entry>
 207        </row>
 208       </thead>
 209       <tbody>
 210
 211        <row>
 212         <entry><literal>NEW_Z3950</literal></entry>
 213         <entry> If 1, the auto-generated decoder/encoders
 214          for Z39.50 as written by the ASN.1 compiler will be used. If 0,
 215          the old decoders for Z39.50 will be used. Note, when 1, the
 216          setting TCL should point to the Tcl shell on your system.
 217         </entry>
 218        </row>
 219
 220        <row>
 221         <entry><literal>DEBUG</literal></entry>
 222         <entry> If set to 1, the software is
 223          compiled with debugging libraries. If set to 0, the software
 224          is compiled with release (non-debugging) libraries.
 225         </entry>
 226        </row>
 227
 228        <row>
 229         <entry><literal>TCL</literal></entry>
 230         <entry> Specifies the name of the Tcl shell (EXE-file).
 231          You do not need setting this or installing Tcl unless you wish
 232          to change or add ASN.1 for &yaz;.
 233         </entry>
 234        </row>
 235
 236       </tbody>
 237      </tgroup>
 238     </table>
 239
 240    </para>
 241    <para>
 242     When satisfied with the settings in the makefile type
 243     <screen>
 244      nmake
 245     </screen>
 246    </para>
 247    <para>
 248     The following files are generated upon successful compilation:
 249
 250     <variablelist>
 251      <varlistentry><term><filename>bin/yaz.dll</filename></term>
 252       <listitem><para>
 253         the multi-threaded &yaz; DLL.
 254        </para></listitem></varlistentry>
 255
 256      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 257       <listitem><para>
 258         A console Z39.50 client application.
 259        </para></listitem></varlistentry>
 260
 261      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 262       <listitem><para>
 263         A console Z39.50 multi threaded server.
 264        </para></listitem></varlistentry>
 265
 266     </variablelist>
 267
 268    </para>
 269   </sect1>
 270  </chapter>
 271
 272  <!-- Keep this comment at the end of the file
 273  Local variables:
 274  mode: sgml
 275  sgml-omittag:t
 276  sgml-shorttag:t
 277  sgml-minimize-attributes:nil
 278  sgml-always-quote-attributes:t
 279  sgml-indent-step:1
 280  sgml-indent-data:t
 281  sgml-parent-document: "yaz.xml"
 282  sgml-local-catalogs: "../../docbook/docbook.cat"
 283  sgml-namecase-general:t
 284  End:
 285  -->
 286