doc/installation.xml

   1 <!-- $Id: installation.xml,v 1.15 2003-02-18 20:21:22 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>BSDs: FreeBSD, OpenBSD, NetBSD</para></listitem>
  26        <listitem><para>MAC OSX</para></listitem>
  27        <listitem><para>Linux</para></listitem>
  28        <listitem><para>IBM AIX</para></listitem>
  29        <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
  30         </para></listitem>
  31        <listitem><para>SGI/IRIX</para></listitem>
  32        <listitem><para>DDE Supermax</para></listitem>
  33       </itemizedlist></listitem>
  34      <listitem><para>Non-unix systems</para>
  35       <itemizedlist>
  36        <listitem><para>Apple Macintosh (using the Codewarrior programming
  37          environment and the GUSI socket libraries)</para></listitem>
  38        <listitem><para>MS Windows 95/98/NT/2K/XP (Win32)</para></listitem>
  39        <listitem><para>IBM AS/400</para></listitem>
  40       </itemizedlist></listitem>
  41     </itemizedlist>
  42
  43    </para>
  44
  45    <para>
  46     If you move the software to other platforms, we'd be grateful if you'd
  47     let us know about it. If you run into difficulties, we will try to help
  48     if we can, and if you solve the problems, we would be happy to include
  49     your fixes in the next release. So far, we have mostly avoided
  50     <literal>&num;ifdefs</literal> for individual platforms, and we'd
  51     like to keep it that way as far as it makes sense.
  52    </para>
  53
  54    <para>
  55     We maintain a mailing-list for the purpose of announcing new releases and
  56     bug-fixes, as well as general discussion. Subscribe by sending mail to
  57     <ulink url="mailto:yaz-request@indexdata.dk">
  58      yaz-request@indexdata.dk
  59     </ulink> or fill-in the form
  60     <ulink url="http://www.indexdata.dk/mailman/listinfo/yazlist">
  61      here</ulink>.
  62     General questions and problems can be directed at
  63     <ulink url="mailto:yaz-help@indexdata.dk">
  64      yaz-help@indexdata.dk
  65     </ulink>, or the address given at the top of this document.
  66    </para>
  67
  68   </sect1>
  69   <sect1 id="installation.unix"><title>UNIX</title>
  70
  71    <para>
  72     We provide
  73     <ulink url="http://www.debian.org/">Debian GNU/Linux</ulink>
  74     and
  75     <ulink url="http://www.redhat.com/">Redhat</ulink> packages for &yaz;.
  76     Only i386 binary packages are available. You should be able to
  77     create packages for other CPU's by building them from the source
  78     package.
  79    </para>
  80
  81    <sect2 id="installation.source.unix">
  82     <title>Compiling from source on Unix</title>
  83
  84     <para>
  85      Note that if your system doesn't have a native ANSI C compiler, you may
  86      have to acquire one separately. We recommend
  87      <ulink url="http://gcc.gnu.org/">GCC</ulink>.
  88     </para>
  89
  90     <para>
  91      If you wish to use character set conversion facilities in &yaz; or if you
  92      are compiling &yaz; for use with Zebra it is a good idea to ensure that
  93      the iconv library is installed. Some Unixes today already have it
  94      - if not, we suggest
  95      <ulink url="http://www.gnu.org/software/libiconv/">GNU iconv</ulink>.
  96     </para>
  97
  98     <para>
  99      The XML C library <ulink url="http://www.xmlsoft.org/">libxml2</ulink>
 100      is required if &yaz; is to support SRW (and SOAP).
 101      This library is very portable and should compile out-of-the
 102      box on virtually all Unix platforms. It is available in binary
 103      forms for Linux and others.
 104     </para>
 105
 106     <para>
 107      The GNU tools
 108      <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
 109      <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
 110      <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
 111      are used to generate Makefiles and configure &yaz; for the system.
 112      You do <emphasis>not</emphasis> these tools unless you're using the
 113      CVS version of &yaz;.
 114     </para>
 115
 116     <para>
 117      The CQL parser for &yaz; is built using
 118      GNU <ulink url="http://www.gnu.org/software/bison/">Bison</ulink>.
 119      This tool is only needed if you're using the CVS version of &yaz;.
 120     </para>
 121
 122     <para>
 123      &yaz; includes a tiny ASN.1 compiler. This compiler is
 124      written in <ulink url="http://www.tcl.tk/">Tcl</ulink>.
 125      But as for Bison you do not need it unless you're using CVS
 126      version of &yaz; or you're using the compiler to built own codecs
 127      for private ASN.1.
 128     </para>
 129
 130     <para>
 131      Generally it should be sufficient to run configure without options,
 132      like this:
 133     </para>
 134
 135     <screen>
 136      ./configure
 137     </screen>
 138
 139     <para>
 140      The configure script attempts to use use the C compiler specified by
 141      the <literal>CC</literal> environment variable. If not set, GNU C will be
 142      used if it is available. The <literal>CFLAGS</literal> environment
 143      variable holds options to be passed to the C compiler. If you're using
 144      Bourne-compatible shell you may pass something like this to use a
 145      particular C compiler with optimization enabled:
 146     </para>
 147
 148     <screen>
 149      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
 150     </screen>
 151
 152     <para>
 153      To customize &yaz;, the configure script also accepts a set of options.
 154      The most important are:
 155
 156      <variablelist>
 157       <varlistentry><term>
 158         <literal>--prefix</literal>=<replaceable>prefix</replaceable></term>
 159        <listitem><para>Specifies installation prefix for &yaz;. This is
 160          only needed if you run <literal>make install</literal> later to
 161          perform a "system" installation. The prefix is
 162          <literal>/usr/local</literal> if not specified.
 163         </para></listitem>
 164       </varlistentry>
 165       <varlistentry><term><literal>--enable-tcpd</literal></term>
 166        <listitem><para>The front end server will be built using Wietse's
 167          <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
 168           TCP wrapper library</ulink>. It allows you to allow/deny
 169          clients depending on IP number. The TCP wrapper library is
 170          often used in Linux/BSD distributions.
 171          See
 172          <citerefentry>
 173           <refentrytitle>hosts_access</refentrytitle>
 174           <manvolnum>5</manvolnum>
 175          </citerefentry>
 176          and
 177          <citerefentry>
 178           <refentrytitle>tcpd</refentrytitle>
 179           <manvolnum>8</manvolnum>
 180          </citerefentry>.
 181         </para></listitem>
 182       </varlistentry>
 183
 184       <varlistentry><term><literal>--enable-threads</literal></term>
 185        <listitem><para>&yaz; will be built using POSIX threads.
 186         Specifically, <constant>_REENTRANT</constant> will be defined during
 187          compilation.
 188         </para></listitem>
 189       </varlistentry>
 190
 191       <varlistentry><term><literal>--enable-shared</literal></term>
 192        <listitem><para>The make process will create shared
 193          libraries (also known as shared objects <filename>.so</filename>).
 194          By default, no shared libraries are created -
 195          equivalent to <literal>--disable-shared</literal>.
 196         </para></listitem>
 197       </varlistentry>
 198
 199       <varlistentry><term><literal>--disable-shared</literal></term>
 200        <listitem><para>The make process will not create
 201          static libraries (<filename>.a</filename>).
 202          By default, static libraries are created -
 203          equivalent to <literal>--enable-static</literal>.
 204         </para></listitem>
 205       </varlistentry>
 206
 207       <varlistentry><term>
 208         <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
 209        </term>
 210        <listitem><para>Compile &yaz; with iconv library in directory
 211          <replaceable>prefix</replaceable>. By default configure will
 212          search for iconv on your system. Use this option if it
 213          doesn't find iconv. Alternatively you can use
 214          <literal>--without-iconv</literal> to force &yaz; not to use
 215          iconv.
 216         </para></listitem>
 217       </varlistentry>
 218
 219       <varlistentry><term>
 220         <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
 221        </term>
 222        <listitem><para>Compile &yaz; with
 223          <ulink url="http://www.xmlsoft.org/">libxml2</ulink> in directory
 224          <replaceable>prefix</replaceable>.
 225          Use this option if you want SOAP support.
 226          By default configure will
 227          search for libxml2 on your system. Use this option if it
 228          doesn't find libxml2. Alternatively you can use
 229          <literal>--without-xml2</literal> to force &yaz; not to use
 230          libxml2.
 231         </para></listitem>
 232       </varlistentry>
 233
 234       <varlistentry><term>
 235         <literal>--with-openssl</literal>[=<replaceable>prefix</replaceable>]
 236        </term>
 237        <listitem><para>&yaz; will be linked with the OpenSSL libraries and
 238          an SSL COMSTACK will be provided. Note that SSL support is still
 239          experimental.
 240         </para></listitem>
 241       </varlistentry>
 242
 243      </variablelist>
 244
 245     </para>
 246     <para>
 247      When configured, build the software by typing:
 248      <screen>
 249       make
 250      </screen>
 251     </para>
 252
 253     <para>
 254      The following files are generated by the make process:
 255      <variablelist>
 256       <varlistentry><term><filename>lib/libyaz.la</filename></term>
 257        <listitem><para>
 258          Main &yaz; library. This is no ordinary library. It's
 259          a Libtool archive.
 260          By default, &yaz; creates a static library in
 261          <filename>lib/.libs/libyaz.a</filename>.
 262         </para></listitem></varlistentry>
 263
 264       <varlistentry><term><filename>lib/libyazthread.la</filename></term>
 265        <listitem><para>
 266          When threading is supported/enabled by configure this Libtool
 267          library is created. It includes functions that allows &yaz;
 268          to use threads.
 269         </para></listitem></varlistentry>
 270
 271       <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 272        <listitem><para>Test Z39.50 server.
 273         </para></listitem></varlistentry>
 274
 275       <varlistentry><term><filename>client/yaz-client</filename></term>
 276        <listitem><para>Z39.50 client for testing the protocol.
 277          See chapter <link linkend="client">
 278           YAZ client</link> for more information.
 279         </para></listitem></varlistentry>
 280
 281       <varlistentry><term><filename>yaz-config</filename></term>
 282        <listitem><para>A Bourne-shell script, generated by configure, that
 283          specifies how external applications should compile - and link with
 284          &yaz;.
 285         </para></listitem></varlistentry>
 286
 287       <varlistentry><term><filename>yaz-comp</filename></term>
 288        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 289          Tcl Shell, <application>tclsh</application>, in
 290          <literal>PATH</literal> to operate.
 291         </para></listitem></varlistentry>
 292
 293       <varlistentry><term><filename>zoom/zoomsh</filename></term>
 294        <listitem><para>
 295          A simple shell implemented on top of the
 296          <link linkend="zoom">ZOOM</link> functions.
 297          The shell is a command line application that allows you to enter
 298          simple commands to perform ZOOM operations.
 299         </para></listitem></varlistentry>
 300
 301       <varlistentry><term><filename>zoom/zoomtst1</filename>,
 302         <filename>zoom/zoomtst2</filename>, ..</term>
 303        <listitem><para>
 304          Several small applications that demonstrates the ZOOM API.
 305         </para></listitem></varlistentry>
 306      </variablelist>
 307
 308     </para>
 309
 310     <para>
 311      If you wish to install &yaz; in system directories
 312      <filename>/usr/local/bin</filename>,
 313      <filename>/usr/local/lib</filename> .. etc, you can type:
 314     </para>
 315
 316     <screen>
 317      make install
 318     </screen>
 319
 320     <para>
 321      You probably need to have root access in order to perform this.
 322      You must specify the <literal>--prefix</literal> option for configure if
 323      you wish to install &yaz; in other directories than the default
 324      <filename>/usr/local/</filename>.
 325     </para>
 326
 327     <para>
 328      If you wish to perform an un-installation of &yaz;, use:
 329     </para>
 330
 331     <screen>
 332      make uninstall
 333     </screen>
 334
 335     <para>
 336      This will only work if you haven't reconfigured &yaz; (and therefore
 337      changed installation prefix). Note that uninstall will not
 338      remove directories created by make install, e.g.
 339      <filename>/usr/local/include/yaz</filename>.
 340     </para>
 341    </sect2>
 342
 343    <sect2><title>How to make apps using YAZ on UNIX</title>
 344     <para>
 345      This section describes how to compile - and link your own
 346      applications using the &yaz; toolkit.
 347      If you're used to Makefiles this shouldn't be hard. As for
 348      other libraries you have used before, you have to set a proper include
 349      path for your C/C++ compiler and specify the location of
 350      &yaz; libraries. You can do it by hand, but generally we suggest
 351      you use the <filename>yaz-config</filename> that is generated
 352      by <filename>configure</filename>. This is especially
 353      important if you're using the threaded version of &yaz; which
 354      require you to pass more options to your linker/compiler.
 355     </para>
 356     <para>
 357      The <filename>yaz-config</filename> script accepts command line
 358      options that makes the <filename>yaz-config</filename> script print
 359      options that you should use in your make process.
 360      The most important ones are:
 361      <literal>--cflags</literal>, <literal>--libs</literal>
 362      which prints C compiler flags, and linker flags respectively.
 363      </para>
 364     <para>
 365      A small and complete <literal>Makefile</literal> for a C
 366      application consisting of one source file,
 367      <filename>myprog.c</filename>, may look like this:
 368      <screen>
 369       YAZCONFIG=/usr/local/bin/yaz-config
 370       CFLAGS=`$(YAZCONFIG) --cflags`
 371       LIBS=`$(YAZCONFIG) --libs`
 372       myprog: myprog.o
 373          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
 374       </screen>
 375      </para>
 376     <para>
 377      The CFLAGS variable consists of a C compiler directive that will set
 378      the include path to the <emphasis>parent</emphasis> directory
 379      of <filename>yaz</filename>. That is, if &yaz; header files were
 380      installed in <filename>/usr/local/include/yaz</filename>,
 381      then include path is set to <filename>/usr/local/include</filename>.
 382      Therefore, in your applications you should use
 383      <screen>
 384       #include &lt;yaz/proto.h>
 385      </screen>
 386      and <emphasis>not</emphasis>
 387      <screen>
 388       #include &lt;proto.h>
 389      </screen>
 390     </para>
 391     <para>
 392      For Libtool users, the <filename>yaz-config</filename> script provides
 393      a different variant of option <literal>--libs</literal>, called
 394      <literal>--lalibs</literal> that returns the name of the
 395      Libtool acrhive(s) for &yaz; rather than the ordinary ones.
 396     </para>
 397     <para>
 398      For applications using the threaded version of &yaz;,
 399      specify <literal>threads</literal> after the
 400      other options. When <literal>threads</literal> is given,
 401      more flags and linker flags will be printed by
 402      <filename>yaz-config</filename>. If our previous example was
 403       using threads, you'd have to modify the lines that set
 404      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
 405      follows:
 406      <screen>
 407       CFLAGS=`$(YAZCONFIG) --cflags threads`
 408       LIBS=`$(YAZCONFIG) --libs threads`
 409      </screen>
 410      There is no need specify POSIX thread libraries in your Makefile.
 411      The <literal>LIBS</literal> variable includes that as well.
 412     </para>
 413    </sect2>
 414   </sect1>
 415   <sect1 id="installation.win32"><title>WIN32</title>
 416
 417    <para>The easiest way to install YAZ on Windows is by downloading
 418     an installer from
 419     <ulink url="http://ftp.indexdata.dk/pub/yaz/win32">here</ulink>.
 420     The installer comes with source too - in case you wish to
 421     compile YAZ with different Compiler options etc.
 422    </para>
 423
 424    <sect2 id="installation.win32.source">
 425     <title>Compiling from Source on WIN32</title>
 426     <para>
 427      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 428      with <ulink url="http://msdn.microsoft.com/vstudio/">
 429       Microsoft Visual C++</ulink>.
 430      Version 6 has been tested. We expect that &yaz; compiles
 431      with version 5 as well.
 432     </para>
 433     <para>
 434      Start a command prompt and switch the sub directory
 435      <filename>WIN</filename> where the file <filename>makefile</filename>
 436      is located. Customize the installation by editing the
 437      <filename>makefile</filename> file (for example by using notepad).
 438
 439      The following summarizes the most important settings in that file:
 440
 441      <variablelist>
 442       <varlistentry><term><literal>DEBUG</literal></term>
 443        <listitem><para>
 444          If set to 1, the software is
 445          compiled with debugging libraries (code generation is
 446          multi-threaded debug DLL).
 447          If set to 0, the software is compiled with release libraries
 448          (code generation is multi-threaded DLL).
 449         </para></listitem>
 450       </varlistentry>
 451       <varlistentry>
 452        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
 453        <listitem><para>
 454          If <literal>HAVE_TCL</literal> is set to 1, nmake will
 455          use the ASN.1 compiler (Tcl based). You must set
 456          <literal>TCL</literal> to the full path of the Tcl
 457          interpreter.
 458         </para>
 459         <para>
 460          If you do not have Tcl installed, set
 461          <literal>HAVE_TCL</literal> to 0.
 462         </para></listitem>
 463       </varlistentry>
 464
 465       <varlistentry>
 466        <term><literal>HAVE_ICONV</literal>,
 467         <literal>ICONV_DIR</literal></term>
 468        <listitem><para>
 469          If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
 470          with iconv support. In this configuration, set
 471          <literal>ICONV_DIR</literal> to the iconv source directory.
 472         </para></listitem>
 473       </varlistentry>
 474
 475       <varlistentry>
 476        <term><literal>HAVE_LIBXML2</literal>,
 477         <literal>LIBXML2_DIR</literal></term>
 478        <listitem>
 479         <para>
 480          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
 481          with SRW (and SOAP) support. In this configuration, set
 482          <literal>LIBXML2_DIR</literal> to the
 483          <ulink url="http://www.xmlsoft.org/">libxml2</ulink> source directory.
 484         </para>
 485
 486         <para>
 487          You can get libxml2 and iconv binaries from
 488          <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
 489           here</ulink>.
 490         </para>
 491        </listitem>
 492       </varlistentry>
 493
 494      </variablelist>
 495     </para>
 496     <para>
 497      When satisfied with the settings in the makefile, type
 498      <screen>
 499       nmake
 500      </screen>
 501     </para>
 502     <note>
 503      <para>
 504       If the <filename>nmake</filename> command is not found on your system
 505       you probably haven't defined the environment variables required to
 506       use that tool. To fix that, find and run the batch file
 507       <filename>vcvars32.bat</filename>. You need to run it from within
 508       the command prompt or set the environment variables "globally";
 509       otherwise it doesn't work.
 510      </para>
 511     </note>
 512     <para>
 513      If you wish to recompile &yaz; - for example if you modify
 514      settings in the <filename>makefile</filename> you can delete
 515      object files, etc by running.
 516      <screen>
 517       nmake clean
 518      </screen>
 519     </para>
 520     <para>
 521      The following files are generated upon successful compilation:
 522
 523      <variablelist>
 524       <varlistentry><term><filename>bin/yaz.dll</filename></term>
 525        <listitem><para>
 526          &yaz; multi-threaded Dynamic Link Library.
 527         </para></listitem></varlistentry>
 528
 529       <varlistentry><term><filename>lib/yaz.lib</filename></term>
 530        <listitem><para>
 531          Import library for <filename>yaz.dll</filename>.
 532         </para></listitem></varlistentry>
 533
 534       <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
 535        <listitem><para>
 536          &yaz; Z39.50 client application. It's a WIN32 console application.
 537          See chapter <link linkend="client">YAZ client</link> for more
 538          information.
 539         </para></listitem></varlistentry>
 540
 541       <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 542        <listitem><para>
 543          Z39.50 multi-threaded test/example server. It's a WIN32
 544          console application.
 545         </para></listitem></varlistentry>
 546
 547       <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
 548        <listitem><para>
 549          Simple console application implemented on top of the
 550          <link linkend="zoom">ZOOM</link> functions.
 551          The application is a command line shell that allows you to enter
 552          simple commands to perform ZOOM operations.
 553         </para></listitem></varlistentry>
 554
 555       <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
 556         <filename>bin/zoomtst2.exe</filename>, ..</term>
 557        <listitem><para>
 558          Several small applications that demonstrates the ZOOM API.
 559         </para></listitem></varlistentry>
 560
 561      </variablelist>
 562
 563     </para>
 564    </sect2>
 565
 566    <sect2><title>How to make apps using YAZ on WIN32</title>
 567     <para>
 568      This section will go though the process of linking your WIN32
 569      applications with &yaz;.
 570     </para>
 571     <para>
 572      Some people are confused by the fact that we use the nmake
 573      tool to build &yaz;. They think they have to do that too - in order
 574      to make their WIN32 applications work with &yaz;. The good news is that
 575      you don't have to. You can use the integrated environment of
 576      Visual Studio if desired for your own application.
 577     </para>
 578     <para>
 579      When setting up a project or Makefile you have to set the following:
 580      <variablelist>
 581       <varlistentry><term>include path</term><listitem><para>
 582          Set it to the <filename>include</filename> directory of &yaz;.
 583         </para></listitem></varlistentry>
 584       <varlistentry><term>import library <filename>yaz.lib</filename>
 585        </term><listitem><para>
 586          You must link with this library. It's located in the
 587          sub directory <filename>lib</filename> of &yaz;.
 588         </para></listitem></varlistentry>
 589       <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
 590        </term><listitem><para>
 591          This DLL must be in your execution path when you invoke
 592          your application. Specifically, you should distribute this
 593          DLL with your application.
 594         </para></listitem></varlistentry>
 595      </variablelist>
 596     </para>
 597    </sect2>
 598   </sect1>
 599  </chapter>
 600
 601  <!-- Keep this comment at the end of the file
 602  Local variables:
 603  mode: sgml
 604  sgml-omittag:t
 605  sgml-shorttag:t
 606  sgml-minimize-attributes:nil
 607  sgml-always-quote-attributes:t
 608  sgml-indent-step:1
 609  sgml-indent-data:t
 610  sgml-parent-document: "yaz.xml"
 611  sgml-local-catalogs: nil
 612  sgml-namecase-general:t
 613  End:
 614  -->
 615