1 <!-- $Id: installation.xml,v 1.12 2002-08-17 07:55:51 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/W2K (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 <varlistentry><term><literal>--enable-threads</literal></term>
125 <listitem><para>&yaz; will be built using POSIX threads.
126 Specifically, <constant>_REENTRANT</constant> will be defined during
130 <varlistentry><term><literal>--with-openssl</literal></term>
131 <listitem><para>&yaz; will be linked with the OpenSSL libraries and
132 an SSL COMSTACK will be provided. Note that SSL support is still
136 <varlistentry><term><literal>--enable-shared</literal></term>
137 <listitem><para>The make process will create shared
138 libraries (also known as shared objects <filename>.so</filename>).
139 By default, no shared libraries are created -
140 equivalent to <literal>--disable-shared</literal>.
143 <varlistentry><term><literal>--disable-shared</literal></term>
144 <listitem><para>The make process will not create
145 static libraries (<filename>.a</filename>).
146 By default, static libraries are created -
147 equivalent to <literal>--enable-static</literal>.
154 When configured, build the software by typing:
162 The following files are generated by the make process:
164 <varlistentry><term><filename>lib/libyaz.la</filename></term>
166 Main &yaz; library. This is no ordinary library. It's
168 By default, &yaz; creates a static library in
169 <filename>lib/.libs/libyaz.a</filename>.
170 </para></listitem></varlistentry>
172 <varlistentry><term><filename>lib/libyazthread.la</filename></term>
174 When threading is supported/enabled by configure this Libtool
175 library is created. It includes functions that allows &yaz;
177 </para></listitem></varlistentry>
179 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
180 <listitem><para>Test Z39.50 server.
181 </para></listitem></varlistentry>
183 <varlistentry><term><filename>client/yaz-client</filename></term>
184 <listitem><para>Z39.50 client for testing the protocol.
185 See chapter <link linkend="client">
186 YAZ client</link> for more information.
187 </para></listitem></varlistentry>
189 <varlistentry><term><filename>yaz-config</filename></term>
190 <listitem><para>A Bourne-shell script, generated by configure, that
191 specifies how external applications should compile - and link with
193 </para></listitem></varlistentry>
195 <varlistentry><term><filename>yaz-comp</filename></term>
196 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
197 Tcl Shell, <application>tclsh</application>, in
198 <literal>PATH</literal> to operate.
199 </para></listitem></varlistentry>
201 <varlistentry><term><filename>zoom/zoomsh</filename></term>
203 A simple shell implemented on top of the
204 <link linkend="zoom">ZOOM</link> functions.
205 The shell is a command line application that allows you to enter
206 simple commands to perform ZOOM operations.
207 </para></listitem></varlistentry>
209 <varlistentry><term><filename>zoom/zoomtst1</filename>,
210 <filename>zoom/zoomtst2</filename>, ..</term>
212 Several small applications that demonstrates the ZOOM API.
213 </para></listitem></varlistentry>
219 If you wish to install &yaz; in system directories
220 <filename>/usr/local/bin</filename>,
221 <filename>/usr/local/lib</filename> .. etc, you can type:
229 You probably need to have root access in order to perform this.
230 You must specify the <literal>--prefix</literal> option for configure if
231 you wish to install &yaz; in other directories than the default
232 <filename>/usr/local/</filename>.
236 If you wish to perform an un-installation of &yaz;, use:
244 This will only work if you haven't reconfigured &yaz; (and therefore
245 changed installation prefix). Note that uninstall will not
246 remove directories created by make install, e.g.
247 <filename>/usr/local/include/yaz</filename>.
250 <sect2><title>How to make apps using YAZ on UNIX</title>
252 This section describes how to compile - and link your own
253 applications using the &yaz; toolkit.
254 If you're used to Makefiles this shouldn't be hard. As for
255 other libraries you have used before, you have to set a proper include
256 path for your C/C++ compiler and specify the location of
257 &yaz; libraries. You can do it by hand, but generally we suggest
258 you use the <filename>yaz-config</filename> that is generated
259 by <filename>configure</filename>. This is especially
260 important if you're using the threaded version of &yaz; which
261 require you to pass more options to your linker/compiler.
264 The <filename>yaz-config</filename> script accepts command line
265 options that makes the <filename>yaz-config</filename> script print
266 options that you should use in your make process.
267 The most important ones are:
268 <literal>--cflags</literal>, <literal>--libs</literal>
269 which prints C compiler flags, and linker flags respectively.
272 A small and complete <literal>Makefile</literal> for a C
273 application consisting of one source file,
274 <filename>myprog.c</filename>, may look like this:
276 YAZCONFIG=/usr/local/bin/yaz-config
277 CFLAGS=`$(YAZCONFIG) --cflags`
278 LIBS=`$(YAZCONFIG) --libs`
280 $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
284 The CFLAGS variable consists of a C compiler directive that will set
285 the include path to the <emphasis>parent</emphasis> directory
286 of <filename>yaz</filename>. That is, if &yaz; header files were
287 installed in <filename>/usr/local/include/yaz</filename>,
288 then include path is set to <filename>/usr/local/include</filename>.
289 Therefore, in your applications you should use
291 #include <yaz/proto.h>
293 and <emphasis>not</emphasis>
295 #include <proto.h>
299 For Libtool users, the <filename>yaz-config</filename> script provides
300 a different variant of option <literal>--libs</literal>, called
301 <literal>--lalibs</literal> that returns the name of the
302 Libtool acrhive(s) for &yaz; rather than the ordinary ones.
305 For applications using the threaded version of &yaz;,
306 specify <literal>threads</literal> after the
307 other options. When <literal>threads</literal> is given,
308 more flags and linker flags will be printed by
309 <filename>yaz-config</filename>. If our previous example was
310 using threads, you'd have to modify the lines that set
311 <literal>CFLAGS</literal> and <literal>LIBS</literal> as
314 CFLAGS=`$(YAZCONFIG) --cflags threads`
315 LIBS=`$(YAZCONFIG) --libs threads`
317 There is no need specify POSIX thread libraries in your Makefile.
318 The <literal>LIBS</literal> variable includes that as well.
322 <sect1 id="installation.win32"><title>WIN32</title>
325 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
326 with Microsoft Visual C++. Version 6 has been tested. We expect that
327 &yaz; should compile with version 5 as well.
330 Start a command prompt and switch the sub directory
331 <filename>WIN</filename> where the file <filename>makefile</filename>
332 is located. Customize the installation by editing the
333 <filename>makefile</filename> file (for example by using notepad).
335 The following summarizes the most important settings in that file:
338 <varlistentry><term><literal>DEBUG</literal></term>
340 If set to 1, the software is
341 compiled with debugging libraries (code generation is
342 multi-threaded debug DLL).
343 If set to 0, the software is compiled with release libraries
344 (code generation is multi-threaded DLL).
347 <varlistentry><term><literal>TCL</literal></term>
349 Specifies the name of the Tcl shell (EXE-file).
350 You do not need setting this or installing Tcl unless you wish
351 to change or add ASN.1 for &yaz;.
357 When satisfied with the settings in the makefile, type
361 If command <filename>nmake</filename> is not found on your system
362 you probably haven't defined the environment variables required to
363 use that tool. To fix that, find and run the batch file
364 <filename>vcvars32.bat</filename>. You need to run it from within
365 the command prompt or set the environment variables "globally";
366 otherwise it doesn't work.
369 If you wish to recompile &yaz; - for example if you modify
370 settings in the <filename>makefile</filename> you can delete
371 object files, etc by running.
377 The following files are generated upon successful compilation:
380 <varlistentry><term><filename>bin/yaz.dll</filename></term>
382 &yaz; multi-threaded Dynamic Link Library.
383 </para></listitem></varlistentry>
385 <varlistentry><term><filename>lib/yaz.lib</filename></term>
387 Import library for <filename>yaz.dll</filename>.
388 </para></listitem></varlistentry>
390 <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
392 &yaz; Z39.50 client application. It's a WIN32 console application.
393 See chapter <link linkend="client">YAZ client</link> for more
395 </para></listitem></varlistentry>
397 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
399 Z39.50 multi-threaded test/example server. It's a WIN32
401 </para></listitem></varlistentry>
403 <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
405 Simple console application implemented on top of the
406 <link linkend="zoom">ZOOM</link> functions.
407 The application is a command line shell that allows you to enter
408 simple commands perform to perform ZOOM operations.
409 </para></listitem></varlistentry>
411 <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
412 <filename>bin/zoomtst2.exe</filename>, ..</term>
414 Several small applications that demonstrates the ZOOM API.
415 </para></listitem></varlistentry>
420 <sect2><title>How to make apps using YAZ on WIN32</title>
422 This section will go though the process of linking your WIN32
423 applications with &yaz;.
426 Some people are confused by the fact that we use the nmake
427 tool to build &yaz;. They think they have to do that too - in order
428 to make their WIN32 applications work with &yaz;. The good news is that
429 you don't have to. You can use the integrated environment of
430 Visual Studio if desired for your own application.
433 When setting up a project or Makefile you have to set the following:
435 <varlistentry><term>include path</term><listitem><para>
436 Set it to the <filename>include</filename> directory of &yaz;.
437 </para></listitem></varlistentry>
438 <varlistentry><term>import library <filename>yaz.lib</filename>
439 </term><listitem><para>
440 You must link with this library. It's located in the
441 sub directory <filename>lib</filename> of &yaz;.
442 </para></listitem></varlistentry>
443 <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
444 </term><listitem><para>
445 This DLL must be in your execution path when you invoke
446 your application. Specifically, you should distribute this
447 DLL with your application.
448 </para></listitem></varlistentry>
455 <!-- Keep this comment at the end of the file
460 sgml-minimize-attributes:nil
461 sgml-always-quote-attributes:t
464 sgml-parent-document: "yaz.xml"
465 sgml-local-catalogs: nil
466 sgml-namecase-general:t