1 <!-- $Id: installation.xml,v 1.14 2002-09-25 20:38:36 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>
72 We provide Debian GNU/Linux and Redhat packages for YAZ.
73 Only i386 binary packages are available. You should be able to
74 create packages for other CPU's by building them from the source
78 <sect2 id="installation.source.unix">
79 <title>Compiling from source on Unix</title>
82 Note that if your system doesn't have a native ANSI C compiler, you may
83 have to acquire one separately. We recommend
84 <ulink url="http://gcc.gnu.org/">GCC</ulink>.
87 For UNIX, the GNU tools
88 <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
89 <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
90 <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
91 are used to generate Makefiles and configure &yaz; for the system.
92 You do <emphasis>not</emphasis> these tools unless you're using the
97 If you wish to use character set conversion facilities in YAZ or if you
98 are compiling YAZ for use with Zebra it is a good idea to ensure that
99 the iconv library is installed. Most Unixes today already have it
101 <ulink url="http://www.gnu.org/software/libiconv/">GNU iconv</ulink>.
105 Generally it should be sufficient to run configure without options,
114 The configure script attempts to use use the C compiler specified by
115 the <literal>CC</literal> environment variable. If not set, GNU C will be
116 used if it is available. The <literal>CFLAGS</literal> environment
117 variable holds options to be passed to the C compiler. If you're using
118 Bourne-compatible shell you may pass something like this to use a
119 particular C compiler with optimization enabled:
123 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
127 To customize &yaz;, the configure script also accepts a set of options.
128 The most important are:
131 <varlistentry><term><literal>--prefix </literal>path</term>
132 <listitem><para>Specifies installation prefix. This is
133 only needed if you run <literal>make install</literal> later to
134 perform a "system" installation. The prefix is
135 <literal>/usr/local</literal> if not specified.
138 <varlistentry><term><literal>--enable-tcpd</literal></term>
139 <listitem><para>The front end server will be built using Wietse's
140 <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
141 TCP wrapper library</ulink>. It allows you to allow/deny
142 clients depending on IP number. The TCP wrapper library is
143 often used in Linux/BSD distributions.
146 <refentrytitle>hosts_access</refentrytitle>
147 <manvolnum>5</manvolnum>
151 <refentrytitle>tcpd</refentrytitle>
152 <manvolnum>8</manvolnum>
156 <varlistentry><term><literal>--enable-threads</literal></term>
157 <listitem><para>&yaz; will be built using POSIX threads.
158 Specifically, <constant>_REENTRANT</constant> will be defined during
162 <varlistentry><term><literal>--with-openssl</literal></term>
163 <listitem><para>&yaz; will be linked with the OpenSSL libraries and
164 an SSL COMSTACK will be provided. Note that SSL support is still
168 <varlistentry><term><literal>--enable-shared</literal></term>
169 <listitem><para>The make process will create shared
170 libraries (also known as shared objects <filename>.so</filename>).
171 By default, no shared libraries are created -
172 equivalent to <literal>--disable-shared</literal>.
175 <varlistentry><term><literal>--disable-shared</literal></term>
176 <listitem><para>The make process will not create
177 static libraries (<filename>.a</filename>).
178 By default, static libraries are created -
179 equivalent to <literal>--enable-static</literal>.
184 <literal>--with-iconv</literal>[=<replaceable>dir</replaceable>]</term>
185 <listitem><para>Compile YAZ with iconv library in directory
186 <replaceable>dir</replaceable>. By default configure will
187 search for iconv on your system. Use this option if it
188 doesn't find iconv. Alternatively you can use
189 <literal>--without-iconv</literal> to force YAZ not to use
198 When configured, build the software by typing:
205 The following files are generated by the make process:
207 <varlistentry><term><filename>lib/libyaz.la</filename></term>
209 Main &yaz; library. This is no ordinary library. It's
211 By default, &yaz; creates a static library in
212 <filename>lib/.libs/libyaz.a</filename>.
213 </para></listitem></varlistentry>
215 <varlistentry><term><filename>lib/libyazthread.la</filename></term>
217 When threading is supported/enabled by configure this Libtool
218 library is created. It includes functions that allows &yaz;
220 </para></listitem></varlistentry>
222 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
223 <listitem><para>Test Z39.50 server.
224 </para></listitem></varlistentry>
226 <varlistentry><term><filename>client/yaz-client</filename></term>
227 <listitem><para>Z39.50 client for testing the protocol.
228 See chapter <link linkend="client">
229 YAZ client</link> for more information.
230 </para></listitem></varlistentry>
232 <varlistentry><term><filename>yaz-config</filename></term>
233 <listitem><para>A Bourne-shell script, generated by configure, that
234 specifies how external applications should compile - and link with
236 </para></listitem></varlistentry>
238 <varlistentry><term><filename>yaz-comp</filename></term>
239 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
240 Tcl Shell, <application>tclsh</application>, in
241 <literal>PATH</literal> to operate.
242 </para></listitem></varlistentry>
244 <varlistentry><term><filename>zoom/zoomsh</filename></term>
246 A simple shell implemented on top of the
247 <link linkend="zoom">ZOOM</link> functions.
248 The shell is a command line application that allows you to enter
249 simple commands to perform ZOOM operations.
250 </para></listitem></varlistentry>
252 <varlistentry><term><filename>zoom/zoomtst1</filename>,
253 <filename>zoom/zoomtst2</filename>, ..</term>
255 Several small applications that demonstrates the ZOOM API.
256 </para></listitem></varlistentry>
262 If you wish to install &yaz; in system directories
263 <filename>/usr/local/bin</filename>,
264 <filename>/usr/local/lib</filename> .. etc, you can type:
272 You probably need to have root access in order to perform this.
273 You must specify the <literal>--prefix</literal> option for configure if
274 you wish to install &yaz; in other directories than the default
275 <filename>/usr/local/</filename>.
279 If you wish to perform an un-installation of &yaz;, use:
287 This will only work if you haven't reconfigured &yaz; (and therefore
288 changed installation prefix). Note that uninstall will not
289 remove directories created by make install, e.g.
290 <filename>/usr/local/include/yaz</filename>.
294 <sect2><title>How to make apps using YAZ on UNIX</title>
296 This section describes how to compile - and link your own
297 applications using the &yaz; toolkit.
298 If you're used to Makefiles this shouldn't be hard. As for
299 other libraries you have used before, you have to set a proper include
300 path for your C/C++ compiler and specify the location of
301 &yaz; libraries. You can do it by hand, but generally we suggest
302 you use the <filename>yaz-config</filename> that is generated
303 by <filename>configure</filename>. This is especially
304 important if you're using the threaded version of &yaz; which
305 require you to pass more options to your linker/compiler.
308 The <filename>yaz-config</filename> script accepts command line
309 options that makes the <filename>yaz-config</filename> script print
310 options that you should use in your make process.
311 The most important ones are:
312 <literal>--cflags</literal>, <literal>--libs</literal>
313 which prints C compiler flags, and linker flags respectively.
316 A small and complete <literal>Makefile</literal> for a C
317 application consisting of one source file,
318 <filename>myprog.c</filename>, may look like this:
320 YAZCONFIG=/usr/local/bin/yaz-config
321 CFLAGS=`$(YAZCONFIG) --cflags`
322 LIBS=`$(YAZCONFIG) --libs`
324 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
328 The CFLAGS variable consists of a C compiler directive that will set
329 the include path to the <emphasis>parent</emphasis> directory
330 of <filename>yaz</filename>. That is, if &yaz; header files were
331 installed in <filename>/usr/local/include/yaz</filename>,
332 then include path is set to <filename>/usr/local/include</filename>.
333 Therefore, in your applications you should use
335 #include <yaz/proto.h>
337 and <emphasis>not</emphasis>
339 #include <proto.h>
343 For Libtool users, the <filename>yaz-config</filename> script provides
344 a different variant of option <literal>--libs</literal>, called
345 <literal>--lalibs</literal> that returns the name of the
346 Libtool acrhive(s) for &yaz; rather than the ordinary ones.
349 For applications using the threaded version of &yaz;,
350 specify <literal>threads</literal> after the
351 other options. When <literal>threads</literal> is given,
352 more flags and linker flags will be printed by
353 <filename>yaz-config</filename>. If our previous example was
354 using threads, you'd have to modify the lines that set
355 <literal>CFLAGS</literal> and <literal>LIBS</literal> as
358 CFLAGS=`$(YAZCONFIG) --cflags threads`
359 LIBS=`$(YAZCONFIG) --libs threads`
361 There is no need specify POSIX thread libraries in your Makefile.
362 The <literal>LIBS</literal> variable includes that as well.
366 <sect1 id="installation.win32"><title>WIN32</title>
368 <para>The easiest way to install YAZ on Windows is by downloading
370 <ulink url="http://ftp.indexdata.dk/pub/yaz/win32">here</ulink>.
371 The installer comes with source too - in case you wish to
372 compile YAZ with different Compiler options etc.
375 <sect2 id="installation.win32.source">
376 <title>Compiling from Source on WIN32</title>
378 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
379 with Microsoft Visual C++. Version 6 has been tested. We expect that
380 &yaz; should compile with version 5 as well.
383 Start a command prompt and switch the sub directory
384 <filename>WIN</filename> where the file <filename>makefile</filename>
385 is located. Customize the installation by editing the
386 <filename>makefile</filename> file (for example by using notepad).
388 The following summarizes the most important settings in that file:
391 <varlistentry><term><literal>DEBUG</literal></term>
393 If set to 1, the software is
394 compiled with debugging libraries (code generation is
395 multi-threaded debug DLL).
396 If set to 0, the software is compiled with release libraries
397 (code generation is multi-threaded DLL).
400 <varlistentry><term><literal>TCL</literal></term>
402 Specifies the name of the Tcl shell (EXE-file).
403 You do not need setting this or installing Tcl unless you wish
404 to change or add ASN.1 for &yaz;.
409 <term><literal>HAVE_ICONV</literal>, <literal>ICONV_DIR</literal></term>
411 If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
412 with iconv support. In this configuration, set
413 <literal>ICONV_DIR</literal> to the iconv source directory.
420 When satisfied with the settings in the makefile, type
424 If command <filename>nmake</filename> is not found on your system
425 you probably haven't defined the environment variables required to
426 use that tool. To fix that, find and run the batch file
427 <filename>vcvars32.bat</filename>. You need to run it from within
428 the command prompt or set the environment variables "globally";
429 otherwise it doesn't work.
432 If you wish to recompile &yaz; - for example if you modify
433 settings in the <filename>makefile</filename> you can delete
434 object files, etc by running.
440 The following files are generated upon successful compilation:
443 <varlistentry><term><filename>bin/yaz.dll</filename></term>
445 &yaz; multi-threaded Dynamic Link Library.
446 </para></listitem></varlistentry>
448 <varlistentry><term><filename>lib/yaz.lib</filename></term>
450 Import library for <filename>yaz.dll</filename>.
451 </para></listitem></varlistentry>
453 <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
455 &yaz; Z39.50 client application. It's a WIN32 console application.
456 See chapter <link linkend="client">YAZ client</link> for more
458 </para></listitem></varlistentry>
460 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
462 Z39.50 multi-threaded test/example server. It's a WIN32
464 </para></listitem></varlistentry>
466 <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
468 Simple console application implemented on top of the
469 <link linkend="zoom">ZOOM</link> functions.
470 The application is a command line shell that allows you to enter
471 simple commands to perform ZOOM operations.
472 </para></listitem></varlistentry>
474 <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
475 <filename>bin/zoomtst2.exe</filename>, ..</term>
477 Several small applications that demonstrates the ZOOM API.
478 </para></listitem></varlistentry>
485 <sect2><title>How to make apps using YAZ on WIN32</title>
487 This section will go though the process of linking your WIN32
488 applications with &yaz;.
491 Some people are confused by the fact that we use the nmake
492 tool to build &yaz;. They think they have to do that too - in order
493 to make their WIN32 applications work with &yaz;. The good news is that
494 you don't have to. You can use the integrated environment of
495 Visual Studio if desired for your own application.
498 When setting up a project or Makefile you have to set the following:
500 <varlistentry><term>include path</term><listitem><para>
501 Set it to the <filename>include</filename> directory of &yaz;.
502 </para></listitem></varlistentry>
503 <varlistentry><term>import library <filename>yaz.lib</filename>
504 </term><listitem><para>
505 You must link with this library. It's located in the
506 sub directory <filename>lib</filename> of &yaz;.
507 </para></listitem></varlistentry>
508 <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
509 </term><listitem><para>
510 This DLL must be in your execution path when you invoke
511 your application. Specifically, you should distribute this
512 DLL with your application.
513 </para></listitem></varlistentry>
520 <!-- Keep this comment at the end of the file
525 sgml-minimize-attributes:nil
526 sgml-always-quote-attributes:t
529 sgml-parent-document: "yaz.xml"
530 sgml-local-catalogs: nil
531 sgml-namecase-general:t