doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.6 2001-10-24 21:30:47 adam Exp $ -->
   2  <chapter id="installation"><title>Compilation and Installation</title>
   3
   4  <sect1><title>Introduction</title>
   5   <para>
   6    The latest version of the software will generally be found at:
   7   </para>
   8   <para>
   9    <ulink url="http://ftp.indexdata.dk/pub/yaz/">
  10     http://ftp.indexdata.dk/pub/yaz/</ulink>
  11   </para>
  12   <para>
  13    We have tried our best to keep the software portable, and on many
  14    platforms, you should be able to compile everything with little or
  15    no changes.
  16    So far, the software has been ported to the following platforms with
  17    little or no difficulties.
  18
  19    <itemizedlist>
  20     <listitem><para>Unix systems</para>
  21      <itemizedlist>
  22       <listitem><para>HP/UX</para></listitem>
  23       <listitem><para>SunOS/Solaris</para></listitem>
  24       <listitem><para>DEC Unix</para></listitem>
  25       <listitem><para>OpenBSD/FreeBSD</para></listitem>
  26       <listitem><para>Linux</para></listitem>
  27       <listitem><para>IBM AIX</para></listitem>
  28       <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
  29        </para></listitem>
  30       <listitem><para>SGI/IRIX</para></listitem>
  31       <listitem><para>DDE Supermax</para></listitem>
  32      </itemizedlist></listitem>
  33     <listitem><para>Non-unix systems</para>
  34      <itemizedlist>
  35       <listitem><para>Apple Macintosh (using the Codewarrior programming
  36         environment and the GUSI socket libraries)</para></listitem>
  37       <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
  38       <listitem><para>IBM AS/400</para></listitem>
  39      </itemizedlist></listitem>
  40    </itemizedlist>
  41
  42   </para>
  43   <para>
  44    If you move the software to other platforms, we'd be grateful if you'd
  45    let us know about it. If you run into difficulties, we will try to help
  46    if we can, and if you solve the problems, we would be happy to include
  47    your fixes in the next release. So far, we have mostly avoided
  48    &num;ifdefs for individual platforms, and we'd like to keep it that
  49    way as far as it makes sense.
  50   </para>
  51
  52   <para>
  53    We maintain a mailing-list for the purpose of announcing new releases and
  54    bug-fixes, as well as general discussion. Subscribe by sending mail to
  55    <ulink url="mailto:yaz-request@indexdata.dk">
  56     yaz-request@indexdata.dk
  57    </ulink>.
  58    General questions and problems can be directed at
  59    <ulink url="mailto:yaz-help@indexdata.dk">
  60     yaz-help@indexdata.dk
  61    </ulink>, or the address given at the top of this document.
  62   </para>
  63
  64   </sect1>
  65   <sect1 id="installation.unix"><title>UNIX</title>
  66
  67    <para>
  68     Note that if your system doesn't have a native ANSI C compiler, you may
  69     have to acquire one separately. We recommend
  70     <ulink url="http://gcc.gnu.org">GCC</ulink>.
  71    </para>
  72    <para>
  73     For UNIX, the GNU tools
  74     <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
  75     <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
  76     <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
  77     is used to generate Makefiles and configure &yaz; for the system.
  78     You do <emphasis>not</emphasis> these tools unless you're using the
  79     CVS version of &yaz;.
  80     Generally it should be sufficient to run configure without options,
  81     like this:
  82    </para>
  83
  84    <screen>
  85     ./configure
  86    </screen>
  87
  88    <para>
  89     The configure script attempts to use use the C compiler specified by
  90     the <literal>CC</literal> environment variable. If not set, GNU C will be
  91     used if it is available. The <literal>CFLAGS</literal> environment
  92     variable holds options to be passed to the C compiler. If you're using
  93     Bourne-compatible shell you may pass something like this to use a
  94     particular C compiler with optimization enabled:
  95    </para>
  96
  97    <screen>
  98     CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
  99    </screen>
 100
 101    <para>
 102     To customize &yaz; the configure script also accepts a set of options.
 103     The most important are:
 104
 105     <variablelist>
 106      <varlistentry><term><literal>--prefix </literal>path</term>
 107       <listitem><para>Specifies installation prefix. This is
 108         only needed if you run <literal>make install</literal> later to
 109         perform a "system" installation. The prefix is
 110         <literal>/usr/local</literal> if not specified.
 111        </para></listitem>
 112      </varlistentry>
 113      <varlistentry><term><literal>--enable-tcpd</literal></term>
 114       <listitem><para>The front end server will be built using Wietse's
 115         <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
 116         TCP wrapper library</ulink>. It allows you to allow/deny
 117         clients depending on IP number. The TCP wrapper library is
 118         commonly used in Linux/BSD distributions.
 119        </para></listitem>
 120      </varlistentry>
 121      <varlistentry><term><literal>--enable-threads</literal></term>
 122       <listitem><para>&yaz; will be built using POSIX threads.
 123         Specifically, <constant>_REENTRANT</constant> will be defined during
 124         compilation.
 125        </para></listitem>
 126      </varlistentry>
 127     </variablelist>
 128
 129    </para>
 130    <para>
 131     When configured, build the software by typing:
 132     <screen>
 133      make
 134     </screen>
 135
 136    </para>
 137
 138    <para>
 139     The following files are generated by the make process:
 140     <variablelist>
 141      <varlistentry><term><filename>lib/libyaz.la</filename></term>
 142       <listitem><para>
 143         Main &yaz; library. This is no ordinary library. It's
 144         a Libtool archive.
 145         By default, &yaz; creates a static library in
 146         <filename>lib/.libs/libyaz.a</filename>.
 147        </para></listitem></varlistentry>
 148
 149      <varlistentry><term><filename>lib/libyazthread.la</filename></term>
 150       <listitem><para>
 151         When threading is supported/enabled by configure this GNU libtool
 152         library is created. It includes functions that allows &yaz;
 153         to use threads.
 154        </para></listitem></varlistentry>
 155
 156      <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 157       <listitem><para>Test Z39.50 server.
 158        </para></listitem></varlistentry>
 159
 160      <varlistentry><term><filename>client/yaz-client</filename></term>
 161       <listitem><para>Z39.50 client for testing the protocol.
 162        See chapter <link linkend="client">
 163        YAZ client</link> for more information.
 164        </para></listitem></varlistentry>
 165
 166      <varlistentry><term><filename>yaz-config</filename></term>
 167       <listitem><para>A Bourne-shell script, generate by configure, that
 168         specifies how external applications should compile - and link with
 169         &yaz;.
 170        </para></listitem></varlistentry>
 171
 172      <varlistentry><term><filename>yaz-comp</filename></term>
 173       <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 174         Tcl Shell, <application>tclsh</application>, in
 175         <literal>PATH</literal> to operate.
 176        </para></listitem></varlistentry>
 177
 178      <varlistentry><term><filename>zoom/zoomsh</filename></term>
 179       <listitem><para>
 180         A simple shell implemented on top of the
 181        <link linkend="zoom">ZOOM</link> functions.
 182         The shell is a command line application that allows you to enter
 183         simple commands perform to perform ZOOM operations.
 184        </para></listitem></varlistentry>
 185
 186      <varlistentry><term><filename>zoom/zoomtst1</filename>,
 187       <filename>zoom/zoomtst2</filename>, ..</term>
 188       <listitem><para>
 189         Several small applications that demonstrates the use of ZOOM.
 190        </para></listitem></varlistentry>
 191     </variablelist>
 192
 193    </para>
 194
 195    <para>
 196     If you wish to install &yaz; in system directories such as
 197     <filename>/usr/local/bin</filename>,
 198     <filename>/usr/local/lib</filename> you can type:
 199    </para>
 200
 201    <screen>
 202     make install
 203    </screen>
 204
 205    <para>
 206     You probably need to have root access in order to perform this.
 207     You must specify the <literal>--prefix</literal> option for configure if
 208     you wish to install &yaz; in other directories than the default
 209     <filename>/usr/local/</filename>.
 210    </para>
 211
 212    <para>
 213     If you wish to perform an un-installation of &yaz; use:
 214    </para>
 215
 216    <screen>
 217     make uninstall
 218    </screen>
 219
 220    <para>
 221     This will only work if you haven't reconfigured &yaz; (and therefore
 222     changed installation prefix). Note that uninstall will not
 223     remove directories created by make install, e.g.
 224     <filename>/usr/local/include/yaz</filename>.
 225    </para>
 226
 227   </sect1>
 228   <sect1 id="installation.win32"><title>WIN32</title>
 229
 230    <para>
 231     &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 232     with Microsoft Visual C++. Version 6 has been tested. We expect that
 233     &yaz; should compile with version 5 as well.
 234    </para>
 235    <para>
 236     Start a command prompt and switch the sub directory
 237     <filename>WIN</filename> where the file <filename>makefile</filename>
 238     is located. Customize the installation by editing the
 239     <filename>makefile</filename> file (for example by using notepad).
 240
 241     The following summarises the most important settings in that file:
 242
 243     <variablelist>
 244      <varlistentry><term><literal>DEBUG</literal></term>
 245       <listitem><para>
 246          If set to 1, the software is
 247          compiled with debugging libraries (code generation is
 248          multi-threaded debug DLL).
 249          If set to 0, the software is compiled with release libraries
 250          (code generation is multi-threaded DLL).
 251        </para></listitem>
 252      </varlistentry>
 253      <varlistentry><term><literal>TCL</literal></term>
 254       <listitem><para>
 255          Specifies the name of the Tcl shell (EXE-file).
 256          You do not need setting this or installing Tcl unless you wish
 257          to change or add ASN.1 for &yaz;.
 258        </para></listitem>
 259      </varlistentry>
 260     </variablelist>
 261    </para>
 262    <para>
 263     When satisfied with the settings in the makefile type
 264     <screen>
 265      nmake
 266     </screen>
 267     If command <filename>nmake</filename> is not found on your system
 268     you probably haven't defined the environment variables required to
 269     use that tool. To fix that, find and run the batch file
 270    <filename>vcvars32.bat</filename>. You need to run it from within
 271     the command prompt or set the environment variables "globally";
 272     otherwise it doesn't work.
 273    </para>
 274    <para>
 275     If you wish to recompile &yaz; - for example if you modify
 276     settings in the <filename>makefile</filename> you can delete
 277     object files, etc by running.
 278     <screen>
 279      nmake clean
 280     </screen>
 281    </para>
 282    <para>
 283     The following files are generated upon successful compilation:
 284
 285     <variablelist>
 286      <varlistentry><term><filename>bin/yaz.dll</filename></term>
 287       <listitem><para>
 288         &yaz; multi-threaded Dynamic Link Library.
 289        </para></listitem></varlistentry>
 290
 291      <varlistentry><term><filename>lib/yaz.lib</filename></term>
 292       <listitem><para>
 293         Import library for <filename>yaz.dll</filename>.
 294        </para></listitem></varlistentry>
 295
 296      <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
 297       <listitem><para>
 298         &yaz; Z39.50 client application. It's a WIN32 console application.
 299         See chapter <link linkend="client">YAZ client</link> for more
 300         information.
 301        </para></listitem></varlistentry>
 302
 303      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 304       <listitem><para>
 305         Z39.50 multi-threaded test/example server. It's a WIN32
 306         console application.
 307        </para></listitem></varlistentry>
 308
 309      <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
 310       <listitem><para>
 311         Simple console application implemented on top of the
 312         <link linkend="zoom">ZOOM</link> functions.
 313         The application is a command line shell that allows you to enter
 314         simple commands perform to perform ZOOM operations.
 315        </para></listitem></varlistentry>
 316
 317      <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
 318       <filename>bin/zoomtst2.exe</filename>, ..</term>
 319       <listitem><para>
 320         Several small applications that demonstrates the use of ZOOM.
 321        </para></listitem></varlistentry>
 322
 323     </variablelist>
 324
 325    </para>
 326   </sect1>
 327  </chapter>
 328
 329  <!-- Keep this comment at the end of the file
 330  Local variables:
 331  mode: sgml
 332  sgml-omittag:t
 333  sgml-shorttag:t
 334  sgml-minimize-attributes:nil
 335  sgml-always-quote-attributes:t
 336  sgml-indent-step:1
 337  sgml-indent-data:t
 338  sgml-parent-document: "yaz.xml"
 339  sgml-local-catalogs: "../../docbook/docbook.cat"
 340  sgml-namecase-general:t
 341  End:
 342  -->
 343