doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.5 2001-10-24 20:12:36 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 the TCP
 115         wrapper library. It allows you to disallow/deny clients depending
 116         on IP.
 117        </para></listitem>
 118      </varlistentry>
 119      <varlistentry><term><literal>--enable-threads</literal></term>
 120       <listitem><para>&yaz; will be built using POSIX threads.
 121         Specifically, <constant>_REENTRANT</constant> will be defined during
 122         compilation.
 123        </para></listitem>
 124      </varlistentry>
 125     </variablelist>
 126
 127    </para>
 128    <para>
 129     When configured, build the software by typing:
 130     <screen>
 131      make
 132     </screen>
 133
 134    </para>
 135
 136    <para>
 137     The following files are generated by the make process:
 138     <variablelist>
 139      <varlistentry><term><filename>lib/libyaz.la</filename></term>
 140       <listitem><para>
 141         The main &yaz; library. This is no ordinary library. It's
 142         a Libtool archive.
 143         By default, &yaz; creates a static library in
 144         <filename>lib/.libs/libyaz.a</filename>.
 145        </para></listitem></varlistentry>
 146
 147      <varlistentry><term><filename>lib/libyazthread.la</filename></term>
 148       <listitem><para>
 149         When threading is supported/enabled by configure this GNU libtool
 150         library is created. It include functions that allows &yaz;
 151         to use threads.
 152        </para></listitem></varlistentry>
 153
 154      <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 155       <listitem><para>A test Z39.50 server.
 156        </para></listitem></varlistentry>
 157
 158      <varlistentry><term><filename>client/yaz-client</filename></term>
 159       <listitem><para>A YAZ Z39.50 client. See chapter <link linkend="client">
 160        YAZ client</link> for more information.
 161        </para></listitem></varlistentry>
 162
 163      <varlistentry><term><filename>yaz-config</filename></term>
 164       <listitem><para>A Bourne-shell script, generate by configure, that
 165         specifies how external applications should compile - and link with
 166         &yaz;.
 167        </para></listitem></varlistentry>
 168
 169      <varlistentry><term><filename>yaz-comp</filename></term>
 170       <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 171         Tcl Shell, <application>tclsh</application>, in
 172         <literal>PATH</literal> to operate.
 173        </para></listitem></varlistentry>
 174
 175      <varlistentry><term><filename>zoom/zoomsh</filename></term>
 176       <listitem><para>
 177         A simple shell implemented on top of the
 178        <link linkend="zoom">ZOOM</link> functions.
 179         The shell is a command line application that allows you to enter
 180         simple commands perform to perform ZOOM operations.
 181        </para></listitem></varlistentry>
 182
 183      <varlistentry><term><filename>zoom/zoomtst1</filename>,
 184       <filename>zoom/zoomtst2</filename>, ..</term>
 185       <listitem><para>
 186         Several small applications that demonstrates the use of ZOOM.
 187        </para></listitem></varlistentry>
 188     </variablelist>
 189
 190    </para>
 191
 192    <para>
 193     If you wish to install &yaz; in system directories such as
 194     <filename>/usr/local/bin</filename>,
 195     <filename>/usr/local/lib</filename> you can type:
 196    </para>
 197
 198    <screen>
 199     make install
 200    </screen>
 201
 202    <para>
 203     You probably need to have root access in order to perform this.
 204     You must specify the <literal>--prefix</literal> option for configure if
 205     you wish to install &yaz; in other directories than the default
 206     <filename>/usr/local/</filename>.
 207    </para>
 208
 209    <para>
 210     If you wish to perform an un-installation of &yaz; use:
 211    </para>
 212
 213    <screen>
 214     make uninstall
 215    </screen>
 216
 217    <para>
 218     This will only work if you haven't reconfigured &yaz; (and therefore
 219     changed installation prefix). Note that uninstall will not
 220     remove directories created by make install, e.g.
 221     <filename>/usr/local/include/yaz</filename>.
 222    </para>
 223
 224   </sect1>
 225   <sect1 id="installation.win32"><title>WIN32</title>
 226
 227    <para>
 228     &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 229     with Microsoft Visual C++. Version 6 has been tested. We expect that
 230     &yaz; should compile with version 5 as well.
 231    </para>
 232    <para>
 233     Start a command prompt and switch the sub directory
 234     <filename>WIN</filename> where the file <filename>makefile</filename>
 235     is located. Customize the installation by editing the
 236     <filename>makefile</filename> file (for example by using notepad).
 237
 238     The following summarises the most important settings in that file:
 239
 240     <variablelist>
 241      <varlistentry><term><literal>DEBUG</literal></term>
 242       <listitem><para>
 243          If set to 1, the software is
 244          compiled with debugging libraries (code generation is
 245          multi-threaded debug DLL).
 246          If set to 0, the software is compiled with release libraries
 247          (code generation is multi-threaded DLL).
 248        </para></listitem>
 249      </varlistentry>
 250      <varlistentry><term><literal>TCL</literal></term>
 251       <listitem><para>
 252          Specifies the name of the Tcl shell (EXE-file).
 253          You do not need setting this or installing Tcl unless you wish
 254          to change or add ASN.1 for &yaz;.
 255        </para></listitem>
 256      </varlistentry>
 257     </variablelist>
 258    </para>
 259    <para>
 260     When satisfied with the settings in the makefile type
 261     <screen>
 262      nmake
 263     </screen>
 264     If command <filename>nmake</filename> is not found on your system
 265     you probably haven't defined the environment variables required to
 266     use that tool. To fix that, find and run the batch file
 267    <filename>vcvars32.bat</filename>. You need to run it from within
 268     the command prompt or set the environment variables "globally";
 269     otherwise it doesn't work.
 270    </para>
 271    <para>
 272     If you wish to recompile &yaz; - for example if you modify
 273     settings in the <filename>makefile</filename> you can delete
 274     object files, etc by running.
 275     <screen>
 276      nmake clean
 277     </screen>
 278    </para>
 279    <para>
 280     The following files are generated upon successful compilation:
 281
 282     <variablelist>
 283      <varlistentry><term><filename>bin/yaz.dll</filename></term>
 284       <listitem><para>
 285         The multi-threaded &yaz; Dynamic Link Library.
 286        </para></listitem></varlistentry>
 287
 288      <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
 289       <listitem><para>
 290         The &yaz; Z39.50 client application. It's a WIN32 console application.
 291         See chapter <link linkend="client">YAZ client</link> for more
 292         information.
 293        </para></listitem></varlistentry>
 294
 295      <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 296       <listitem><para>
 297         The example/test Z39.50 multi threaded server. It's a WIN32
 298         console application.
 299        </para></listitem></varlistentry>
 300
 301      <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
 302       <listitem><para>
 303         A simple console application implemented on top of the
 304         <link linkend="zoom">ZOOM</link> functions.
 305         The application is a command line shell that allows you to enter
 306         simple commands perform to perform ZOOM operations.
 307        </para></listitem></varlistentry>
 308
 309      <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
 310       <filename>bin/zoomtst2.exe</filename>, ..</term>
 311       <listitem><para>
 312         Several small applications that demonstrates the use of ZOOM.
 313        </para></listitem></varlistentry>
 314
 315     </variablelist>
 316
 317    </para>
 318   </sect1>
 319  </chapter>
 320
 321  <!-- Keep this comment at the end of the file
 322  Local variables:
 323  mode: sgml
 324  sgml-omittag:t
 325  sgml-shorttag:t
 326  sgml-minimize-attributes:nil
 327  sgml-always-quote-attributes:t
 328  sgml-indent-step:1
 329  sgml-indent-data:t
 330  sgml-parent-document: "yaz.xml"
 331  sgml-local-catalogs: "../../docbook/docbook.cat"
 332  sgml-namecase-general:t
 333  End:
 334  -->
 335