1 <!-- $Id: installation.xml,v 1.15 2003-02-18 20:21:22 adam Exp $ -->
2 <chapter id="installation"><title>Compilation and Installation</title>
4 <sect1><title>Introduction</title>
6 The latest version of the software will generally be found at:
9 <ulink url="http://ftp.indexdata.dk/pub/yaz/">
10 http://ftp.indexdata.dk/pub/yaz/</ulink>
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
16 So far, the software has been ported to the following platforms with
17 little or no difficulties.
20 <listitem><para>Unix systems</para>
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)
31 <listitem><para>SGI/IRIX</para></listitem>
32 <listitem><para>DDE Supermax</para></listitem>
33 </itemizedlist></listitem>
34 <listitem><para>Non-unix systems</para>
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>
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>#ifdefs</literal> for individual platforms, and we'd
51 like to keep it that way as far as it makes sense.
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">
62 General questions and problems can be directed at
63 <ulink url="mailto:yaz-help@indexdata.dk">
65 </ulink>, or the address given at the top of this document.
69 <sect1 id="installation.unix"><title>UNIX</title>
73 <ulink url="http://www.debian.org/">Debian GNU/Linux</ulink>
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
81 <sect2 id="installation.source.unix">
82 <title>Compiling from source on Unix</title>
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>.
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
95 <ulink url="http://www.gnu.org/software/libiconv/">GNU iconv</ulink>.
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.
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;.
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;.
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
131 Generally it should be sufficient to run configure without options,
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:
149 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
153 To customize &yaz;, the configure script also accepts a set of options.
154 The most important are:
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.
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.
173 <refentrytitle>hosts_access</refentrytitle>
174 <manvolnum>5</manvolnum>
178 <refentrytitle>tcpd</refentrytitle>
179 <manvolnum>8</manvolnum>
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
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>.
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>.
208 <literal>--with-iconv</literal>[=<replaceable>prefix</replaceable>]
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
220 <literal>--with-xml2</literal>[=<replaceable>prefix</replaceable>]
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
235 <literal>--with-openssl</literal>[=<replaceable>prefix</replaceable>]
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
247 When configured, build the software by typing:
254 The following files are generated by the make process:
256 <varlistentry><term><filename>lib/libyaz.la</filename></term>
258 Main &yaz; library. This is no ordinary library. It's
260 By default, &yaz; creates a static library in
261 <filename>lib/.libs/libyaz.a</filename>.
262 </para></listitem></varlistentry>
264 <varlistentry><term><filename>lib/libyazthread.la</filename></term>
266 When threading is supported/enabled by configure this Libtool
267 library is created. It includes functions that allows &yaz;
269 </para></listitem></varlistentry>
271 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
272 <listitem><para>Test Z39.50 server.
273 </para></listitem></varlistentry>
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>
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
285 </para></listitem></varlistentry>
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>
293 <varlistentry><term><filename>zoom/zoomsh</filename></term>
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>
301 <varlistentry><term><filename>zoom/zoomtst1</filename>,
302 <filename>zoom/zoomtst2</filename>, ..</term>
304 Several small applications that demonstrates the ZOOM API.
305 </para></listitem></varlistentry>
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:
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>.
328 If you wish to perform an un-installation of &yaz;, use:
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>.
343 <sect2><title>How to make apps using YAZ on UNIX</title>
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.
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.
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:
369 YAZCONFIG=/usr/local/bin/yaz-config
370 CFLAGS=`$(YAZCONFIG) --cflags`
371 LIBS=`$(YAZCONFIG) --libs`
373 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
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
384 #include <yaz/proto.h>
386 and <emphasis>not</emphasis>
388 #include <proto.h>
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.
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
407 CFLAGS=`$(YAZCONFIG) --cflags threads`
408 LIBS=`$(YAZCONFIG) --libs threads`
410 There is no need specify POSIX thread libraries in your Makefile.
411 The <literal>LIBS</literal> variable includes that as well.
415 <sect1 id="installation.win32"><title>WIN32</title>
417 <para>The easiest way to install YAZ on Windows is by downloading
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.
424 <sect2 id="installation.win32.source">
425 <title>Compiling from Source on WIN32</title>
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.
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).
439 The following summarizes the most important settings in that file:
442 <varlistentry><term><literal>DEBUG</literal></term>
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).
452 <term><literal>HAVE_TCL</literal>, <literal>TCL</literal></term>
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
460 If you do not have Tcl installed, set
461 <literal>HAVE_TCL</literal> to 0.
466 <term><literal>HAVE_ICONV</literal>,
467 <literal>ICONV_DIR</literal></term>
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.
476 <term><literal>HAVE_LIBXML2</literal>,
477 <literal>LIBXML2_DIR</literal></term>
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.
487 You can get libxml2 and iconv binaries from
488 <ulink url="http://www.zlatkovic.com/projects/libxml/binaries.html">
497 When satisfied with the settings in the makefile, type
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.
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.
521 The following files are generated upon successful compilation:
524 <varlistentry><term><filename>bin/yaz.dll</filename></term>
526 &yaz; multi-threaded Dynamic Link Library.
527 </para></listitem></varlistentry>
529 <varlistentry><term><filename>lib/yaz.lib</filename></term>
531 Import library for <filename>yaz.dll</filename>.
532 </para></listitem></varlistentry>
534 <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
536 &yaz; Z39.50 client application. It's a WIN32 console application.
537 See chapter <link linkend="client">YAZ client</link> for more
539 </para></listitem></varlistentry>
541 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
543 Z39.50 multi-threaded test/example server. It's a WIN32
545 </para></listitem></varlistentry>
547 <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
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>
555 <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
556 <filename>bin/zoomtst2.exe</filename>, ..</term>
558 Several small applications that demonstrates the ZOOM API.
559 </para></listitem></varlistentry>
566 <sect2><title>How to make apps using YAZ on WIN32</title>
568 This section will go though the process of linking your WIN32
569 applications with &yaz;.
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.
579 When setting up a project or Makefile you have to set the following:
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>
601 <!-- Keep this comment at the end of the file
606 sgml-minimize-attributes:nil
607 sgml-always-quote-attributes:t
610 sgml-parent-document: "yaz.xml"
611 sgml-local-catalogs: nil
612 sgml-namecase-general:t