-<!-- $Id: installation.xml,v 1.13 2002-09-17 20:17:44 adam Exp $ -->
+<!-- $Id: installation.xml,v 1.14 2002-09-25 20:38:36 adam Exp $ -->
<chapter id="installation"><title>Compilation and Installation</title>
<sect1><title>Introduction</title>
<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>BSDs: FreeBSD, OpenBSD, NetBSD</para></listitem>
+ <listitem><para>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)
</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
</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
- <ulink url="http://gcc.gnu.org/">GCC</ulink>.
- </para>
- <para>
- 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>
- ./configure
- </screen>
-
+
<para>
- The configure script attempts to use use the C compiler specified by
- the <literal>CC</literal> environment variable. If not set, GNU C will be
- used if it is available. The <literal>CFLAGS</literal> environment
- variable holds options to be passed to the C compiler. If you're using
- Bourne-compatible shell you may pass something like this to use a
- particular C compiler with optimization enabled:
+ We provide Debian GNU/Linux and Redhat packages for YAZ.
+ Only i386 binary packages are available. You should be able to
+ create packages for other CPU's by building them from the source
+ package.
</para>
- <screen>
- CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
- </screen>
-
- <para>
- To customize &yaz;, the configure script also accepts a set of options.
- The most important are:
+ <sect2 id="installation.source.unix">
+ <title>Compiling from source on Unix</title>
- <variablelist>
- <varlistentry><term><literal>--prefix </literal>path</term>
- <listitem><para>Specifies installation prefix. This is
- only needed if you run <literal>make install</literal> later to
- perform a "system" installation. The prefix is
- <literal>/usr/local</literal> if not specified.
- </para></listitem>
- </varlistentry>
- <varlistentry><term><literal>--enable-tcpd</literal></term>
- <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>
- <listitem><para>&yaz; will be built using POSIX threads.
- Specifically, <constant>_REENTRANT</constant> will be defined during
- 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>
+ Note that if your system doesn't have a native ANSI C compiler, you may
+ have to acquire one separately. We recommend
+ <ulink url="http://gcc.gnu.org/">GCC</ulink>.
+ </para>
+ <para>
+ 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;.
+ </para>
+
+ <para>
+ If you wish to use character set conversion facilities in YAZ or if you
+ are compiling YAZ for use with Zebra it is a good idea to ensure that
+ the iconv library is installed. Most Unixes today already have it
+ - if not, we suggest
+ <ulink url="http://www.gnu.org/software/libiconv/">GNU iconv</ulink>.
+ </para>
+
+ <para>
+ Generally it should be sufficient to run configure without options,
+ like this:
+ </para>
- </para>
- <para>
- When configured, build the software by typing:
<screen>
- make
+ ./configure
</screen>
- </para>
-
- <para>
- The following files are generated by the make process:
- <variablelist>
- <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>
- 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>Test Z39.50 server.
- </para></listitem></varlistentry>
+
+ <para>
+ The configure script attempts to use use the C compiler specified by
+ the <literal>CC</literal> environment variable. If not set, GNU C will be
+ used if it is available. The <literal>CFLAGS</literal> environment
+ variable holds options to be passed to the C compiler. If you're using
+ Bourne-compatible shell you may pass something like this to use a
+ particular C compiler with optimization enabled:
+ </para>
+
+ <screen>
+ CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
+ </screen>
+
+ <para>
+ To customize &yaz;, the configure script also accepts a set of options.
+ The most important are:
- <varlistentry><term><filename>client/yaz-client</filename></term>
- <listitem><para>Z39.50 client for testing the protocol.
- See chapter <link linkend="client">
- YAZ client</link> for more information.
- </para></listitem></varlistentry>
+ <variablelist>
+ <varlistentry><term><literal>--prefix </literal>path</term>
+ <listitem><para>Specifies installation prefix. This is
+ only needed if you run <literal>make install</literal> later to
+ perform a "system" installation. The prefix is
+ <literal>/usr/local</literal> if not specified.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>--enable-tcpd</literal></term>
+ <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>
+ <listitem><para>&yaz; will be built using POSIX threads.
+ Specifically, <constant>_REENTRANT</constant> will be defined during
+ 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>
+
+ <varlistentry><term>
+ <literal>--with-iconv</literal>[=<replaceable>dir</replaceable>]</term>
+ <listitem><para>Compile YAZ with iconv library in directory
+ <replaceable>dir</replaceable>. By default configure will
+ search for iconv on your system. Use this option if it
+ doesn't find iconv. Alternatively you can use
+ <literal>--without-iconv</literal> to force YAZ not to use
+ iconv.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
- <varlistentry><term><filename>yaz-config</filename></term>
- <listitem><para>A Bourne-shell script, generated by configure, that
- specifies how external applications should compile - and link with
- &yaz;.
- </para></listitem></varlistentry>
+ </para>
+ <para>
+ When configured, build the software by typing:
+ <screen>
+ make
+ </screen>
+ </para>
+
+ <para>
+ The following files are generated by the make process:
+ <variablelist>
+ <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>
+ 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>Test Z39.50 server.
+ </para></listitem></varlistentry>
+
+ <varlistentry><term><filename>client/yaz-client</filename></term>
+ <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, 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
+ <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>
- <varlistentry><term><filename>yaz-comp</filename></term>
- <listitem><para>The ASN.1 compiler for &yaz;. Requires the
- 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>
-
- <para>
- If you wish to install &yaz; in system directories
- <filename>/usr/local/bin</filename>,
- <filename>/usr/local/lib</filename> .. etc, you can type:
- </para>
-
- <screen>
- make install
- </screen>
+ <para>
+ If you wish to install &yaz; in system directories
+ <filename>/usr/local/bin</filename>,
+ <filename>/usr/local/lib</filename> .. etc, you can type:
+ </para>
+
+ <screen>
+ make install
+ </screen>
- <para>
- You probably need to have root access in order to perform this.
- You must specify the <literal>--prefix</literal> option for configure if
+ <para>
+ You probably need to have root access in order to perform this.
+ You must specify the <literal>--prefix</literal> option for configure if
you wish to install &yaz; in other directories than the default
- <filename>/usr/local/</filename>.
- </para>
-
- <para>
- If you wish to perform an un-installation of &yaz;, use:
- </para>
-
- <screen>
- make uninstall
- </screen>
-
- <para>
- This will only work if you haven't reconfigured &yaz; (and therefore
- changed installation prefix). Note that uninstall will not
- remove directories created by make install, e.g.
- <filename>/usr/local/include/yaz</filename>.
- </para>
+ <filename>/usr/local/</filename>.
+ </para>
+
+ <para>
+ If you wish to perform an un-installation of &yaz;, use:
+ </para>
+
+ <screen>
+ make uninstall
+ </screen>
+
+ <para>
+ This will only work if you haven't reconfigured &yaz; (and therefore
+ changed installation prefix). Note that uninstall will not
+ remove directories created by make install, e.g.
+ <filename>/usr/local/include/yaz</filename>.
+ </para>
+ </sect2>
<sect2><title>How to make apps using YAZ on UNIX</title>
<para>
</sect1>
<sect1 id="installation.win32"><title>WIN32</title>
- <para>
- &yaz; is shipped with "makefiles" for the NMAKE tool that comes
- 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 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>The easiest way to install YAZ on Windows is by downloading
+ an installer from
+ <ulink url="http://ftp.indexdata.dk/pub/yaz/win32">here</ulink>.
+ The installer comes with source too - in case you wish to
+ compile YAZ with different Compiler options etc.
</para>
- <para>
- 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>
- &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-client.exe</filename></term>
- <listitem><para>
- &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>
+
+ <sect2 id="installation.win32.source">
+ <title>Compiling from Source on WIN32</title>
+ <para>
+ &yaz; is shipped with "makefiles" for the NMAKE tool that comes
+ 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).
- <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
- <listitem><para>
- Z39.50 multi-threaded test/example server. It's a WIN32
- console application.
- </para></listitem></varlistentry>
+ The following summarizes the most important settings in that file:
- <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>
+ <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>
+
+ <varlistentry>
+ <term><literal>HAVE_ICONV</literal>, <literal>ICONV_DIR</literal></term>
+ <listitem><para>
+ If <literal>HAVE_ICONV</literal> is set to 1, YAZ is compiled
+ with iconv support. In this configuration, set
+ <literal>ICONV_DIR</literal> to the iconv source directory.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ <para>
+ 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:
- <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>
+ <varlistentry><term><filename>bin/yaz.dll</filename></term>
+ <listitem><para>
+ &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-client.exe</filename></term>
+ <listitem><para>
+ &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>
+ 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 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>
- </variablelist>
-
- </para>
+ </para>
+ </sect2>
+
<sect2><title>How to make apps using YAZ on WIN32</title>
<para>
This section will go though the process of linking your WIN32
projects / yaz-moved-to-github.git / commitdiff