-<!-- $Header: /home/cvsroot/yaz/doc/installation.xml,v 1.1 2001-01-04 13:36:24 adam Exp $ -->
-<chapter><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.
-
-<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>
-<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><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.
-</para>
-<para>
-For UNIX we use GNU configure to create Makefiles for &yaz;.
-Generally it should be sufficient to run configure without options:
-</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:
-</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:
-
-<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-comp </literal></term>
-<listitem><para> &yaz; will be built using the ASN.1 compiler for &yaz;
-(default). If you wish to use the old decoders (in sub directory asn)
-use <literal>--disable-comp</literal> instead.
-</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>
-</variablelist>
-
-</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.a</filename></term>
-<listitem><para>
-The &yaz; programmers' library.
-</para></listitem></varlistentry>
-
-<varlistentry><term><filename>ztest/yaz-ztest</filename></term>
-<listitem><para>A test Z39.50 server.
-</para></listitem></varlistentry>
-
-<varlistentry><term><filename>client/yaz-client</filename></term>
-<listitem><para>A command mode Z39.50 client.
-</para></listitem></varlistentry>
-
-<varlistentry><term><filename>yaz-config</filename></term>
-<listitem><para>A Bourne-shell script that holds build
-settings for &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.
-</para></listitem></varlistentry>
-</variablelist>
-
-</para>
-
-<para>
-If you wish to install &yaz; in system directories such as
-<filename>/usr/local/bin</filename>,
-<filename>/usr/local/lib</filename> 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
-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>
-
-</sect1>
-<sect1><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 <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>NEW_Z3950</literal></entry>
-<entry> If 1, the auto-generated decoder/encoders
-for Z39.50 as written by the ASN.1 compiler will be used. If 0, the old
-decoders for Z39.50 will be used. Note, when 1, the setting TCL should
-point to the Tcl shell on your system.
-</entry>
-</row>
-
-<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>
-
-</para>
-<para>
-When satisfied with the settings in the makefile type
-<screen>
- nmake
-</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.
-</para></listitem></varlistentry>
-
-<varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
-<listitem><para>
-A console Z39.50 client application.
-</para></listitem></varlistentry>
-
-<varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
-<listitem><para>
-A console Z39.50 multi threaded server.
-</para></listitem></varlistentry>
-
-</variablelist>
-
-</para>
-</sect1>
-</chapter>
-
+<!-- $Id: installation.xml,v 1.6 2001-10-24 21:30:47 adam Exp $ -->
+ <chapter id="installation"><title>Compilation and Installation</title>
+
+ <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>OpenBSD/FreeBSD</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>
+ <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
+ <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>
+ is 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:
+ </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:
+
+ <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
+ commonly used in Linux/BSD distributions.
+ </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>
+ </variablelist>
+
+ </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 GNU 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, generate 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 perform 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 use of ZOOM.
+ </para></listitem></varlistentry>
+ </variablelist>
+
+ </para>
+
+ <para>
+ If you wish to install &yaz; in system directories such as
+ <filename>/usr/local/bin</filename>,
+ <filename>/usr/local/lib</filename> 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
+ 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>
+
+ </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 summarises 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
+ <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>
+
+ <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 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 use of ZOOM.
+ </para></listitem></varlistentry>
+
+ </variablelist>
+
+ </para>
+ </sect1>
+ </chapter>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "yaz.xml"
+ sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-namecase-general:t
+ End:
+ -->
+
projects / yaz-moved-to-github.git / blobdiff