doc/installation.xml

   1 <chapter id="installation"><title>Compilation and Installation</title>
   2
   3   <sect1 id="installation-introduction"><title>Introduction</title>
   4    <para>
   5     The latest version of the software will generally be found at:
   6    </para>
   7    <para>
   8     <ulink url="&url.yaz.download;"/>
   9    </para>
  10    <para>
  11     We have tried our best to keep the software portable, and on many
  12     platforms, you should be able to compile everything with little or
  13     no changes.
  14    </para>
  15
  16    <para>
  17     The software is regularly tested on
  18     <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
  19     <ulink url="&url.centos;">CentOS</ulink>,
  20     <ulink url="&url.ubuntu;">Ubuntu Linux</ulink>,
  21     <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
  22     <ulink url="&url.macosx;">MAC OSX</ulink>,
  23     <ulink url="&url.solaris;">Solaris</ulink>,
  24     Windows 7, Windows XP.
  25    </para>
  26
  27    <para>
  28     Some versions have be known to work on HP/UX,
  29     DEC Unix, <ulink url="&url.netbsd;">NetBSD</ulink>,
  30     <ulink url="&url.openbsd;">OpenBSD</ulink>,
  31     IBM AIX,
  32     Data General DG/UX (with some CFLAGS tinkering),
  33     SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
  34     environment and the GUSI socket libraries),
  35     IBM AS/400 .
  36    </para>
  37
  38    <para>
  39     If you move the software to other platforms, we'd be grateful if you'd
  40     let us know about it. If you run into difficulties, we will try to help
  41     if we can, and if you solve the problems, we would be happy to include
  42     your fixes in the next release. So far, we have mostly avoided
  43     <literal>#ifdefs</literal> for individual platforms, and we'd
  44     like to keep it that way as far as it makes sense.
  45    </para>
  46
  47    <para>
  48     We maintain a mailing-list for the purpose of announcing new releases and
  49     bug-fixes, as well as general discussion. Subscribe by
  50     filling-in the form
  51     <ulink url="&url.yaz.mailinglist;">here</ulink>.
  52     General questions and problems can be directed at
  53     <ulink url="&url.yaz.mail;"/>, or the address given at the top of
  54      this document.
  55    </para>
  56
  57   </sect1>
  58   <sect1 id="installation.unix"><title>UNIX</title>
  59
  60    <para>
  61     We provide
  62     <ulink url="&url.debian;">Debian GNU/Linux</ulink> (i386 and amd64),
  63     <ulink url="&url.ubuntu;">Ubuntu</ulink> (i386 and amd64)
  64     and
  65     <ulink url="&url.centos;">CentOS</ulink> (amd64 only) packages for &yaz;.
  66     You should be able to create packages for other CPUs by building
  67     them from the source package.
  68    </para>
  69
  70    <para>
  71     YAZ is also part of several packages repositories. Some of them are
  72    </para>
  73
  74    <itemizedlist>
  75     <listitem>
  76      <para>
  77       Solaris CSW: <ulink url="http://www.opencsw.org/packages/yaz/"/>
  78      </para>
  79     </listitem>
  80     <listitem>
  81      <para>
  82       Solaris: <ulink url="http://unixpackages.com"/>
  83      </para>
  84     </listitem>
  85     <listitem>
  86      <para>
  87       FreeBSD: <ulink url="http://www.freshports.org/net/yaz"/>
  88      </para>
  89     </listitem>
  90     <listitem>
  91      <para>
  92       Debian: <ulink url="http://packages.debian.org/search?keywords=yaz"/>
  93      </para>
  94     </listitem>
  95     <listitem>
  96      <para>
  97       Ubuntu: <ulink url="https://launchpad.net/ubuntu/+source/yaz"/>
  98      </para>
  99     </listitem>
 100     <listitem>
 101      <para>
 102       NetBSD:
 103       <ulink url="http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/net/yaz/README.html"/>
 104      </para>
 105     </listitem>
 106    </itemizedlist>
 107
 108    <sect2 id="installation.source.unix">
 109     <title>Compiling from source on Unix</title>
 110
 111     <para>
 112      Note that if your system doesn't have a native ANSI C compiler, you may
 113      have to acquire one separately. We recommend
 114      <ulink url="&url.gcc;">GCC</ulink>.
 115     </para>
 116
 117     <para>
 118      If you wish to use character set conversion facilities in &yaz; or if you
 119      are compiling &yaz; for use with Zebra it is a good idea to ensure that
 120      the iconv library is installed. Some Unixes today already have it
 121      - if not, we suggest
 122      <ulink url="&url.libiconv;">GNU libiconv</ulink>.
 123     </para>
 124
 125     <para>
 126      YAZ 3.0.16 and later includes a wrapper for the
 127      <ulink url="&url.icu;">ICU</ulink>
 128      (International Components for Unicode).
 129      In order to use this, the developer version of the ICU library
 130      must be available. ICU support is recommended for applications
 131      such as Pazpar2 and Zebra.
 132     </para>
 133
 134     <para>
 135      The <ulink url="&url.libxslt;">libxslt</ulink>,
 136      <ulink url="&url.libxml2;">libxml2</ulink> librararies are required
 137      if &yaz; is to support SRU/Solr.
 138      These libraries are very portable and should compile out-of-the
 139      box on virtually all Unix platforms. It is available in binary
 140      forms for Linux and others.
 141     </para>
 142
 143     <para>
 144      The GNU tools
 145      <ulink url="&url.autoconf;">Autoconf</ulink>,
 146      <ulink url="&url.automake;">Automake</ulink> and
 147      <ulink url="&url.libtool;">Libtool</ulink>
 148      are used to generate Makefiles and configure &yaz; for the system.
 149      You do <emphasis>not</emphasis> these tools unless you're using the
 150      Git version of &yaz;.
 151     </para>
 152
 153     <para>
 154      The CQL parser for &yaz; is built using
 155      GNU <ulink url="&url.bison;">Bison</ulink>.
 156      This tool is only needed if you're using the Git version of &yaz;.
 157     </para>
 158
 159     <para>
 160      &yaz; includes a tiny ASN.1 compiler. This compiler is
 161      written in <ulink url="&url.tcl;">Tcl</ulink>.
 162      But as for Bison you do not need it unless you're using Git
 163      version of &yaz; or you're using the compiler to built own codecs
 164      for private ASN.1.
 165     </para>
 166
 167     <para>
 168      Generally it should be sufficient to run configure without options,
 169      like this:
 170     </para>
 171
 172     <screen>
 173      ./configure
 174     </screen>
 175
 176     <para>
 177      The configure script attempts to use use the C compiler specified by
 178      the <literal>CC</literal> environment variable. If not set, GNU C will be
 179      used if it is available. The <literal>CFLAGS</literal> environment
 180      variable holds options to be passed to the C compiler. If you're using
 181      Bourne-compatible shell you may pass something like this to use a
 182      particular C compiler with optimization enabled:
 183     </para>
 184
 185     <screen>
 186      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
 187     </screen>
 188
 189     <para>
 190      To customize &yaz;, the configure script also accepts a set of options.
 191      The most important are:
 192
 193      <variablelist>
 194       <varlistentry><term>
 195         <literal>--prefix</literal>=<replaceable>prefix</replaceable></term>
 196        <listitem><para>Specifies installation prefix for &yaz;. This is
 197          only needed if you run <literal>make install</literal> later to
 198          perform a "system" installation. The prefix is
 199          <literal>/usr/local</literal> if not specified.
 200         </para></listitem>
 201       </varlistentry>
 202       <varlistentry><term><literal>--enable-tcpd</literal></term>
 203        <listitem><para>The front end server will be built using Wietse's
 204          <ulink url="&url.tcpwrapper;">TCP wrapper library</ulink>.
 205          It allows you to allow/deny clients depending on IP number.
 206          The TCP wrapper library is often used in GNU/Linux and
 207          BSD distributions.
 208          See
 209          <citerefentry>
 210           <refentrytitle>hosts_access</refentrytitle>
 211           <manvolnum>5</manvolnum>
 212          </citerefentry>
 213          and
 214          <citerefentry>
 215           <refentrytitle>tcpd</refentrytitle>
 216           <manvolnum>8</manvolnum>
 217          </citerefentry>.
 218         </para></listitem>
 219       </varlistentry>
 220
 221       <varlistentry><term><literal>--enable-threads</literal></term>
 222        <listitem><para>&yaz; will be built using POSIX threads.
 223         Specifically, <constant>_REENTRANT</constant> will be defined during
 224          compilation.
 225         </para></listitem>
 226       </varlistentry>
 227
 228       <varlistentry><term><literal>--disable-shared</literal></term>
 229        <listitem><para>The make process will not create shared
 230          libraries (also known as shared objects <filename>.so</filename>).
 231          By default, shared libraries are created -
 232          equivalent to <literal>--enable-shared</literal>.
 233         </para></listitem>
 234       </varlistentry>
 235
 236       <varlistentry><term><literal>--disable-shared</literal></term>
 237        <listitem><para>The make process will not create
 238          static libraries (<filename>.a</filename>).
 239          By default, static libraries are created -
 240          equivalent to <literal>--enable-static</literal>.
 241         </para></listitem>
 242       </varlistentry>
 243
 244       <varlistentry><term>
 245         <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
 246        </term>
 247        <listitem><para>Compile &yaz; with iconv library in directory
 248          <replaceable>prefix</replaceable>. By default configure will
 249          search for iconv on the system. Use this option if it
 250          doesn't find iconv. Alternatively,
 251          <literal>--without-iconv</literal>, can be uset to force &yaz;
 252          not to use iconv.
 253         </para></listitem>
 254       </varlistentry>
 255
 256       <varlistentry><term>
 257         <literal>--with-xslt</literal>[=<replaceable>prefix</replaceable>]
 258        </term>
 259        <listitem><para>Compile &yaz; with
 260          <ulink url="&url.libxslt;">libxslt</ulink> in directory
 261          <replaceable>prefix</replaceable>.
 262          Use this option if you want XSLT and XML support.
 263          By default, configure will
 264          search for libxslt on the system. Use this option if it
 265          libxslt is not found automatically. Alternatively,
 266          <literal>--without-xslt</literal>, can be used to force &yaz;
 267          not to use libxslt.
 268         </para>
 269        </listitem>
 270       </varlistentry>
 271
 272       <varlistentry><term>
 273         <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
 274        </term>
 275        <listitem><para>Compile &yaz; with
 276          <ulink url="&url.libxml2;">libxml2</ulink> in directory
 277          <replaceable>prefix</replaceable>.
 278          Use this option if you want &yaz; to use XML and support SRU/Solr.
 279          By default, configure will
 280          search for libxml2 on the system. Use this option if it
 281          libxml2 is not found automatically. Alternatively,
 282          <literal>--without-xml2</literal>, can be used to force &yaz;
 283          not to use libxml2.
 284          </para>
 285          <para>
 286            Note that option <literal>--with-xslt</literal>
 287            also enables libxml2.
 288          </para>
 289        </listitem>
 290       </varlistentry>
 291
 292       <varlistentry><term>
 293         <literal>--with-gnutls</literal>[=<replaceable>prefix</replaceable>]
 294        </term>
 295        <listitem><para>&yaz; will be linked with the GNU TLS libraries and
 296          an SSL COMSTACK will be provided. By default configure enables
 297          SSL support for YAZ if the GNU TLS development libraries are found
 298          on the system.
 299         </para></listitem>
 300       </varlistentry>
 301
 302       <varlistentry><term>
 303         <literal>--with-icu</literal>[=<replaceable>prefix</replaceable>]
 304        </term>
 305        <listitem><para>&yaz; will be linked the
 306         <ulink url="&url.icu;">ICU</ulink> library in the prefix if given.
 307         If prefix is not given, the libraries exposed by the script
 308         <application>icu-config</application> will be used if found.
 309         </para></listitem>
 310       </varlistentry>
 311
 312       <varlistentry><term>
 313         <literal>--with-libgcrypt</literal>[=<replaceable>prefix</replaceable>]
 314        </term>
 315        <listitem><para>&yaz; will be linked with
 316         <ulink url="&url.libgcrypt;">Libgcrypt</ulink> in the prefix if given.
 317         If prefix is not given, the libraries exposed by the script
 318         <application>libgcrypt-config</application> will be used if found.
 319         </para></listitem>
 320       </varlistentry>
 321
 322       <varlistentry><term>
 323         <literal>--with-memcached</literal>
 324        </term>
 325        <listitem><para>&yaz; will be linked with
 326         <ulink url="&url.libmemcached;">libMemcached</ulink> to allow
 327         for result-set caching for ZOOM.
 328         The prefix can not be given. Note that YAZ will only search
 329         for libMemcached if Libgcrypt is also enabled.
 330         </para></listitem>
 331       </varlistentry>
 332
 333      </variablelist>
 334
 335     </para>
 336     <para>
 337      When configured, build the software by typing:
 338      <screen>
 339       make
 340      </screen>
 341     </para>
 342
 343     <para>
 344      The following files are generated by the make process:
 345      <variablelist>
 346       <varlistentry><term><filename>src/libyaz.la</filename></term>
 347        <listitem><para>
 348          Main &yaz; library. This is no ordinary library. It's
 349          a Libtool archive.
 350          By default, &yaz; creates a static library in
 351          <filename>lib/.libs/libyaz.a</filename>.
 352         </para></listitem>
 353       </varlistentry>
 354
 355       <varlistentry><term><filename>src/libyaz_server.la</filename></term>
 356        <listitem><para>
 357          Generic Frontend server. This is an add-on for libyaz.la.
 358          Code in this library uses POSIX threads functions - if POSIX
 359          threads are available on the platform.
 360         </para></listitem>
 361       </varlistentry>
 362
 363       <varlistentry><term><filename>src/libyaz_icu.la</filename></term>
 364        <listitem><para>
 365          Functions that wrap the ICU library.
 366         </para></listitem>
 367       </varlistentry>
 368
 369       <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 370        <listitem><para>Test Z39.50 server.
 371         </para></listitem>
 372       </varlistentry>
 373
 374       <varlistentry><term><filename>client/yaz-client</filename></term>
 375        <listitem><para>Z39.50 client for testing the protocol.
 376          See chapter <link linkend="yaz-client">
 377           YAZ client</link> for more information.
 378         </para></listitem>
 379       </varlistentry>
 380
 381       <varlistentry><term><filename>util/yaz-config</filename></term>
 382        <listitem><para>A Bourne-shell script, generated by configure, that
 383          specifies how external applications should compile - and link with
 384          &yaz;.
 385         </para></listitem>
 386       </varlistentry>
 387
 388       <varlistentry><term><filename>util/yaz-asncomp</filename></term>
 389        <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 390          Tcl Shell, <application>tclsh</application>, in
 391          <literal>PATH</literal> to operate.
 392         </para></listitem>
 393       </varlistentry>
 394
 395       <varlistentry><term><filename>util/yaz-iconv</filename></term>
 396        <listitem><para>This program converts data in one character set to
 397          another. This command exercises the YAZ character set
 398          conversion API.
 399         </para></listitem>
 400       </varlistentry>
 401
 402       <varlistentry><term><filename>util/yaz-marcdump</filename></term>
 403        <listitem><para>This program parses ISO2709 encoded MARC records
 404          and prints them in line-format or XML.
 405         </para></listitem>
 406       </varlistentry>
 407
 408       <varlistentry><term><filename>util/yaz-icu</filename></term>
 409        <listitem><para>This program exposes the ICU wrapper library if that
 410          is enabled for YAZ. Only if ICU is available this program is
 411          useful.
 412         </para></listitem>
 413       </varlistentry>
 414
 415       <varlistentry><term><filename>util/yaz-url</filename></term>
 416        <listitem><para>This program is a simple HTTP page fetcher ala
 417          wget or curl.
 418         </para></listitem>
 419       </varlistentry>
 420
 421      <varlistentry><term><filename>zoom/zoomsh</filename></term>
 422        <listitem><para>
 423          A simple shell implemented on top of the
 424          <link linkend="zoom">ZOOM</link> functions.
 425          The shell is a command line application that allows you to enter
 426          simple commands to perform ZOOM operations.
 427         </para></listitem>
 428       </varlistentry>
 429
 430       <varlistentry><term><filename>zoom/zoomtst1</filename>,
 431         <filename>zoom/zoomtst2</filename>, ..</term>
 432        <listitem><para>
 433          Several small applications that demonstrates the ZOOM API.
 434         </para></listitem>
 435       </varlistentry>
 436      </variablelist>
 437
 438     </para>
 439
 440     <para>
 441      If you wish to install &yaz; in system directories
 442      <filename>/usr/local/bin</filename>,
 443      <filename>/usr/local/lib</filename> .. etc, you can type:
 444     </para>
 445
 446     <screen>
 447      make install
 448     </screen>
 449
 450     <para>
 451      You probably need to have root access in order to perform this.
 452      You must specify the <literal>--prefix</literal> option for configure if
 453      you wish to install &yaz; in other directories than the default
 454      <filename>/usr/local/</filename>.
 455     </para>
 456
 457     <para>
 458      If you wish to perform an un-installation of &yaz;, use:
 459     </para>
 460
 461     <screen>
 462      make uninstall
 463     </screen>
 464
 465     <para>
 466      This will only work if you haven't reconfigured &yaz; (and therefore
 467      changed installation prefix). Note that uninstall will not
 468      remove directories created by make install, e.g.
 469      <filename>/usr/local/include/yaz</filename>.
 470     </para>
 471    </sect2>
 472
 473    <sect2 id="installation-linking-yaz-unix">
 474     <title>How to make apps using YAZ on UNIX</title>
 475     <para>
 476      This section describes how to compile - and link your own
 477      applications using the &yaz; toolkit.
 478      If you're used to Makefiles this shouldn't be hard. As for
 479      other libraries you have used before, you have to set a proper include
 480      path for your C/C++ compiler and specify the location of
 481      &yaz; libraries. You can do it by hand, but generally we suggest
 482      you use the <filename>yaz-config</filename> that is generated
 483      by <filename>configure</filename>. This is especially
 484      important if you're using the threaded version of &yaz; which
 485      require you to pass more options to your linker/compiler.
 486     </para>
 487     <para>
 488      The <filename>yaz-config</filename> script accepts command line
 489      options that makes the <filename>yaz-config</filename> script print
 490      options that you should use in your make process.
 491      The most important ones are:
 492      <literal>--cflags</literal>, <literal>--libs</literal>
 493      which prints C compiler flags, and linker flags respectively.
 494      </para>
 495     <para>
 496      A small and complete <literal>Makefile</literal> for a C
 497      application consisting of one source file,
 498      <filename>myprog.c</filename>, may look like this:
 499      <screen>
 500       YAZCONFIG=/usr/local/bin/yaz-config
 501       CFLAGS=`$(YAZCONFIG) --cflags`
 502       LIBS=`$(YAZCONFIG) --libs`
 503       myprog: myprog.o
 504          $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
 505       </screen>
 506      </para>
 507     <para>
 508      The CFLAGS variable consists of a C compiler directive that will set
 509      the include path to the <emphasis>parent</emphasis> directory
 510      of <filename>yaz</filename>. That is, if &yaz; header files were
 511      installed in <filename>/usr/local/include/yaz</filename>,
 512      then include path is set to <filename>/usr/local/include</filename>.
 513      Therefore, in your applications you should use
 514      <screen>
 515       #include &lt;yaz/proto.h>
 516      </screen>
 517      and <emphasis>not</emphasis>
 518      <screen>
 519       #include &lt;proto.h>
 520      </screen>
 521     </para>
 522     <para>
 523      For Libtool users, the <filename>yaz-config</filename> script provides
 524      a different variant of option <literal>--libs</literal>, called
 525      <literal>--lalibs</literal> that returns the name of the
 526      Libtool archive(s) for &yaz; rather than the ordinary ones.
 527     </para>
 528     <para>
 529      For applications using the threaded version of &yaz;,
 530      specify <literal>threads</literal> after the
 531      other options. When <literal>threads</literal> is given,
 532      more flags and linker flags will be printed by
 533      <filename>yaz-config</filename>. If our previous example was
 534       using threads, you'd have to modify the lines that set
 535      <literal>CFLAGS</literal> and <literal>LIBS</literal> as
 536      follows:
 537      <screen>
 538       CFLAGS=`$(YAZCONFIG) --cflags threads`
 539       LIBS=`$(YAZCONFIG) --libs threads`
 540      </screen>
 541      There is no need specify POSIX thread libraries in your Makefile.
 542      The <literal>LIBS</literal> variable includes that as well.
 543     </para>
 544    </sect2>
 545   </sect1>
 546   <sect1 id="installation.win32"><title>WIN32</title>
 547
 548    <para>The easiest way to install YAZ on Windows is by downloading
 549     an installer from
 550     <ulink url="&url.yaz.download.win32;">here</ulink>.
 551     The installer comes with source too - in case you wish to
 552     compile YAZ with different compiler options, etc.
 553    </para>
 554
 555    <sect2 id="installation.win32.source">
 556     <title>Compiling from Source on WIN32</title>
 557     <para>
 558      &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 559      with <ulink url="&url.vstudio;">
 560      Microsoft Visual Studio</ulink>. It has been tested with
 561      Microsoft Visual Studio 2003/2005/2008.
 562     </para>
 563     <para>
 564      Start a command prompt and switch the sub directory
 565      <filename>WIN</filename> where the file <filename>makefile</filename>
 566      is located. Customize the installation by editing the
 567      <filename>makefile</filename> file (for example by using notepad).
 568
 569      The following summarizes the most important settings in that file:
 570
 571      <variablelist>
 572       <varlistentry><term><literal>DEBUG</literal></term>
 573        <listitem><para>
 574          If set to 1, the software is
 575          compiled with debugging libraries (code generation is
 576          multi-threaded debug DLL).
 577          If set to 0, the software is compiled with release libraries
 578          (code generation is multi-threaded DLL).
 579         </para></listitem>
 580       </varlistentry>
 581       <varlistentry>
 582        <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
 583        <listitem><para>
 584          If <literal>HAVE_TCL</literal> is set to 1, nmake will
 585          use the ASN.1 compiler (<ulink url="&url.tcl;">Tcl</ulink> based).
 586          You must set <literal>TCL</literal> to the full path of the Tcl
 587          interpreter. A Windows version of Tcl is part of
 588          <ulink url="&url.gitwindows;">Git for Windows</ulink>.
 589         </para>
 590         <para>
 591          If you do not have Tcl installed, set
 592          <literal>HAVE_TCL</literal> to 0.
 593         </para></listitem>
 594       </varlistentry>
 595
 596       <varlistentry>
 597        <term><literal>HAVE_BISON</literal>,
 598         <literal>BISON</literal></term>
 599        <listitem><para>
 600          If GNU Bison is present, you might set <literal>HAVE_BISON</literal>
 601          to 1 and specify the Bison executable in <literal>BISON</literal>.
 602          Bison is only required if you use the Git version of
 603          YAZ or if you modify the grammar for CQL
 604          (<filename>cql.y</filename>).
 605         </para>
 606         <para>
 607          A Windows version of GNU Bison is part of
 608          <ulink url="&url.gitwindows;">Git for Windows</ulink>.
 609         </para></listitem>
 610       </varlistentry>
 611
 612       <varlistentry>
 613        <term><literal>HAVE_ICONV</literal>,
 614         <literal>ICONV_DIR</literal></term>
 615        <listitem><para>
 616          If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
 617          with iconv support. In this configuration, set
 618          <literal>ICONV_DIR</literal> to the iconv source directory.
 619         </para></listitem>
 620       </varlistentry>
 621
 622       <varlistentry>
 623        <term><literal>HAVE_LIBXML2</literal>,
 624         <literal>LIBXML2_DIR</literal></term>
 625        <listitem>
 626         <para>
 627          If <literal>HAVE_LIBXML2</literal> is set to 1, YAZ is compiled
 628          with SRU support. In this configuration, set
 629          <literal>LIBXML2_DIR</literal> to the
 630          <ulink url="&url.libxml2;">libxml2</ulink> source directory
 631          and
 632          <literal>ZLIB_DIR</literal> to the zlib directory.
 633         </para>
 634
 635         <para>
 636          Windows versions of libxslt, libxml2, zlib and iconv can be found
 637          <ulink url="&url.libxml2.download.win32;">
 638           Igor Zlatkovi&#x0107;' site</ulink>.
 639         </para>
 640
 641         <note>
 642          <para>
 643           YAZ is not using zlib but libxml2 is depending on it.
 644          </para>
 645         </note>
 646        </listitem>
 647       </varlistentry>
 648
 649       <varlistentry>
 650        <term><literal>HAVE_LIBXSLT</literal>,
 651         <literal>LIBXSLT_DIR</literal></term>
 652        <listitem>
 653         <para>
 654          If <literal>HAVE_LIBXSLT</literal> is set to 1, YAZ is compiled
 655          with XSLT support. In this configuration, set
 656          <literal>LIBXSLT_DIR</literal> to the
 657          <ulink url="&url.libxslt;">libxslt</ulink> source directory.
 658         </para>
 659
 660         <note>
 661          <para>
 662           libxslt depends libxml2.
 663          </para>
 664         </note>
 665        </listitem>
 666       </varlistentry>
 667
 668       <varlistentry>
 669        <term><literal>HAVE_ICU</literal>,
 670         <literal>ICU_DIR</literal></term>
 671        <listitem>
 672         <para>
 673          If <literal>HAVE_ICU</literal> is set to 1, YAZ is compiled
 674          with <ulink url="&url.icu;">ICU</ulink> support.
 675          In this configuration, set
 676          <literal>ICU_DIR</literal> to the
 677          <ulink url="&url.icu;">ICU</ulink> source directory.
 678         </para>
 679        </listitem>
 680
 681       </varlistentry>
 682
 683      </variablelist>
 684     </para>
 685     <para>
 686      When satisfied with the settings in the makefile, type
 687      <screen>
 688       nmake
 689      </screen>
 690     </para>
 691     <note>
 692      <para>
 693       If the <filename>nmake</filename> command is not found on your system
 694       you probably haven't defined the environment variables required to
 695       use that tool. To fix that, find and run the batch file
 696       <filename>vcvars32.bat</filename>. You need to run it from within
 697       the command prompt or set the environment variables "globally";
 698       otherwise it doesn't work.
 699      </para>
 700     </note>
 701     <para>
 702      If you wish to recompile &yaz; - for example if you modify
 703      settings in the <filename>makefile</filename> you can delete
 704      object files, etc by running.
 705      <screen>
 706       nmake clean
 707      </screen>
 708     </para>
 709     <para>
 710      The following files are generated upon successful compilation:
 711
 712      <variablelist>
 713       <varlistentry><term><filename>bin/yaz&soversion;.dll</filename> /
 714           <filename>bin/yaz&soversion;d.dll</filename></term>
 715        <listitem><para>
 716          &yaz; Release/Debug DLL.
 717         </para></listitem></varlistentry>
 718
 719       <varlistentry><term><filename>lib/yaz&soversion;.lib</filename> /
 720           <filename>lib/yaz&soversion;d.lib</filename></term>
 721        <listitem><para>
 722          Import library for <filename>yaz&soversion;.dll</filename> /
 723          <filename>yaz&soversion;d.dll</filename>.
 724         </para></listitem></varlistentry>
 725
 726       <varlistentry><term><filename>bin/yaz_cond&soversion;.dll</filename> /
 727           <filename>bin/yaz_cond&soversion;d.dll</filename></term>
 728        <listitem><para>
 729          Release/Debug DLL for condition variable utilities (condvar.c).
 730         </para></listitem></varlistentry>
 731
 732       <varlistentry><term><filename>lib/yaz_cond&soversion;.lib</filename> /
 733           <filename>lib/yaz_cond&soversion;d.lib</filename></term>
 734        <listitem><para>
 735          Import library for <filename>yaz_cond&soversion;.dll</filename> /
 736          <filename>yaz_cond&soversion;d.dll</filename>.
 737         </para></listitem></varlistentry>
 738
 739       <varlistentry><term><filename>bin/yaz_icu&soversion;.dll</filename> /
 740           <filename>bin/yaz_icu&soversion;d.dll</filename></term>
 741        <listitem><para>
 742          Release/Debug DLL for the ICU wrapper utility.
 743          Only build if HAVE_ICU is 1.
 744         </para></listitem></varlistentry>
 745
 746       <varlistentry><term><filename>lib/yaz_icu&soversion;.lib</filename> /
 747           <filename>lib/yaz_icu&soversion;d.lib</filename></term>
 748        <listitem><para>
 749          Import library for <filename>yaz_icu&soversion;.dll</filename> /
 750          <filename>yaz_icu&soversion;d.dll</filename>.
 751         </para></listitem></varlistentry>
 752
 753       <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 754        <listitem><para>
 755          Z39.50 multi-threaded test/example server. It's a WIN32
 756          console application.
 757         </para></listitem></varlistentry>
 758
 759       <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
 760        <listitem><para>
 761          &yaz; Z39.50 client application. It's a WIN32 console application.
 762          See chapter <link linkend="yaz-client">YAZ client</link> for more
 763          information.
 764         </para></listitem></varlistentry>
 765
 766       <varlistentry><term><filename>bin/yaz-icu.exe</filename></term>
 767        <listitem><para>This program exposes the ICU wrapper library if that
 768          is enabled for YAZ. Only if ICU is available this program is
 769          build.
 770         </para></listitem></varlistentry>
 771
 772       <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
 773        <listitem><para>
 774          Simple console application implemented on top of the
 775          <link linkend="zoom">ZOOM</link> functions.
 776          The application is a command line shell that allows you to enter
 777          simple commands to perform ZOOM operations.
 778         </para></listitem></varlistentry>
 779
 780       <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
 781         <filename>bin/zoomtst2.exe</filename>, ..</term>
 782        <listitem><para>
 783          Several small applications that demonstrates the ZOOM API.
 784         </para></listitem></varlistentry>
 785
 786      </variablelist>
 787
 788     </para>
 789    </sect2>
 790
 791    <sect2 id="installation-linking-yaz-win32">
 792     <title>How to make apps using YAZ on WIN32</title>
 793     <para>
 794      This section will go though the process of linking your WIN32
 795      applications with &yaz;.
 796     </para>
 797     <para>
 798      Some people are confused by the fact that we use the nmake
 799      tool to build &yaz;. They think they have to do that too - in order
 800      to make their WIN32 applications work with &yaz;. The good news is that
 801      you don't have to. You can use the integrated environment of
 802      Visual Studio if desired for your own application.
 803     </para>
 804     <para>
 805      When setting up a project or Makefile you have to set the following:
 806      <variablelist>
 807       <varlistentry><term>include path</term><listitem><para>
 808          Set it to the <filename>include</filename> directory of &yaz;.
 809         </para></listitem></varlistentry>
 810       <varlistentry><term>import library <filename>yaz&soversion;.lib</filename>
 811        </term><listitem><para>
 812          You must link with this library. It's located in the
 813          sub directory <filename>lib</filename> of &yaz;.
 814          If you want to link with the debug version of &yaz;, you must
 815          link against <filename>yaz&soversion;d.lib</filename> instead.
 816         </para></listitem></varlistentry>
 817       <varlistentry><term>dynamic link library
 818          <filename>yaz&soversion;.dll</filename>
 819        </term><listitem><para>
 820          This DLL must be in your execution path when you invoke
 821          your application. Specifically, you should distribute this
 822          DLL with your application.
 823         </para></listitem></varlistentry>
 824      </variablelist>
 825     </para>
 826    </sect2>
 827   </sect1>
 828  </chapter>
 829
 830  <!-- Keep this comment at the end of the file
 831  Local variables:
 832  mode: sgml
 833  sgml-omittag:t
 834  sgml-shorttag:t
 835  sgml-minimize-attributes:nil
 836  sgml-always-quote-attributes:t
 837  sgml-indent-step:1
 838  sgml-indent-data:t
 839  sgml-parent-document: "yaz.xml"
 840  sgml-local-catalogs: nil
 841  sgml-namecase-general:t
 842  End:
 843  -->
 844