-<!-- $Id: installation.xml,v 1.4 2001-10-24 12:50:44 adam Exp $ -->
+<!-- $Id: installation.xml,v 1.13 2002-09-17 20:17:44 adam Exp $ -->
<chapter id="installation"><title>Compilation and Installation</title>
- <para>
- The latest version of the software will generally be found at
- </para>
- <para>
- <ulink url="http://ftp.indexdata.dk/pub/yaz/">
- http://ftp.indexdata.dk/pub/yaz/</ulink>
- </para>
- <para>
- We have tried our best to keep the software portable, and on many
- platforms, you should be able to compile everything with little or
- no changes.
- So far, the software has been ported to the following platforms with
- little or no difficulties.
+ <sect1><title>Introduction</title>
+ <para>
+ The latest version of the software will generally be found at:
+ </para>
+ <para>
+ <ulink url="http://ftp.indexdata.dk/pub/yaz/">
+ http://ftp.indexdata.dk/pub/yaz/</ulink>
+ </para>
+ <para>
+ We have tried our best to keep the software portable, and on many
+ platforms, you should be able to compile everything with little or
+ no changes.
+ So far, the software has been ported to the following platforms with
+ little or no difficulties.
+
+ <itemizedlist>
+ <listitem><para>Unix systems</para>
+ <itemizedlist>
+ <listitem><para>HP/UX</para></listitem>
+ <listitem><para>SunOS/Solaris</para></listitem>
+ <listitem><para>DEC Unix</para></listitem>
+ <listitem><para>BSDs: FreeBSD, OpenBSD, NetBSD, MAC OSX
+ </para></listitem>
+ <listitem><para>Linux</para></listitem>
+ <listitem><para>IBM AIX</para></listitem>
+ <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
+ </para></listitem>
+ <listitem><para>SGI/IRIX</para></listitem>
+ <listitem><para>DDE Supermax</para></listitem>
+ </itemizedlist></listitem>
+ <listitem><para>Non-unix systems</para>
+ <itemizedlist>
+ <listitem><para>Apple Macintosh (using the Codewarrior programming
+ environment and the GUSI socket libraries)</para></listitem>
+ <listitem><para>MS Windows 95/98/NT/2K/XP (Win32)</para></listitem>
+ <listitem><para>IBM AS/400</para></listitem>
+ </itemizedlist></listitem>
+ </itemizedlist>
+
+ </para>
+ <para>
+ If you move the software to other platforms, we'd be grateful if you'd
+ let us know about it. If you run into difficulties, we will try to help
+ if we can, and if you solve the problems, we would be happy to include
+ your fixes in the next release. So far, we have mostly avoided
+ <literal>#ifdefs</literal> for individual platforms, and we'd
+ like to keep it that way as far as it makes sense.
+ </para>
- <itemizedlist>
- <listitem><para>Unix systems</para>
- <itemizedlist>
- <listitem><para>HP/UX</para></listitem>
- <listitem><para>SunOS/Solaris</para></listitem>
- <listitem><para>DEC Unix</para></listitem>
- <listitem><para>Linux</para></listitem>
- <listitem><para>IBM AIX</para></listitem>
- <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
- </para></listitem>
- <listitem><para>SGI/IRIX</para></listitem>
- <listitem><para>DDE Supermax</para></listitem>
- </itemizedlist></listitem>
- <listitem><para>Non-unix systems</para>
- <itemizedlist>
- <listitem><para>Apple Macintosh (using the Codewarrior programming
- environment and the GUSI socket libraries)</para></listitem>
- <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
- <listitem><para>IBM AS/400</para></listitem>
- </itemizedlist></listitem>
- </itemizedlist>
+ <para>
+ We maintain a mailing-list for the purpose of announcing new releases and
+ bug-fixes, as well as general discussion. Subscribe by sending mail to
+ <ulink url="mailto:yaz-request@indexdata.dk">
+ yaz-request@indexdata.dk
+ </ulink> or fill-in the form
+ <ulink url="http://www.indexdata.dk/mailman/listinfo/yazlist">
+ here</ulink>.
+ General questions and problems can be directed at
+ <ulink url="mailto:yaz-help@indexdata.dk">
+ yaz-help@indexdata.dk
+ </ulink>, or the address given at the top of this document.
+ </para>
- </para>
- <para>
- If you move the software to other platforms, we'd be grateful if you'd
- let us know about it. If you run into difficulties, we will try to help
- if we can, and if you solve the problems, we would be happy to include
- your fixes in the next release. So far, we have mostly avoided
- #ifdefs for individual platforms, and we'd like to keep it that
- way as far as it makes sense.
- </para>
-
- <para>
- We maintain a mailing-list for the purpose of announcing new releases and
- bug-fixes, as well as general discussion. Subscribe by sending mail to
- <ulink url="mailto:yaz-request@indexdata.dk">
- yaz-request@indexdata.dk
- </ulink>.
- General questions and problems can be directed at
- <ulink url="mailto:yaz-help@indexdata.dk">
- yaz-help@indexdata.dk
- </ulink>, or the address given at the top of this document.
- </para>
-
+ </sect1>
<sect1 id="installation.unix"><title>UNIX</title>
<para>
Note that if your system doesn't have a native ANSI C compiler, you may
- have to acquire one separately. We recommend gcc.
+ have to acquire one separately. We recommend
+ <ulink url="http://gcc.gnu.org/">GCC</ulink>.
</para>
<para>
- For UNIX we use GNU configure to create Makefiles for &yaz;.
- Generally it should be sufficient to run configure without options:
+ For UNIX, the GNU tools
+ <ulink url="http://www.gnu.org/software/autoconf/">Autoconf</ulink>,
+ <ulink url="http://www.gnu.org/software/automake/">Automake</ulink> and
+ <ulink url="http://www.gnu.org/software/libtool/">Libtool</ulink>
+ are used to generate Makefiles and configure &yaz; for the system.
+ You do <emphasis>not</emphasis> these tools unless you're using the
+ CVS version of &yaz;.
+ Generally it should be sufficient to run configure without options,
+ like this:
</para>
<screen>
</screen>
<para>
- To customize &yaz; the configure script also accepts a set of options.
+ To customize &yaz;, the configure script also accepts a set of options.
The most important are:
<variablelist>
</para></listitem>
</varlistentry>
<varlistentry><term><literal>--enable-tcpd</literal></term>
- <listitem><para>The front end server will be built using the TCP
- wrapper library. It allows you to disallow/deny clients depending
- on IP.
+ <listitem><para>The front end server will be built using Wietse's
+ <ulink url="ftp://ftp.porcupine.org/pub/security/index.html">
+ TCP wrapper library</ulink>. It allows you to allow/deny
+ clients depending on IP number. The TCP wrapper library is
+ often used in Linux/BSD distributions.
+ See
+ <citerefentry>
+ <refentrytitle>hosts_access</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>tcpd</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>--enable-threads</literal></term>
compilation.
</para></listitem>
</varlistentry>
+ <varlistentry><term><literal>--with-openssl</literal></term>
+ <listitem><para>&yaz; will be linked with the OpenSSL libraries and
+ an SSL COMSTACK will be provided. Note that SSL support is still
+ experimental.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>--enable-shared</literal></term>
+ <listitem><para>The make process will create shared
+ libraries (also known as shared objects <filename>.so</filename>).
+ By default, no shared libraries are created -
+ equivalent to <literal>--disable-shared</literal>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>--disable-shared</literal></term>
+ <listitem><para>The make process will not create
+ static libraries (<filename>.a</filename>).
+ By default, static libraries are created -
+ equivalent to <literal>--enable-static</literal>.
+ </para></listitem>
+ </varlistentry>
</variablelist>
</para>
<screen>
make
</screen>
-
</para>
<para>
The following files are generated by the make process:
<variablelist>
- <varlistentry><term><filename>lib/libyaz.a</filename></term>
+ <varlistentry><term><filename>lib/libyaz.la</filename></term>
+ <listitem><para>
+ Main &yaz; library. This is no ordinary library. It's
+ a Libtool archive.
+ By default, &yaz; creates a static library in
+ <filename>lib/.libs/libyaz.a</filename>.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>lib/libyazthread.la</filename></term>
<listitem><para>
- The &yaz; programmers' library.
+ When threading is supported/enabled by configure this Libtool
+ library is created. It includes functions that allows &yaz;
+ to use threads.
</para></listitem></varlistentry>
<varlistentry><term><filename>ztest/yaz-ztest</filename></term>
- <listitem><para>A test Z39.50 server.
+ <listitem><para>Test Z39.50 server.
</para></listitem></varlistentry>
<varlistentry><term><filename>client/yaz-client</filename></term>
- <listitem><para>A command mode Z39.50 client.
+ <listitem><para>Z39.50 client for testing the protocol.
+ See chapter <link linkend="client">
+ YAZ client</link> for more information.
</para></listitem></varlistentry>
<varlistentry><term><filename>yaz-config</filename></term>
- <listitem><para>A Bourne-shell script that holds build
- settings for &yaz;.
+ <listitem><para>A Bourne-shell script, generated by configure, that
+ specifies how external applications should compile - and link with
+ &yaz;.
</para></listitem></varlistentry>
<varlistentry><term><filename>yaz-comp</filename></term>
<listitem><para>The ASN.1 compiler for &yaz;. Requires the
- Tcl Shell, <application>tclsh</application>, in current path to work.
+ Tcl Shell, <application>tclsh</application>, in
+ <literal>PATH</literal> to operate.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>zoom/zoomsh</filename></term>
+ <listitem><para>
+ A simple shell implemented on top of the
+ <link linkend="zoom">ZOOM</link> functions.
+ The shell is a command line application that allows you to enter
+ simple commands to perform ZOOM operations.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>zoom/zoomtst1</filename>,
+ <filename>zoom/zoomtst2</filename>, ..</term>
+ <listitem><para>
+ Several small applications that demonstrates the ZOOM API.
</para></listitem></varlistentry>
</variablelist>
</para>
<para>
- If you wish to install &yaz; in system directories such as
+ If you wish to install &yaz; in system directories
<filename>/usr/local/bin</filename>,
- <filename>/usr/local/lib</filename> you can type:
+ <filename>/usr/local/lib</filename> .. etc, you can type:
</para>
<screen>
</para>
<para>
- If you wish to perform an un-installation of &yaz; use:
+ If you wish to perform an un-installation of &yaz;, use:
</para>
<screen>
remove directories created by make install, e.g.
<filename>/usr/local/include/yaz</filename>.
</para>
-
+
+ <sect2><title>How to make apps using YAZ on UNIX</title>
+ <para>
+ This section describes how to compile - and link your own
+ applications using the &yaz; toolkit.
+ If you're used to Makefiles this shouldn't be hard. As for
+ other libraries you have used before, you have to set a proper include
+ path for your C/C++ compiler and specify the location of
+ &yaz; libraries. You can do it by hand, but generally we suggest
+ you use the <filename>yaz-config</filename> that is generated
+ by <filename>configure</filename>. This is especially
+ important if you're using the threaded version of &yaz; which
+ require you to pass more options to your linker/compiler.
+ </para>
+ <para>
+ The <filename>yaz-config</filename> script accepts command line
+ options that makes the <filename>yaz-config</filename> script print
+ options that you should use in your make process.
+ The most important ones are:
+ <literal>--cflags</literal>, <literal>--libs</literal>
+ which prints C compiler flags, and linker flags respectively.
+ </para>
+ <para>
+ A small and complete <literal>Makefile</literal> for a C
+ application consisting of one source file,
+ <filename>myprog.c</filename>, may look like this:
+ <screen>
+ YAZCONFIG=/usr/local/bin/yaz-config
+ CFLAGS=`$(YAZCONFIG) --cflags`
+ LIBS=`$(YAZCONFIG) --libs`
+ myprog: myprog.o
+ $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
+ </screen>
+ </para>
+ <para>
+ The CFLAGS variable consists of a C compiler directive that will set
+ the include path to the <emphasis>parent</emphasis> directory
+ of <filename>yaz</filename>. That is, if &yaz; header files were
+ installed in <filename>/usr/local/include/yaz</filename>,
+ then include path is set to <filename>/usr/local/include</filename>.
+ Therefore, in your applications you should use
+ <screen>
+ #include <yaz/proto.h>
+ </screen>
+ and <emphasis>not</emphasis>
+ <screen>
+ #include <proto.h>
+ </screen>
+ </para>
+ <para>
+ For Libtool users, the <filename>yaz-config</filename> script provides
+ a different variant of option <literal>--libs</literal>, called
+ <literal>--lalibs</literal> that returns the name of the
+ Libtool acrhive(s) for &yaz; rather than the ordinary ones.
+ </para>
+ <para>
+ For applications using the threaded version of &yaz;,
+ specify <literal>threads</literal> after the
+ other options. When <literal>threads</literal> is given,
+ more flags and linker flags will be printed by
+ <filename>yaz-config</filename>. If our previous example was
+ using threads, you'd have to modify the lines that set
+ <literal>CFLAGS</literal> and <literal>LIBS</literal> as
+ follows:
+ <screen>
+ CFLAGS=`$(YAZCONFIG) --cflags threads`
+ LIBS=`$(YAZCONFIG) --libs threads`
+ </screen>
+ There is no need specify POSIX thread libraries in your Makefile.
+ The <literal>LIBS</literal> variable includes that as well.
+ </para>
+ </sect2>
</sect1>
<sect1 id="installation.win32"><title>WIN32</title>
<para>
&yaz; is shipped with "makefiles" for the NMAKE tool that comes
- with Visual C++.
-
- Start an MS-DOS prompt and switch the sub directory
+ with Microsoft Visual C++. Version 6 has been tested. We expect that
+ &yaz; should compile with version 5 as well.
+ </para>
+ <para>
+ Start a command prompt and switch the sub directory
<filename>WIN</filename> where the file <filename>makefile</filename>
is located. Customize the installation by editing the
<filename>makefile</filename> file (for example by using notepad).
- The following summarises the most important settings in that file:
-
- <table frame="top"><title>WIN32 makefile settings</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Setting</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>DEBUG</literal></entry>
- <entry> If set to 1, the software is
- compiled with debugging libraries. If set to 0, the software
- is compiled with release (non-debugging) libraries.
- </entry>
- </row>
-
- <row>
- <entry><literal>TCL</literal></entry>
- <entry> Specifies the name of the Tcl shell (EXE-file).
- You do not need setting this or installing Tcl unless you wish
- to change or add ASN.1 for &yaz;.
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
+ The following summarizes the most important settings in that file:
+
+ <variablelist>
+ <varlistentry><term><literal>DEBUG</literal></term>
+ <listitem><para>
+ If set to 1, the software is
+ compiled with debugging libraries (code generation is
+ multi-threaded debug DLL).
+ If set to 0, the software is compiled with release libraries
+ (code generation is multi-threaded DLL).
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>TCL</literal></term>
+ <listitem><para>
+ Specifies the name of the Tcl shell (EXE-file).
+ You do not need setting this or installing Tcl unless you wish
+ to change or add ASN.1 for &yaz;.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
</para>
<para>
- When satisfied with the settings in the makefile type
+ When satisfied with the settings in the makefile, type
<screen>
nmake
</screen>
+ If command <filename>nmake</filename> is not found on your system
+ you probably haven't defined the environment variables required to
+ use that tool. To fix that, find and run the batch file
+ <filename>vcvars32.bat</filename>. You need to run it from within
+ the command prompt or set the environment variables "globally";
+ otherwise it doesn't work.
+ </para>
+ <para>
+ If you wish to recompile &yaz; - for example if you modify
+ settings in the <filename>makefile</filename> you can delete
+ object files, etc by running.
+ <screen>
+ nmake clean
+ </screen>
</para>
<para>
The following files are generated upon successful compilation:
<variablelist>
<varlistentry><term><filename>bin/yaz.dll</filename></term>
<listitem><para>
- the multi-threaded &yaz; DLL.
+ &yaz; multi-threaded Dynamic Link Library.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>lib/yaz.lib</filename></term>
+ <listitem><para>
+ Import library for <filename>yaz.dll</filename>.
</para></listitem></varlistentry>
- <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
+ <varlistentry><term><filename>bin/yaz-client.exe</filename></term>
<listitem><para>
- A console Z39.50 client application.
+ &yaz; Z39.50 client application. It's a WIN32 console application.
+ See chapter <link linkend="client">YAZ client</link> for more
+ information.
</para></listitem></varlistentry>
<varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
<listitem><para>
- A console Z39.50 multi threaded server.
+ Z39.50 multi-threaded test/example server. It's a WIN32
+ console application.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>bin/zoomsh.exe</filename></term>
+ <listitem><para>
+ Simple console application implemented on top of the
+ <link linkend="zoom">ZOOM</link> functions.
+ The application is a command line shell that allows you to enter
+ simple commands perform to perform ZOOM operations.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>bin/zoomtst1.exe</filename>,
+ <filename>bin/zoomtst2.exe</filename>, ..</term>
+ <listitem><para>
+ Several small applications that demonstrates the ZOOM API.
</para></listitem></varlistentry>
</variablelist>
</para>
+ <sect2><title>How to make apps using YAZ on WIN32</title>
+ <para>
+ This section will go though the process of linking your WIN32
+ applications with &yaz;.
+ </para>
+ <para>
+ Some people are confused by the fact that we use the nmake
+ tool to build &yaz;. They think they have to do that too - in order
+ to make their WIN32 applications work with &yaz;. The good news is that
+ you don't have to. You can use the integrated environment of
+ Visual Studio if desired for your own application.
+ </para>
+ <para>
+ When setting up a project or Makefile you have to set the following:
+ <variablelist>
+ <varlistentry><term>include path</term><listitem><para>
+ Set it to the <filename>include</filename> directory of &yaz;.
+ </para></listitem></varlistentry>
+ <varlistentry><term>import library <filename>yaz.lib</filename>
+ </term><listitem><para>
+ You must link with this library. It's located in the
+ sub directory <filename>lib</filename> of &yaz;.
+ </para></listitem></varlistentry>
+ <varlistentry><term>dynamic link library <filename>yaz.dll</filename>
+ </term><listitem><para>
+ This DLL must be in your execution path when you invoke
+ your application. Specifically, you should distribute this
+ DLL with your application.
+ </para></listitem></varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
</sect1>
</chapter>
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->
projects / yaz-moved-to-github.git / blobdiff