1 <!-- $Id: installation.xml,v 1.9 2001-11-18 21:14: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>OpenBSD/FreeBSD</para></listitem>
26 <listitem><para>Linux</para></listitem>
27 <listitem><para>IBM AIX</para></listitem>
28 <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
30 <listitem><para>SGI/IRIX</para></listitem>
31 <listitem><para>DDE Supermax</para></listitem>
32 </itemizedlist></listitem>
33 <listitem><para>Non-unix systems</para>
35 <listitem><para>Apple Macintosh (using the Codewarrior programming
36 environment and the GUSI socket libraries)</para></listitem>
37 <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
38 <listitem><para>IBM AS/400</para></listitem>
39 </itemizedlist></listitem>
44 If you move the software to other platforms, we'd be grateful if you'd
45 let us know about it. If you run into difficulties, we will try to help
46 if we can, and if you solve the problems, we would be happy to include
47 your fixes in the next release. So far, we have mostly avoided
48 #ifdefs for individual platforms, and we'd like to keep it that
49 way as far as it makes sense.
53 We maintain a mailing-list for the purpose of announcing new releases and
54 bug-fixes, as well as general discussion. Subscribe by sending mail to
55 <ulink url="mailto:yaz-request@indexdata.dk">
56 yaz-request@indexdata.dk
58 General questions and problems can be directed at
59 <ulink url="mailto:yaz-help@indexdata.dk">
61 </ulink>, or the address given at the top of this document.
65 <sect1 id="installation.unix"><title>UNIX</title>
68 Note that if your system doesn't have a native ANSI C compiler, you may
69 have to acquire one separately. We recommend
70 <ulink url="http://gcc.gnu.org">GCC</ulink>.
73 For UNIX, the GNU tools
74 <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
75 <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
76 <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
77 is used to generate Makefiles and configure &yaz; for the system.
78 You do <emphasis>not</emphasis> these tools unless you're using the
80 Generally it should be sufficient to run configure without options,
89 The configure script attempts to use use the C compiler specified by
90 the <literal>CC</literal> environment variable. If not set, GNU C will be
91 used if it is available. The <literal>CFLAGS</literal> environment
92 variable holds options to be passed to the C compiler. If you're using
93 Bourne-compatible shell you may pass something like this to use a
94 particular C compiler with optimization enabled:
98 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
102 To customize &yaz;, the configure script also accepts a set of options.
103 The most important are:
106 <varlistentry><term><literal>--prefix </literal>path</term>
107 <listitem><para>Specifies installation prefix. This is
108 only needed if you run <literal>make install</literal> later to
109 perform a "system" installation. The prefix is
110 <literal>/usr/local</literal> if not specified.
113 <varlistentry><term><literal>--enable-tcpd</literal></term>
114 <listitem><para>The front end server will be built using Wietse's
115 <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
116 TCP wrapper library</ulink>. It allows you to allow/deny
117 clients depending on IP number. The TCP wrapper library is
118 often used in Linux/BSD distributions.
121 <varlistentry><term><literal>--enable-threads</literal></term>
122 <listitem><para>&yaz; will be built using POSIX threads.
123 Specifically, <constant>_REENTRANT</constant> will be defined during
127 <varlistentry><term><literal>--with-openssl</literal></term>
128 <listitem><para>&yaz; will be linked with the OpenSSL libraries and
129 an SSL COMSTACK will be provided. Note that SSL support is still
133 <varlistentry><term><literal>--enable-shared</literal></term>
134 <listitem><para>The make process will create shared
135 libraries (also known as shared objects <filename>.so</filename>).
136 By default, no shared libraries are created -
137 equivalent to <literal>--disable-shared</literal>.
140 <varlistentry><term><literal>--disable-shared</literal></term>
141 <listitem><para>The make process will not create
142 static libraries (<filename>.a</filename>).
143 By default, static libraries are created -
144 equivalent to <literal>--enable-static</literal>.
151 When configured, build the software by typing:
159 The following files are generated by the make process:
161 <varlistentry><term><filename>lib/libyaz.la</filename></term>
163 Main &yaz; library. This is no ordinary library. It's
165 By default, &yaz; creates a static library in
166 <filename>lib/.libs/libyaz.a</filename>.
167 </para></listitem></varlistentry>
169 <varlistentry><term><filename>lib/libyazthread.la</filename></term>
171 When threading is supported/enabled by configure this Libtool
172 library is created. It includes functions that allows &yaz;
174 </para></listitem></varlistentry>
176 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
177 <listitem><para>Test Z39.50 server.
178 </para></listitem></varlistentry>
180 <varlistentry><term><filename>client/yaz-client</filename></term>
181 <listitem><para>Z39.50 client for testing the protocol.
182 See chapter <link linkend="client">
183 YAZ client</link> for more information.
184 </para></listitem></varlistentry>
186 <varlistentry><term><filename>yaz-config</filename></term>
187 <listitem><para>A Bourne-shell script, generated by configure, that
188 specifies how external applications should compile - and link with
190 </para></listitem></varlistentry>
192 <varlistentry><term><filename>yaz-comp</filename></term>
193 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
194 Tcl Shell, <application>tclsh</application>, in
195 <literal>PATH</literal> to operate.
196 </para></listitem></varlistentry>
198 <varlistentry><term><filename>zoom/zoomsh</filename></term>
200 A simple shell implemented on top of the
201 <link linkend="zoom">ZOOM</link> functions.
202 The shell is a command line application that allows you to enter
203 simple commands to perform ZOOM operations.
204 </para></listitem></varlistentry>
206 <varlistentry><term><filename>zoom/zoomtst1</filename>,
207 <filename>zoom/zoomtst2</filename>, ..</term>
209 Several small applications that demonstrates the ZOOM API.
210 </para></listitem></varlistentry>
216 If you wish to install &yaz; in system directories
217 <filename>/usr/local/bin</filename>,
218 <filename>/usr/local/lib</filename> .. etc, you can type:
226 You probably need to have root access in order to perform this.
227 You must specify the <literal>--prefix</literal> option for configure if
228 you wish to install &yaz; in other directories than the default
229 <filename>/usr/local/</filename>.
233 If you wish to perform an un-installation of &yaz;, use:
241 This will only work if you haven't reconfigured &yaz; (and therefore
242 changed installation prefix). Note that uninstall will not
243 remove directories created by make install, e.g.
244 <filename>/usr/local/include/yaz</filename>.
247 <sect2><title>How to make apps using YAZ on UNIX</title>
249 This section describes how to compile - and link your own
250 applications using the &yaz; toolkit.
251 If you're used to Makefiles this shouldn't be hard. As for
252 other libraries you have used before, you have to set a proper include
253 path for your C/C++ compiler and specify the location of
254 &yaz; libraries. You can do it by hand, but generally we suggest
255 you use the <filename>yaz-config</filename> that is generated
256 by <filename>configure</filename>. This is especially
257 important if you're using the threaded version of &yaz; which
258 require you to pass more options to your linker/compiler.
261 The <filename>yaz-config</filename> script accepts command line
262 options that makes the <filename>yaz-config</filename> script print
263 options that you should use in your make process.
264 The most important ones are:
265 <literal>--cflags</literal>, <literal>--libs</literal>
266 which prints C compiler flags, and linker flags respectively.
269 A small and complete <literal>Makefile</literal> for a C
270 application consisting of one source file,
271 <filename>myprog.c</filename>, may look like this:
273 YAZCONFIG=/usr/local/bin/yaz-config
274 CFLAGS=`$(YAZCONFIG) --cflags`
275 LIBS=`$(YAZCONFIG) --libs`
277 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
281 The CFLAGS variable consists of a C compiler directive that will set
282 the include path to the <emphasis>parent</emphasis> directory
283 of <filename>yaz</filename>. That is, if &yaz; header files were
284 installed in <filename>/usr/local/include/yaz</filename>,
285 then include path is set to <filename>/usr/local/include</filename>.
286 Therefore, in your applications you should use
288 #include <yaz/proto.h>
290 and <emphasis>not</emphasis>
292 #include <proto.h>
296 For Libtool users, the <filename>yaz-config</filename> script provides
297 a different variant of option <literal>--libs</literal>, called
298 <literal>--lalibs</literal> that returns the name of the
299 Libtool acrhive(s) for &yaz; rather than the ordinary ones.
302 For applications using the threaded version of &yaz;,
303 specify <literal>threads</literal> after the
304 other options. When <literal>threads</literal> is given,
305 more flags and linker flags will be printed by
306 <filename>yaz-config</filename>. If our previous example was
307 using threads, you'd have to modify the lines that set
308 <literal>CFLAGS</literal> and <literal>LIBS</literal> as
311 CFLAGS=`$(YAZCONFIG) --cflags threads`
312 LIBS=`$(YAZCONFIG) --libs threads`
314 There is no need specify POSIX thread libraries in your Makefile.
315 The <literal>LIBS</literal> variable includes that as well.
319 <sect1 id="installation.win32"><title>WIN32</title>
322 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
323 with Microsoft Visual C++. Version 6 has been tested. We expect that
324 &yaz; should compile with version 5 as well.
327 Start a command prompt and switch the sub directory
328 <filename>WIN</filename> where the file <filename>makefile</filename>
329 is located. Customize the installation by editing the
330 <filename>makefile</filename> file (for example by using notepad).
332 The following summarises the most important settings in that file:
335 <varlistentry><term><literal>DEBUG</literal></term>
337 If set to 1, the software is
338 compiled with debugging libraries (code generation is
339 multi-threaded debug DLL).
340 If set to 0, the software is compiled with release libraries
341 (code generation is multi-threaded DLL).
344 <varlistentry><term><literal>TCL</literal></term>
346 Specifies the name of the Tcl shell (EXE-file).
347 You do not need setting this or installing Tcl unless you wish
348 to change or add ASN.1 for &yaz;.
354 When satisfied with the settings in the makefile, type
358 If command <filename>nmake</filename> is not found on your system
359 you probably haven't defined the environment variables required to
360 use that tool. To fix that, find and run the batch file
361 <filename>vcvars32.bat</filename>. You need to run it from within
362 the command prompt or set the environment variables "globally";
363 otherwise it doesn't work.
366 If you wish to recompile &yaz; - for example if you modify
367 settings in the <filename>makefile</filename> you can delete
368 object files, etc by running.
374 The following files are generated upon successful compilation:
377 <varlistentry><term><filename>bin/yaz.dll</filename></term>
379 &yaz; multi-threaded Dynamic Link Library.
380 </para></listitem></varlistentry>
382 <varlistentry><term><filename>lib/yaz.lib</filename></term>
384 Import library for <filename>yaz.dll</filename>.
385 </para></listitem></varlistentry>
387 <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
389 &yaz; Z39.50 client application. It's a WIN32 console application.
390 See chapter <link linkend="client">YAZ client</link> for more
392 </para></listitem></varlistentry>
394 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
396 Z39.50 multi-threaded test/example server. It's a WIN32
398 </para></listitem></varlistentry>
400 <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
402 Simple console application implemented on top of the
403 <link linkend="zoom">ZOOM</link> functions.
404 The application is a command line shell that allows you to enter
405 simple commands perform to perform ZOOM operations.
406 </para></listitem></varlistentry>
408 <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
409 <filename>bin/zoomtst2.exe</filename>, ..</term>
411 Several small applications that demonstrates the ZOOM API.
412 </para></listitem></varlistentry>
417 <sect2><title>How to make apps using YAZ on WIN32</title>
419 This section will go though the process of linking your WIN32
420 applications with &yaz;.
423 Some people are confused by the fact that we use the nmake
424 tool to build &yaz;. They think they have to do that too - in order
425 to make their WIN32 applications work with &yaz;. The good news is that
426 you don't have to. You can use the integrated environement of
427 Visual Studio if desired for your own application.
430 When setting up a project or Makefile you have to set the following:
432 <varlistentry><term>include path</term><listitem><para>
433 Set it to the <filename>include</filename> directory of &yaz;.
434 </para></listitem></varlistentry>
435 <varlistentry><term>import library <filename>yaz.lib</filename>
436 </term><listitem><para>
437 You must link with this library. It's located in the
438 sub directory <filename>lib</filename> of &yaz;.
439 </para></listitem></varlistentry>
440 <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
441 </term><listitem><para>
442 This DLL must be in your execution path when you invoke
443 your application. Specifically, you should distribute this
444 DLL with your application.
445 </para></listitem></varlistentry>
452 <!-- Keep this comment at the end of the file
457 sgml-minimize-attributes:nil
458 sgml-always-quote-attributes:t
461 sgml-parent-document: "yaz.xml"
462 sgml-local-catalogs: nil
463 sgml-namecase-general:t