1 <!-- $Id: installation.xml,v 1.13 2002-09-17 20:17:44 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, MAC OSX
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>
45 If you move the software to other platforms, we'd be grateful if you'd
46 let us know about it. If you run into difficulties, we will try to help
47 if we can, and if you solve the problems, we would be happy to include
48 your fixes in the next release. So far, we have mostly avoided
49 <literal>#ifdefs</literal> for individual platforms, and we'd
50 like to keep it that way as far as it makes sense.
54 We maintain a mailing-list for the purpose of announcing new releases and
55 bug-fixes, as well as general discussion. Subscribe by sending mail to
56 <ulink url="mailto:yaz-request@indexdata.dk">
57 yaz-request@indexdata.dk
58 </ulink> or fill-in the form
59 <ulink url="http://www.indexdata.dk/mailman/listinfo/yazlist">
61 General questions and problems can be directed at
62 <ulink url="mailto:yaz-help@indexdata.dk">
64 </ulink>, or the address given at the top of this document.
68 <sect1 id="installation.unix"><title>UNIX</title>
71 Note that if your system doesn't have a native ANSI C compiler, you may
72 have to acquire one separately. We recommend
73 <ulink url="http://gcc.gnu.org/">GCC</ulink>.
76 For UNIX, the GNU tools
77 <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
78 <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
79 <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
80 are used to generate Makefiles and configure &yaz; for the system.
81 You do <emphasis>not</emphasis> these tools unless you're using the
83 Generally it should be sufficient to run configure without options,
92 The configure script attempts to use use the C compiler specified by
93 the <literal>CC</literal> environment variable. If not set, GNU C will be
94 used if it is available. The <literal>CFLAGS</literal> environment
95 variable holds options to be passed to the C compiler. If you're using
96 Bourne-compatible shell you may pass something like this to use a
97 particular C compiler with optimization enabled:
101 CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
105 To customize &yaz;, the configure script also accepts a set of options.
106 The most important are:
109 <varlistentry><term><literal>--prefix </literal>path</term>
110 <listitem><para>Specifies installation prefix. This is
111 only needed if you run <literal>make install</literal> later to
112 perform a "system" installation. The prefix is
113 <literal>/usr/local</literal> if not specified.
116 <varlistentry><term><literal>--enable-tcpd</literal></term>
117 <listitem><para>The front end server will be built using Wietse's
118 <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
119 TCP wrapper library</ulink>. It allows you to allow/deny
120 clients depending on IP number. The TCP wrapper library is
121 often used in Linux/BSD distributions.
124 <refentrytitle>hosts_access</refentrytitle>
125 <manvolnum>5</manvolnum>
129 <refentrytitle>tcpd</refentrytitle>
130 <manvolnum>8</manvolnum>
134 <varlistentry><term><literal>--enable-threads</literal></term>
135 <listitem><para>&yaz; will be built using POSIX threads.
136 Specifically, <constant>_REENTRANT</constant> will be defined during
140 <varlistentry><term><literal>--with-openssl</literal></term>
141 <listitem><para>&yaz; will be linked with the OpenSSL libraries and
142 an SSL COMSTACK will be provided. Note that SSL support is still
146 <varlistentry><term><literal>--enable-shared</literal></term>
147 <listitem><para>The make process will create shared
148 libraries (also known as shared objects <filename>.so</filename>).
149 By default, no shared libraries are created -
150 equivalent to <literal>--disable-shared</literal>.
153 <varlistentry><term><literal>--disable-shared</literal></term>
154 <listitem><para>The make process will not create
155 static libraries (<filename>.a</filename>).
156 By default, static libraries are created -
157 equivalent to <literal>--enable-static</literal>.
164 When configured, build the software by typing:
171 The following files are generated by the make process:
173 <varlistentry><term><filename>lib/libyaz.la</filename></term>
175 Main &yaz; library. This is no ordinary library. It's
177 By default, &yaz; creates a static library in
178 <filename>lib/.libs/libyaz.a</filename>.
179 </para></listitem></varlistentry>
181 <varlistentry><term><filename>lib/libyazthread.la</filename></term>
183 When threading is supported/enabled by configure this Libtool
184 library is created. It includes functions that allows &yaz;
186 </para></listitem></varlistentry>
188 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
189 <listitem><para>Test Z39.50 server.
190 </para></listitem></varlistentry>
192 <varlistentry><term><filename>client/yaz-client</filename></term>
193 <listitem><para>Z39.50 client for testing the protocol.
194 See chapter <link linkend="client">
195 YAZ client</link> for more information.
196 </para></listitem></varlistentry>
198 <varlistentry><term><filename>yaz-config</filename></term>
199 <listitem><para>A Bourne-shell script, generated by configure, that
200 specifies how external applications should compile - and link with
202 </para></listitem></varlistentry>
204 <varlistentry><term><filename>yaz-comp</filename></term>
205 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
206 Tcl Shell, <application>tclsh</application>, in
207 <literal>PATH</literal> to operate.
208 </para></listitem></varlistentry>
210 <varlistentry><term><filename>zoom/zoomsh</filename></term>
212 A simple shell implemented on top of the
213 <link linkend="zoom">ZOOM</link> functions.
214 The shell is a command line application that allows you to enter
215 simple commands to perform ZOOM operations.
216 </para></listitem></varlistentry>
218 <varlistentry><term><filename>zoom/zoomtst1</filename>,
219 <filename>zoom/zoomtst2</filename>, ..</term>
221 Several small applications that demonstrates the ZOOM API.
222 </para></listitem></varlistentry>
228 If you wish to install &yaz; in system directories
229 <filename>/usr/local/bin</filename>,
230 <filename>/usr/local/lib</filename> .. etc, you can type:
238 You probably need to have root access in order to perform this.
239 You must specify the <literal>--prefix</literal> option for configure if
240 you wish to install &yaz; in other directories than the default
241 <filename>/usr/local/</filename>.
245 If you wish to perform an un-installation of &yaz;, use:
253 This will only work if you haven't reconfigured &yaz; (and therefore
254 changed installation prefix). Note that uninstall will not
255 remove directories created by make install, e.g.
256 <filename>/usr/local/include/yaz</filename>.
259 <sect2><title>How to make apps using YAZ on UNIX</title>
261 This section describes how to compile - and link your own
262 applications using the &yaz; toolkit.
263 If you're used to Makefiles this shouldn't be hard. As for
264 other libraries you have used before, you have to set a proper include
265 path for your C/C++ compiler and specify the location of
266 &yaz; libraries. You can do it by hand, but generally we suggest
267 you use the <filename>yaz-config</filename> that is generated
268 by <filename>configure</filename>. This is especially
269 important if you're using the threaded version of &yaz; which
270 require you to pass more options to your linker/compiler.
273 The <filename>yaz-config</filename> script accepts command line
274 options that makes the <filename>yaz-config</filename> script print
275 options that you should use in your make process.
276 The most important ones are:
277 <literal>--cflags</literal>, <literal>--libs</literal>
278 which prints C compiler flags, and linker flags respectively.
281 A small and complete <literal>Makefile</literal> for a C
282 application consisting of one source file,
283 <filename>myprog.c</filename>, may look like this:
285 YAZCONFIG=/usr/local/bin/yaz-config
286 CFLAGS=`$(YAZCONFIG) --cflags`
287 LIBS=`$(YAZCONFIG) --libs`
289 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
293 The CFLAGS variable consists of a C compiler directive that will set
294 the include path to the <emphasis>parent</emphasis> directory
295 of <filename>yaz</filename>. That is, if &yaz; header files were
296 installed in <filename>/usr/local/include/yaz</filename>,
297 then include path is set to <filename>/usr/local/include</filename>.
298 Therefore, in your applications you should use
300 #include <yaz/proto.h>
302 and <emphasis>not</emphasis>
304 #include <proto.h>
308 For Libtool users, the <filename>yaz-config</filename> script provides
309 a different variant of option <literal>--libs</literal>, called
310 <literal>--lalibs</literal> that returns the name of the
311 Libtool acrhive(s) for &yaz; rather than the ordinary ones.
314 For applications using the threaded version of &yaz;,
315 specify <literal>threads</literal> after the
316 other options. When <literal>threads</literal> is given,
317 more flags and linker flags will be printed by
318 <filename>yaz-config</filename>. If our previous example was
319 using threads, you'd have to modify the lines that set
320 <literal>CFLAGS</literal> and <literal>LIBS</literal> as
323 CFLAGS=`$(YAZCONFIG) --cflags threads`
324 LIBS=`$(YAZCONFIG) --libs threads`
326 There is no need specify POSIX thread libraries in your Makefile.
327 The <literal>LIBS</literal> variable includes that as well.
331 <sect1 id="installation.win32"><title>WIN32</title>
334 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
335 with Microsoft Visual C++. Version 6 has been tested. We expect that
336 &yaz; should compile with version 5 as well.
339 Start a command prompt and switch the sub directory
340 <filename>WIN</filename> where the file <filename>makefile</filename>
341 is located. Customize the installation by editing the
342 <filename>makefile</filename> file (for example by using notepad).
344 The following summarizes the most important settings in that file:
347 <varlistentry><term><literal>DEBUG</literal></term>
349 If set to 1, the software is
350 compiled with debugging libraries (code generation is
351 multi-threaded debug DLL).
352 If set to 0, the software is compiled with release libraries
353 (code generation is multi-threaded DLL).
356 <varlistentry><term><literal>TCL</literal></term>
358 Specifies the name of the Tcl shell (EXE-file).
359 You do not need setting this or installing Tcl unless you wish
360 to change or add ASN.1 for &yaz;.
366 When satisfied with the settings in the makefile, type
370 If command <filename>nmake</filename> is not found on your system
371 you probably haven't defined the environment variables required to
372 use that tool. To fix that, find and run the batch file
373 <filename>vcvars32.bat</filename>. You need to run it from within
374 the command prompt or set the environment variables "globally";
375 otherwise it doesn't work.
378 If you wish to recompile &yaz; - for example if you modify
379 settings in the <filename>makefile</filename> you can delete
380 object files, etc by running.
386 The following files are generated upon successful compilation:
389 <varlistentry><term><filename>bin/yaz.dll</filename></term>
391 &yaz; multi-threaded Dynamic Link Library.
392 </para></listitem></varlistentry>
394 <varlistentry><term><filename>lib/yaz.lib</filename></term>
396 Import library for <filename>yaz.dll</filename>.
397 </para></listitem></varlistentry>
399 <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
401 &yaz; Z39.50 client application. It's a WIN32 console application.
402 See chapter <link linkend="client">YAZ client</link> for more
404 </para></listitem></varlistentry>
406 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
408 Z39.50 multi-threaded test/example server. It's a WIN32
410 </para></listitem></varlistentry>
412 <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
414 Simple console application implemented on top of the
415 <link linkend="zoom">ZOOM</link> functions.
416 The application is a command line shell that allows you to enter
417 simple commands perform to perform ZOOM operations.
418 </para></listitem></varlistentry>
420 <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
421 <filename>bin/zoomtst2.exe</filename>, ..</term>
423 Several small applications that demonstrates the ZOOM API.
424 </para></listitem></varlistentry>
429 <sect2><title>How to make apps using YAZ on WIN32</title>
431 This section will go though the process of linking your WIN32
432 applications with &yaz;.
435 Some people are confused by the fact that we use the nmake
436 tool to build &yaz;. They think they have to do that too - in order
437 to make their WIN32 applications work with &yaz;. The good news is that
438 you don't have to. You can use the integrated environment of
439 Visual Studio if desired for your own application.
442 When setting up a project or Makefile you have to set the following:
444 <varlistentry><term>include path</term><listitem><para>
445 Set it to the <filename>include</filename> directory of &yaz;.
446 </para></listitem></varlistentry>
447 <varlistentry><term>import library <filename>yaz.lib</filename>
448 </term><listitem><para>
449 You must link with this library. It's located in the
450 sub directory <filename>lib</filename> of &yaz;.
451 </para></listitem></varlistentry>
452 <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
453 </term><listitem><para>
454 This DLL must be in your execution path when you invoke
455 your application. Specifically, you should distribute this
456 DLL with your application.
457 </para></listitem></varlistentry>
464 <!-- Keep this comment at the end of the file
469 sgml-minimize-attributes:nil
470 sgml-always-quote-attributes:t
473 sgml-parent-document: "yaz.xml"
474 sgml-local-catalogs: nil
475 sgml-namecase-general:t