X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Finstallation.xml;h=35b0a4f0d1d9f2267c863142f6f04698d6bacf2e;hb=13473bcae713a0df158fd9620fbeba13663459ca;hp=cbd4abdfb09064519316afce388e6363b7ee5c43;hpb=0f72f09a46621eb0aa9960b990dd35c221333e4d;p=yaz-moved-to-github.git
diff --git a/doc/installation.xml b/doc/installation.xml
index cbd4abd..35b0a4f 100644
--- a/doc/installation.xml
+++ b/doc/installation.xml
@@ -1,267 +1,711 @@
-
-Compilation and Installation
-
-
-The latest version of the software will generally be found at
-
-
-
-http://ftp.indexdata.dk/pub/yaz/
-
-
-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.
-
-
-Unix systems
-
-HP/UX
-SunOS/Solaris
-DEC Unix
-Linux
-IBM AIX
-Data General DG/UX (with some CFLAGS tinkering)
-
-SGI/IRIX
-DDE Supermax
-
-Non-unix systems
-
-Apple Macintosh (using the Codewarrior programming
-environment and the GUSI socket libraries)
-MS Windows 95/98/NT/W2K (Win32)
-IBM AS/400
-
-
-
-
-
-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.
-
-
-
-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
-yaz-request@indexdata.dk.
-General questions and problems can be directed at
-yaz-help@indexdata.dk, or
-the address given at the top of this document.
-
-
-UNIX
-
-
-Note that if your system doesn't have a native ANSI C compiler, you may
-have to acquire one separately. We recommend gcc.
-
-
-For UNIX we use GNU configure to create Makefiles for &yaz;.
-Generally it should be sufficient to run configure without options:
-
-
-
- ./configure
-
-
-
-The configure script attempts to use use the C compiler specified by
-the CC environment variable. If not set, GNU C will be
-used if it is available. The CFLAGS 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:
-
-
-
- CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
-
-
-
-To customize &yaz; the configure script also accepts a set of options.
-The most important are:
-
-
---prefix path
-Specifies installation prefix. This is
-only needed if you run make install later to perform a
-"system" installation. The prefix is /usr/local if not
-specified.
-
-
-
---enable-comp
- &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 --disable-comp instead.
-
-
---enable-threads
-&yaz; will be built using POSIX threads.
-Specifically, _REENTRANT will be defined during
-compilation.
-
-
-
-
-
-
-When configured, build the software by typing:
-
- make
-
-
-
-
-
-The following files are generated by the make process:
-
-lib/libyaz.a
-
-The &yaz; programmers' library.
-
-
-ztest/yaz-ztest
-A test Z39.50 server.
-
-
-client/yaz-client
-A command mode Z39.50 client.
-
-
-yaz-config
-A Bourne-shell script that holds build
-settings for &yaz;.
-
-
-yaz-comp
-The ASN.1 compiler for &yaz;. Requires the
-Tcl Shell, tclsh, in current path to work.
-
-
-
-
-
-
-If you wish to install &yaz; in system directories such as
-/usr/local/bin,
-/usr/local/lib you can type:
-
-
-
- make install
-
-
-
-You probably need to have root access in order to perform this.
-You must specify the --prefix option for configure if
-you wish to install &yaz; in other directories than the default
-/usr/local/.
-
-
-
-If you wish to perform an un-installation of &yaz; use:
-
-
-
- make uninstall
-
-
-
-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.
-/usr/local/include/yaz.
-
-
-
-WIN32
-
-
-&yaz; is shipped with "makefiles" for the NMAKE tool that comes
-with Visual C++.
-
-Start an MS-DOS prompt and switch the sub directory WIN
-where the file makefile is located. Customize the
-installation by editing the makefile file (for example
-by using notepad).
-
-The following summarises the most important settings in that file:
-
-
WIN32 makefile settings
-
-
-
-Setting
-Description
-
-
-
-
-
-NEW_Z3950
- 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.
-
-
-
-
-DEBUG
- If set to 1, the software is
-compiled with debugging libraries. If set to 0, the software
-is compiled with release (non-debugging) libraries.
-
-
-
-
-TCL
- 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;.
-
-
-
-
-
-
-
-
-
-When satisfied with the settings in the makefile type
-
- nmake
-
-
-
-The following files are generated upon successful compilation:
-
-
-bin/yaz.dll
-
-the multi-threaded &yaz; DLL.
-
-
-bin/yaz-ztest.exe
-
-A console Z39.50 client application.
-
-
-bin/yaz-ztest.exe
-
-A console Z39.50 multi threaded server.
-
-
-
-
-
-
-
-
+
+ Compilation and Installation
+
+ Introduction
+
+ The latest version of the software will generally be found at:
+
+
+
+
+
+ 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.
+
+
+
+ The software is regularly tested on
+ Debian GNU/Linux,
+ Redhat Linux,
+ Gentoo Linux,
+ FreeBSD (i386),
+ MAC OSX,
+ SunOS 5.8 (sparc),
+ Windows 2000,
+ Windows 2003 server.
+
+
+
+ Some versions have be known to work on HP/UX,
+ DEC Unix, NetBSD,
+ OpenBSD,
+ IBM AIX,
+ Data General DG/UX (with some CFLAGS tinkering),
+ SGI/IRIX, DDE Supermax, Apple Macintosh (using the Codewarrior programming
+ environment and the GUSI socket libraries),
+ IBM AS/400 .
+
+
+
+ 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.
+
+
+
+ We maintain a mailing-list for the purpose of announcing new releases and
+ bug-fixes, as well as general discussion. Subscribe by
+ filling-in the form
+ here.
+ General questions and problems can be directed at
+ , or the address given at the top of
+ this document.
+
+
+
+ UNIX
+
+
+ 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 CPUs by building them from the source
+ package.
+
+
+
+ Compiling from source on Unix
+
+
+ Note that if your system doesn't have a native ANSI C compiler, you may
+ have to acquire one separately. We recommend
+ GCC.
+
+
+
+ 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. Some Unixes today already have it
+ - if not, we suggest
+ GNU libiconv.
+
+
+
+ The libxslt,
+ libxml2 librararies are required
+ if &yaz; is to support SRU.
+ These libraries are very portable and should compile out-of-the
+ box on virtually all Unix platforms. It is available in binary
+ forms for Linux and others.
+
+
+
+ The GNU tools
+ Autoconf,
+ Automake and
+ Libtool
+ are used to generate Makefiles and configure &yaz; for the system.
+ You do not these tools unless you're using the
+ CVS version of &yaz;.
+
+
+
+ YAZ can optionally be compiled with
+ libpcap support. By default,
+ configure enables libpcap if it is available.
+ The libpcap library is required for
+ ziffy. And without libpcap,
+ ziffy will not be built.
+
+
+
+ The CQL parser for &yaz; is built using
+ GNU Bison.
+ This tool is only needed if you're using the CVS version of &yaz;.
+
+
+
+ &yaz; includes a tiny ASN.1 compiler. This compiler is
+ written in Tcl.
+ But as for Bison you do not need it unless you're using CVS
+ version of &yaz; or you're using the compiler to built own codecs
+ for private ASN.1.
+
+
+
+ Generally it should be sufficient to run configure without options,
+ like this:
+
+
+
+ ./configure
+
+
+
+ The configure script attempts to use use the C compiler specified by
+ the CC environment variable. If not set, GNU C will be
+ used if it is available. The CFLAGS 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:
+
+
+
+ CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
+
+
+
+ To customize &yaz;, the configure script also accepts a set of options.
+ The most important are:
+
+
+
+ --prefix=prefix
+ Specifies installation prefix for &yaz;. This is
+ only needed if you run make install later to
+ perform a "system" installation. The prefix is
+ /usr/local if not specified.
+
+
+ --enable-tcpd
+ The front end server will be built using Wietse's
+ TCP wrapper library.
+ It allows you to allow/deny clients depending on IP number.
+ The TCP wrapper library is often used in GNU/Linux and
+ BSD distributions.
+ See
+
+ hosts_access
+ 5
+
+ and
+
+ tcpd
+ 8
+ .
+
+
+
+ --enable-threads
+ &yaz; will be built using POSIX threads.
+ Specifically, _REENTRANT will be defined during
+ compilation.
+
+
+
+ --disable-shared
+ The make process will not create shared
+ libraries (also known as shared objects .so).
+ By default, shared libraries are created -
+ equivalent to --enable-shared.
+
+
+
+ --disable-shared
+ The make process will not create
+ static libraries (.a).
+ By default, static libraries are created -
+ equivalent to --enable-static.
+
+
+
+
+ --with-iconv[=prefix]
+
+ Compile &yaz; with iconv library in directory
+ prefix. By default configure will
+ search for iconv on the system. Use this option if it
+ doesn't find iconv. Alternatively,
+ --without-iconv, can be uset to force &yaz;
+ not to use iconv.
+
+
+
+
+ --with-xslt[=prefix]
+
+ Compile &yaz; with
+ libxslt in directory
+ prefix.
+ Use this option if you want SRU support.
+ By default, configure will
+ search for libxslt on the system. Use this option if it
+ libxslt is not found automatically. Alternatively,
+ --without-xslt, can be used to force &yaz;
+ not to use libxslt.
+
+
+
+
+ --with-openssl[=prefix]
+
+ &yaz; will be linked with the OpenSSL libraries and
+ an SSL COMSTACK will be provided. Note that SSL support is still
+ experimental.
+
+
+
+
+ --with-libpcap[=prefix]
+
+ Compile &yaz; with
+ libpcap support and the
+ ziffy utility.
+
+
+
+
+
+
+
+ When configured, build the software by typing:
+
+ make
+
+
+
+
+ The following files are generated by the make process:
+
+ src/libyaz.la
+
+ Main &yaz; library. This is no ordinary library. It's
+ a Libtool archive.
+ By default, &yaz; creates a static library in
+ lib/.libs/libyaz.a.
+
+
+
+ src/libyaz_server.la
+
+ Generic Frontend server. This is an add-on for libyaz.la.
+ Code in this library uses POSIX threads functions - if they
+ available on the platform.
+
+
+
+ ztest/yaz-ztest
+ Test Z39.50 server.
+
+
+
+ client/yaz-client
+ Z39.50 client for testing the protocol.
+ See chapter
+ YAZ client for more information.
+
+
+
+ ziffy/ziffy
+ A promiscuous Z39.50 APDU sniffer.
+ ziffy is only built on systems where libpcap is available.
+ See for more information.
+
+
+
+ util/yaz-config
+ A Bourne-shell script, generated by configure, that
+ specifies how external applications should compile - and link with
+ &yaz;.
+
+
+
+ util/yaz-asncomp
+ The ASN.1 compiler for &yaz;. Requires the
+ Tcl Shell, tclsh, in
+ PATH to operate.
+
+
+
+ util/yaz-iconv
+ This program converts data in one character set to
+ another. This command exercises the YAZ character set
+ conversion API.
+
+
+
+ util/yaz-marcdump
+ This program parses ISO2709 encoded MARC records
+ and prints them in line-format or XML.
+
+
+
+ zoom/zoomsh
+
+ A simple shell implemented on top of the
+ ZOOM functions.
+ The shell is a command line application that allows you to enter
+ simple commands to perform ZOOM operations.
+
+
+
+ zoom/zoomtst1,
+ zoom/zoomtst2, ..
+
+ Several small applications that demonstrates the ZOOM API.
+
+
+
+
+
+
+
+ If you wish to install &yaz; in system directories
+ /usr/local/bin,
+ /usr/local/lib .. etc, you can type:
+
+
+
+ make install
+
+
+
+ You probably need to have root access in order to perform this.
+ You must specify the --prefix option for configure if
+ you wish to install &yaz; in other directories than the default
+ /usr/local/.
+
+
+
+ If you wish to perform an un-installation of &yaz;, use:
+
+
+
+ make uninstall
+
+
+
+ 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.
+ /usr/local/include/yaz.
+
+
+
+
+ How to make apps using YAZ on UNIX
+
+ 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 yaz-config that is generated
+ by configure. This is especially
+ important if you're using the threaded version of &yaz; which
+ require you to pass more options to your linker/compiler.
+
+
+ The yaz-config script accepts command line
+ options that makes the yaz-config script print
+ options that you should use in your make process.
+ The most important ones are:
+ --cflags, --libs
+ which prints C compiler flags, and linker flags respectively.
+
+
+ A small and complete Makefile for a C
+ application consisting of one source file,
+ myprog.c, may look like this:
+
+ YAZCONFIG=/usr/local/bin/yaz-config
+ CFLAGS=`$(YAZCONFIG) --cflags`
+ LIBS=`$(YAZCONFIG) --libs`
+ myprog: myprog.o
+ $(CC) $(CFLAGS) -o myprog myprog.o $(LIBS)
+
+
+
+ The CFLAGS variable consists of a C compiler directive that will set
+ the include path to the parent directory
+ of yaz. That is, if &yaz; header files were
+ installed in /usr/local/include/yaz,
+ then include path is set to /usr/local/include.
+ Therefore, in your applications you should use
+
+ #include <yaz/proto.h>
+
+ and not
+
+ #include <proto.h>
+
+
+
+ For Libtool users, the yaz-config script provides
+ a different variant of option --libs, called
+ --lalibs that returns the name of the
+ Libtool acrhive(s) for &yaz; rather than the ordinary ones.
+
+
+ For applications using the threaded version of &yaz;,
+ specify threads after the
+ other options. When threads is given,
+ more flags and linker flags will be printed by
+ yaz-config. If our previous example was
+ using threads, you'd have to modify the lines that set
+ CFLAGS and LIBS as
+ follows:
+
+ CFLAGS=`$(YAZCONFIG) --cflags threads`
+ LIBS=`$(YAZCONFIG) --libs threads`
+
+ There is no need specify POSIX thread libraries in your Makefile.
+ The LIBS variable includes that as well.
+
+
+
+ WIN32
+
+ The easiest way to install YAZ on Windows is by downloading
+ an installer from
+ here.
+ The installer comes with source too - in case you wish to
+ compile YAZ with different Compiler options etc.
+
+
+
+ Compiling from Source on WIN32
+
+ &yaz; is shipped with "makefiles" for the NMAKE tool that comes
+ with
+ Microsoft Visual Studio.
+ Version 6 and .NET has been tested. We expect that &yaz; compiles
+ with version 5 as well.
+
+
+ Start a command prompt and switch the sub directory
+ WIN where the file makefile
+ is located. Customize the installation by editing the
+ makefile file (for example by using notepad).
+
+ The following summarizes the most important settings in that file:
+
+
+ DEBUG
+
+ 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).
+
+
+
+ HAVE_TCL, TCL
+
+ If HAVE_TCL is set to 1, nmake will
+ use the ASN.1 compiler (Tcl based). You must set
+ TCL to the full path of the Tcl
+ interpreter.
+
+
+ If you do not have Tcl installed, set
+ HAVE_TCL to 0.
+
+
+
+
+ HAVE_BISON,
+ BISON
+
+ If GNU Bison is present, you might set HAVE_ICONV
+ to 1 and specify the Bison executable in BISON.
+ Bison is only required if you use the CVS version of
+ YAZ or if you modify the grammar for CQL
+ (cql.y).
+
+
+ A Windows version of GNU Bison is part of
+ unxutils.
+
+
+
+
+ HAVE_ICONV,
+ ICONV_DIR
+
+ If HAVE_ICONV is set to 1, YAZ is compiled
+ with iconv support. In this configuration, set
+ ICONV_DIR to the iconv source directory.
+
+
+
+
+ HAVE_LIBXML2,
+ LIBXML2_DIR
+
+
+ If HAVE_LIBXML2 is set to 1, YAZ is compiled
+ with SRU support. In this configuration, set
+ LIBXML2_DIR to the
+ libxml2 source directory
+ and
+ ZLIB_DIR to the zlib directory.
+
+
+
+ Windows versions of libxslt, libxml2, zlib and iconv can be found
+
+ Igor Zlatković' site.
+
+
+
+
+ YAZ is not using zlib but libxml2 is depending on it.
+
+
+
+
+
+
+ HAVE_LIBXSLT,
+ LIBXSLT_DIR
+
+
+ If HAVE_LIBXSLT is set to 1, YAZ is compiled
+ with XSLT support. In this configuration, set
+ LIBXSLT_DIR to the
+ libxslt source directory.
+
+
+
+
+ libxslt depends libxml2.
+
+
+
+
+
+
+
+
+
+ When satisfied with the settings in the makefile, type
+
+ nmake
+
+
+
+
+ If the nmake command 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
+ vcvars32.bat. You need to run it from within
+ the command prompt or set the environment variables "globally";
+ otherwise it doesn't work.
+
+
+
+ If you wish to recompile &yaz; - for example if you modify
+ settings in the makefile you can delete
+ object files, etc by running.
+
+ nmake clean
+
+
+
+ The following files are generated upon successful compilation:
+
+
+ bin/yaz3.dll
+
+ &yaz; release mode multi-threaded Dynamic Link Library.
+
+
+ lib/yaz3.lib
+
+ Import library for yaz3.dll.
+
+
+ bin/yaz3d.dll
+
+ &yaz; debug mode multi-threaded Dynamic Link Library.
+
+
+ lib/yaz3d.lib
+
+ Import library for yaz3d.dll.
+
+
+ bin/yaz-client.exe
+
+ &yaz; Z39.50 client application. It's a WIN32 console application.
+ See chapter YAZ client for more
+ information.
+
+
+ bin/yaz-ztest.exe
+
+ Z39.50 multi-threaded test/example server. It's a WIN32
+ console application.
+
+
+ bin/zoomsh.exe
+
+ Simple console application implemented on top of the
+ ZOOM functions.
+ The application is a command line shell that allows you to enter
+ simple commands to perform ZOOM operations.
+
+
+ bin/zoomtst1.exe,
+ bin/zoomtst2.exe, ..
+
+ Several small applications that demonstrates the ZOOM API.
+
+
+
+
+
+
+
+
+ How to make apps using YAZ on WIN32
+
+ This section will go though the process of linking your WIN32
+ applications with &yaz;.
+
+
+ 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.
+
+
+ When setting up a project or Makefile you have to set the following:
+
+ include path
+ Set it to the include directory of &yaz;.
+
+ import library yaz3.lib
+
+ You must link with this library. It's located in the
+ sub directory lib of &yaz;.
+ If you want to link with the debug version of &yaz;, you must
+ link against yaz3d.lib instead.
+
+ dynamic link library yaz3.dll
+
+ This DLL must be in your execution path when you invoke
+ your application. Specifically, you should distribute this
+ DLL with your application.
+
+
+
+
+
+
+
+
+