doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.4 2001-10-24 12:50:44 adam Exp $ -->
   2  <chapter id="installation"><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 id="installation.unix"><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><term><literal>--enable-tcpd</literal></term>
 103       <listitem><para>The front end server will be built using the TCP
 104         wrapper library. It allows you to disallow/deny clients depending
 105         on IP.
 106        </para></listitem>
 107      </varlistentry>
 108      <varlistentry><term><literal>--enable-threads</literal></term>
 109       <listitem><para>&yaz; will be built using POSIX threads.
 110         Specifically, <constant>_REENTRANT</constant> will be defined during
 111         compilation.
 112        </para></listitem>
 113      </varlistentry>
 114     </variablelist>
 115
 116    </para>
 117    <para>
 118     When configured, build the software by typing:
 119     <screen>
 120      make
 121     </screen>
 122
 123    </para>
 124
 125    <para>
 126     The following files are generated by the make process:
 127     <variablelist>
 128      <varlistentry><term><filename>lib/libyaz.a</filename></term>
 129       <listitem><para>
 130         The &yaz; programmers' library.
 131        </para></listitem></varlistentry>
 132
 133      <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 134       <listitem><para>A test Z39.50 server.
 135        </para></listitem></varlistentry>
 136
 137      <varlistentry><term><filename>client/yaz-client</filename></term>
 138       <listitem><para>A command mode Z39.50 client.
 139        </para></listitem></varlistentry>
 140
 141      <varlistentry><term><filename>yaz-config</filename></term>
 142       <listitem><para>A Bourne-shell script that holds build
 143         settings for &yaz;.
 144        </para></listitem></varlistentry>
 145
 146      <varlistentry><term><filename>yaz-comp</filename></term>
 147       <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 148         Tcl Shell, <application>tclsh</application>, in current path to work.
 149        </para></listitem></varlistentry>
 150     </variablelist>
 151
 152    </para>
 153
 154    <para>
 155     If you wish to install &yaz; in system directories such as
 156     <filename>/usr/local/bin</filename>,
 157     <filename>/usr/local/lib</filename> you can type:
 158    </para>
 159
 160    <screen>
 161     make install
 162    </screen>
 163
 164    <para>
 165     You probably need to have root access in order to perform this.
 166     You must specify the <literal>--prefix</literal> option for configure if
 167     you wish to install &yaz; in other directories than the default
 168     <filename>/usr/local/</filename>.
 169    </para>
 170
 171    <para>
 172     If you wish to perform an un-installation of &yaz; use:
 173    </para>
 174
 175    <screen>
 176     make uninstall
 177    </screen>
 178
 179    <para>
 180     This will only work if you haven't reconfigured &yaz; (and therefore
 181     changed installation prefix). Note that uninstall will not
 182     remove directories created by make install, e.g.
 183     <filename>/usr/local/include/yaz</filename>.
 184    </para>
 185
 186   </sect1>
 187   <sect1 id="installation.win32"><title>WIN32</title>
 188
 189    <para>
 190     &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 191     with Visual C++.
 192
 193     Start an MS-DOS prompt and switch the sub directory
 194     <filename>WIN</filename> where the file <filename>makefile</filename>
 195     is located. Customize the installation by editing the
 196     <filename>makefile</filename> file (for example by using notepad).
 197
 198     The following summarises the most important settings in that file:
 199
 200     <table frame="top"><title>WIN32 makefile settings</title>
 201      <tgroup cols="2">
 202       <thead>
 203        <row>
 204         <entry>Setting</entry>
 205         <entry>Description</entry>
 206        </row>
 207       </thead>
 208       <tbody>
 209        <row>
 210         <entry><literal>DEBUG</literal></entry>
 211         <entry> If set to 1, the software is
 212          compiled with debugging libraries. If set to 0, the software
 213          is compiled with release (non-debugging) libraries.
 214         </entry>
 215        </row>
 216
 217        <row>
 218         <entry><literal>TCL</literal></entry>
 219         <entry> Specifies the name of the Tcl shell (EXE-file).
 220          You do not need setting this or installing Tcl unless you wish
 221          to change or add ASN.1 for &yaz;.
 222         </entry>
 223        </row>
 224
 225       </tbody>
 226      </tgroup>
 227     </table>
 228
 229    </para>
 230    <para>
 231     When satisfied with the settings in the makefile type
 232     <screen>
 233      nmake
 234     </screen>
 235    </para>
 236    <para>
 237     The following files are generated upon successful compilation:
 238
 239     <variablelist>
 240      <varlistentry><term><filename>bin/yaz.dll</filename></term>
 241       <listitem><para>
 242         the multi-threaded &yaz; DLL.
 243        </para></listitem></varlistentry>
 244
 245      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 246       <listitem><para>
 247         A console Z39.50 client application.
 248        </para></listitem></varlistentry>
 249
 250      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 251       <listitem><para>
 252         A console Z39.50 multi threaded server.
 253        </para></listitem></varlistentry>
 254
 255     </variablelist>
 256
 257    </para>
 258   </sect1>
 259  </chapter>
 260
 261  <!-- Keep this comment at the end of the file
 262  Local variables:
 263  mode: sgml
 264  sgml-omittag:t
 265  sgml-shorttag:t
 266  sgml-minimize-attributes:nil
 267  sgml-always-quote-attributes:t
 268  sgml-indent-step:1
 269  sgml-indent-data:t
 270  sgml-parent-document: "yaz.xml"
 271  sgml-local-catalogs: "../../docbook/docbook.cat"
 272  sgml-namecase-general:t
 273  End:
 274  -->
 275