X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Finstallation.xml;h=a01b0188005b525d899db1a86504f713ed33e12d;hp=f94122a3744f2ca80c96ff8eb112424335d3549d;hb=cdd67ab5b29250ce4c16dcaaecb62654346502c1;hpb=7248b20b9e675788555c25d58d807bd8313b8e6d diff --git a/doc/installation.xml b/doc/installation.xml index f94122a..a01b018 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,331 +1,812 @@ - - Compilation and Installation - - Introduction - - 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 - OpenBSD/FreeBSD - 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, the GNU tools - Autoconf, - Automake and - Libtool - is used to generate Makefiles and configure &yaz; for the system. - You do not these tools unless you're using the - CVS version of &yaz;. - Generally it should be sufficient to run configure without options, - like this: - - - - ./configure - - +Compilation and Installation + + Introduction - 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: + The latest version of the software will generally be found at: - - - 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-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 - commonly used in Linux/BSD distributions. - - - --enable-threads - &yaz; will be built using POSIX threads. - Specifically, _REENTRANT will be defined during - compilation. - - - - + - When configured, build the software by typing: - - make - - + 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 following files are generated by the make process: - - lib/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. - - - lib/libyazthread.la - - When threading is supported/enabled by configure this GNU libtool - library is created. It includes functions that allows &yaz; - to use threads. - - - ztest/yaz-ztest - Test Z39.50 server. - - - client/yaz-client - Z39.50 client for testing the protocol. - See chapter - YAZ client for more information. - - - yaz-config - A Bourne-shell script, generate by configure, that - specifies how external applications should compile - and link with - &yaz;. - - - yaz-comp - The ASN.1 compiler for &yaz;. Requires the - Tcl Shell, tclsh, in - PATH to operate. - - 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 perform to perform ZOOM operations. - - - zoom/zoomtst1, - zoom/zoomtst2, .. - - Several small applications that demonstrates the use of ZOOM. - - - - - - If you wish to install &yaz; in system directories such as - /usr/local/bin, - /usr/local/lib you can type: + The software is regularly tested on + Debian GNU/Linux, + CentOS, + Ubuntu Linux, + FreeBSD (i386), + MAC OSX, + Solaris, + Windows 7, Windows Xp. - - - 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/. + 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 wish to perform an un-installation of &yaz; use: + 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. - - - 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. + 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. - + - WIN32 - + UNIX + - &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. + We provide + Debian GNU/Linux (i386 and amd64), + Ubuntu (i386 and amd64) + and + CentOS (amd64 only) packages for &yaz;. + You should be able to create packages for other CPUs by building + them from the source package. + - 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 summarises 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). - - - 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;. - - - + YAZ is also part of several packages repositories. Some of them are - - When satisfied with the settings in the makefile type + + + + + Solaris CSW: + + + + + Solaris: + + + + + FreeBSD: + + + + + Debian: + + + + + Ubuntu: + + + + + NetBSD: + + + + + + + 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. + + + + YAZ 3.0.16 and later includes a wrapper for the + ICU + (International Components for Unicode). + In order to use this, the developer version of the ICU library + must be available. + + + + 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 + git version of &yaz;. + + + + The CQL parser for &yaz; is built using + GNU Bison. + This tool is only needed if you're using the git 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 git + 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: + + - nmake + ./configure - If command nmake 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. + + + 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: + + - nmake clean + 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 XSLT and XML 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-xml2[=prefix] + + Compile &yaz; with + libxml2 in directory + prefix. + Use this option if you want &yaz; to use XML and support SRU. + By default, configure will + search for libxml2 on the system. Use this option if it + libxml2 is not found automatically. Alternatively, + --without-xml2, can be used to force &yaz; + not to use libxml2. + + + Note that option --with-xslt + also enables libxml2. + + + + + + --with-gnutls[=prefix] + + &yaz; will be linked with the GNU TLS libraries and + an SSL COMSTACK will be provided. By default configure enables + SSL support for YAZ if the GNU TLS development libraries are found + on the system. + + + + + --with-openssl[=prefix] + + &yaz; will be linked with the OpenSSL libraries and + an SSL COMSTACK will be provided. If OpenSSL is enabled, GNU TLS + is automatically disabled. + + + + + --with-icu[=prefix] + + &yaz; will be linked the + ICU library in the prefix if given. + If prefix is not given, the libraries exposed by the script + icu-config will be used if found. + + + + + + + + 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 POSIX + threads are available on the platform. + + + + src/libyaz_icu.la + + Functions that wrap the ICU library. + + + + ztest/yaz-ztest + Test Z39.50 server. + + + + client/yaz-client + Z39.50 client for testing the protocol. + See chapter + YAZ client 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. + + + + util/yaz-icu + This program exposes the ICU wrapper library if that + is enabled for YAZ. Only if ICU is available this program is + useful. + + + + 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 archive(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. - - The following files are generated upon successful compilation: - - - bin/yaz.dll - - &yaz; multi-threaded Dynamic Link Library. - - - lib/yaz.lib - - Import library for yaz.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 perform to perform ZOOM operations. - - - bin/zoomtst1.exe, - bin/zoomtst2.exe, .. - - Several small applications that demonstrates the use of ZOOM. - - - - - + + + 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 git 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. + + + + + + + HAVE_ICU, + ICU_DIR + + + If HAVE_ICU is set to 1, YAZ is compiled + with ICU support. + In this configuration, set + ICU_DIR to the + ICU source directory. + + + + + + + + + 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/yaz4.dll / + bin/yaz4d.dll + + &yaz; Release/Debug DLL. + + + lib/yaz4.lib / + lib/yaz4d.lib + + Import library for yaz4.dll / + yaz4d.dll. + + + bin/yaz_cond4.dll / + bin/yaz_cond4d.dll + + Release/Debug DLL for condition variable utilities (condvar.c). + + + lib/yaz_cond4.lib / + lib/yaz_cond4d.lib + + Import library for yaz_cond4.dll / + yaz_cond4d.dll. + + + bin/yaz_icu4.dll / + bin/yaz_icu4d.dll + + Release/Debug DLL for the ICU wrapper utility. + Only build if HAVE_ICU is 1. + + + lib/yaz_icu4.lib / + lib/yaz_icu4d.lib + + Import library for yaz_icu4.dll / + yaz_icu4d.dll. + + + bin/yaz-ztest.exe + + Z39.50 multi-threaded test/example server. It's a WIN32 + console application. + + + bin/yaz-client.exe + + &yaz; Z39.50 client application. It's a WIN32 console application. + See chapter YAZ client for more + information. + + + bin/yaz-icu.exe + This program exposes the ICU wrapper library if that + is enabled for YAZ. Only if ICU is available this program is + build. + + + 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 yaz4.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 yaz4d.lib instead. + + dynamic link library yaz4.dll + + This DLL must be in your execution path when you invoke + your application. Specifically, you should distribute this + DLL with your application. + + + + - + - +