X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Finstallation.xml;h=4f89d4db292855b74a4a3de1c803906736afb96a;hb=519fe26fff30687caa26c4a26038d02dcc0429c8;hp=448bed41a71616b8192d1abb6043cfb2ef0bbfdf;hpb=30dc1fd726606bff28c2f3884f3f294c42550008;p=yaz-moved-to-github.git diff --git a/doc/installation.xml b/doc/installation.xml index 448bed4..4f89d4d 100644 --- a/doc/installation.xml +++ b/doc/installation.xml @@ -1,73 +1,87 @@ - + 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. + 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 + BSDs: FreeBSD, OpenBSD, NetBSD, MAC OSX + + 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/2K/XP (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. + - - 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 - - + + 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 + or fill-in the form + + here. + General questions and problems can be directed at + + yaz-help@indexdata.dk + , or the address given at the top of this document. + - - - 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. + 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: + For UNIX, 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;. + Generally it should be sufficient to run configure without options, + like this: @@ -88,7 +102,7 @@ - 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: @@ -100,9 +114,21 @@ --enable-tcpd - The front end server will be built using the TCP - wrapper library. It allows you to disallow/deny clients depending - on IP. + 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 Linux/BSD distributions. + See + + hosts_access + 5 + + and + + tcpd + 8 + . --enable-threads @@ -111,6 +137,26 @@ compilation. + --with-openssl + &yaz; will be linked with the OpenSSL libraries and + an SSL COMSTACK will be provided. Note that SSL support is still + experimental. + + + --enable-shared + The make process will create shared + libraries (also known as shared objects .so). + By default, no shared libraries are created - + equivalent to --disable-shared. + + + --disable-shared + The make process will not create + static libraries (.a). + By default, static libraries are created - + equivalent to --enable-static. + + @@ -119,42 +165,69 @@ make - The following files are generated by the make process: - lib/libyaz.a + 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 - 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. ztest/yaz-ztest - A test Z39.50 server. + Test Z39.50 server. client/yaz-client - A command mode Z39.50 client. + Z39.50 client for testing the protocol. + See chapter + YAZ client for more information. yaz-config - A Bourne-shell script that holds build - settings for &yaz;. + A Bourne-shell script, generated 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 current path to work. + 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 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 such as + If you wish to install &yaz; in system directories /usr/local/bin, - /usr/local/lib you can type: + /usr/local/lib .. etc, you can type: @@ -169,7 +242,7 @@ - If you wish to perform an un-installation of &yaz; use: + If you wish to perform an un-installation of &yaz;, use: @@ -182,56 +255,132 @@ 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 &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. + + + 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: - - WIN32 makefile settings - - - - Setting - Description - - - - - 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;. - - - - - -
- + 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). + + + 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 + When satisfied with the settings in the makefile, type nmake + 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. + + nmake clean + The following files are generated upon successful compilation: @@ -239,22 +388,76 @@ bin/yaz.dll - the multi-threaded &yaz; DLL. + &yaz; multi-threaded Dynamic Link Library. + + + lib/yaz.lib + + Import library for yaz.dll. - bin/yaz-ztest.exe + bin/yaz-client.exe - A console Z39.50 client application. + &yaz; Z39.50 client application. It's a WIN32 console application. + See chapter YAZ client for more + information. bin/yaz-ztest.exe - A console Z39.50 multi threaded server. + 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 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 yaz.lib + + You must link with this library. It's located in the + sub directory lib of &yaz;. + + dynamic link library yaz.dll + + This DLL must be in your execution path when you invoke + your application. Specifically, you should distribute this + DLL with your application. + + + + @@ -268,7 +471,7 @@ 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: -->