doc/installation.xml

   1 <!-- $Header: /home/cvsroot/yaz/doc/installation.xml,v 1.1 2001-01-04 13:36:24 adam Exp $ -->
   2 <chapter><title>Compilation and Installation</title>
   3
   4 <para>
   5 The latest version of the software will generally be found at
   6 </para>
   7 <para>
   8 <ulink url="http://ftp.indexdata.dk/pub/yaz/">
   9 http://ftp.indexdata.dk/pub/yaz/</ulink>
  10 </para>
  11 <para>
  12 We have tried our best to keep the software portable, and on many
  13 platforms, you should be able to compile everything with little or no changes.
  14 So far, the software has been ported
  15 to the following platforms with little or no difficulties.
  16
  17 <itemizedlist>
  18 <listitem><para>Unix systems</para>
  19 <itemizedlist>
  20 <listitem><para>HP/UX</para></listitem>
  21 <listitem><para>SunOS/Solaris</para></listitem>
  22 <listitem><para>DEC Unix</para></listitem>
  23 <listitem><para>Linux</para></listitem>
  24 <listitem><para>IBM AIX</para></listitem>
  25 <listitem><para>Data General DG/UX (with some CFLAGS tinkering)
  26 </para></listitem>
  27 <listitem><para>SGI/IRIX</para></listitem>
  28 <listitem><para>DDE Supermax</para></listitem>
  29 </itemizedlist></listitem>
  30 <listitem><para>Non-unix systems</para>
  31 <itemizedlist>
  32 <listitem><para>Apple Macintosh (using the Codewarrior programming
  33 environment and the GUSI socket libraries)</para></listitem>
  34 <listitem><para>MS Windows 95/98/NT/W2K (Win32)</para></listitem>
  35 <listitem><para>IBM AS/400</para></listitem>
  36 </itemizedlist></listitem>
  37 </itemizedlist>
  38
  39 </para>
  40 <para>
  41 If you move the software to other platforms, we'd be grateful if you'd
  42 let us know about it. If you run into difficulties, we will try to help if we
  43 can, and if you solve the problems, we would be happy to
  44 include your fixes in the next release. So far, we have mostly avoided
  45 &num;ifdefs for individual platforms, and we'd like to keep it that
  46 way as far as it makes sense.
  47 </para>
  48
  49 <para>
  50 We maintain a mailing-list for the purpose of announcing new releases and
  51 bug-fixes, as well as general discussion. Subscribe by sending mail to
  52 <ulink url="mailto:yaz-request@indexdata.dk">yaz-request@indexdata.dk</ulink>.
  53 General questions and problems can be directed at
  54 <ulink url="mailto:yaz-help@indexdata.dk">yaz-help@indexdata.dk</ulink>, or
  55 the address given at the top of this document.
  56 </para>
  57
  58 <sect1><title>UNIX</title>
  59
  60 <para>
  61 Note that if your system doesn't have a native ANSI C compiler, you may
  62 have to acquire one separately. We recommend gcc.
  63 </para>
  64 <para>
  65 For UNIX we use GNU configure to create Makefiles for &yaz;.
  66 Generally it should be sufficient to run configure without options:
  67 </para>
  68
  69 <screen>
  70   ./configure
  71 </screen>
  72
  73 <para>
  74 The configure script attempts to use use the C compiler specified by
  75 the <literal>CC</literal> environment variable. If not set, GNU C will be
  76 used if it is available. The <literal>CFLAGS</literal> environment variable
  77 holds options to be passed to the C compiler. If you're using
  78 Bourne-compatible shell you may pass something like this to use a
  79 particular C compiler with optimization enabled:
  80 </para>
  81
  82 <screen>
  83   CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
  84 </screen>
  85
  86 <para>
  87 To customize &yaz; the configure script also accepts a set of options.
  88 The most important are:
  89
  90 <variablelist>
  91 <varlistentry><term><literal>--prefix </literal>path</term>
  92 <listitem><para>Specifies installation prefix. This is
  93 only needed if you run <literal>make install</literal> later to perform a
  94 "system" installation. The prefix is <literal>/usr/local</literal> if not
  95 specified.
  96 </para></listitem>
  97 </varlistentry>
  98 <varlistentry>
  99 <term><literal>--enable-comp </literal></term>
 100 <listitem><para> &yaz; will be built using the ASN.1 compiler for &yaz;
 101 (default). If you wish to use the old decoders (in sub directory asn)
 102 use <literal>--disable-comp</literal> instead.
 103 </para></listitem>
 104 </varlistentry>
 105 <varlistentry><term><literal>--enable-threads</literal></term>
 106 <listitem><para>&yaz; will be built using POSIX threads.
 107 Specifically, <constant>_REENTRANT</constant> will be defined during
 108 compilation.
 109 </para></listitem>
 110 </varlistentry>
 111 </variablelist>
 112
 113 </para>
 114 <para>
 115 When configured, build the software by typing:
 116 <screen>
 117   make
 118 </screen>
 119
 120 </para>
 121
 122 <para>
 123 The following files are generated by the make process:
 124 <variablelist>
 125 <varlistentry><term><filename>lib/libyaz.a</filename></term>
 126 <listitem><para>
 127 The &yaz; programmers' library.
 128 </para></listitem></varlistentry>
 129
 130 <varlistentry><term><filename>ztest/yaz-ztest</filename></term>
 131 <listitem><para>A test Z39.50 server.
 132 </para></listitem></varlistentry>
 133
 134 <varlistentry><term><filename>client/yaz-client</filename></term>
 135 <listitem><para>A command mode Z39.50 client.
 136 </para></listitem></varlistentry>
 137
 138 <varlistentry><term><filename>yaz-config</filename></term>
 139 <listitem><para>A Bourne-shell script that holds build
 140 settings for &yaz;.
 141 </para></listitem></varlistentry>
 142
 143 <varlistentry><term><filename>yaz-comp</filename></term>
 144 <listitem><para>The ASN.1 compiler for &yaz;. Requires the
 145 Tcl Shell, <application>tclsh</application>, in current path to work.
 146 </para></listitem></varlistentry>
 147 </variablelist>
 148
 149 </para>
 150
 151 <para>
 152 If you wish to install &yaz; in system directories such as
 153 <filename>/usr/local/bin</filename>,
 154 <filename>/usr/local/lib</filename> you can type:
 155 </para>
 156
 157 <screen>
 158   make install
 159 </screen>
 160
 161 <para>
 162 You probably need to have root access in order to perform this.
 163 You must specify the <literal>--prefix</literal> option for configure if
 164 you wish to install &yaz; in other directories than the default
 165 <filename>/usr/local/</filename>.
 166 </para>
 167
 168 <para>
 169 If you wish to perform an un-installation of &yaz; use:
 170 </para>
 171
 172 <screen>
 173   make uninstall
 174 </screen>
 175
 176 <para>
 177 This will only work if you haven't reconfigured &yaz; (and therefore
 178 changed installation prefix). Note that uninstall will not
 179 remove directories created by make install, e.g.
 180 <filename>/usr/local/include/yaz</filename>.
 181 </para>
 182
 183 </sect1>
 184 <sect1><title>WIN32</title>
 185
 186 <para>
 187 &yaz; is shipped with "makefiles" for the NMAKE tool that comes
 188 with Visual C++.
 189
 190 Start an MS-DOS prompt and switch the sub directory <filename>WIN</filename>
 191 where the file <filename>makefile</filename> is located. Customize the
 192 installation by editing the <filename>makefile</filename> file (for example
 193 by using notepad).
 194
 195 The following summarises the most important settings in that file:
 196
 197 <table frame="top"><title>WIN32 makefile settings</title>
 198 <tgroup cols="2">
 199 <thead>
 200 <row>
 201 <entry>Setting</entry>
 202 <entry>Description</entry>
 203 </row>
 204 </thead>
 205 <tbody>
 206
 207 <row>
 208 <entry><literal>NEW_Z3950</literal></entry>
 209 <entry> If 1, the auto-generated decoder/encoders
 210 for Z39.50 as written by the ASN.1 compiler will be used. If 0, the old
 211 decoders for Z39.50 will be used. Note, when 1, the setting TCL should
 212 point to the Tcl shell on your system.
 213 </entry>
 214 </row>
 215
 216 <row>
 217 <entry><literal>DEBUG</literal></entry>
 218 <entry> If set to 1, the software is
 219 compiled with debugging libraries. If set to 0, the software
 220 is compiled with release (non-debugging) libraries.
 221 </entry>
 222 </row>
 223
 224 <row>
 225 <entry><literal>TCL</literal></entry>
 226 <entry> Specifies the name of the Tcl shell (EXE-file).
 227 You do not need setting this or installing Tcl unless you wish
 228 to change or add ASN.1 for &yaz;.
 229 </entry>
 230 </row>
 231
 232 </tbody>
 233 </tgroup>
 234 </table>
 235
 236 </para>
 237 <para>
 238 When satisfied with the settings in the makefile type
 239 <screen>
 240   nmake
 241 </screen>
 242 </para>
 243 <para>
 244 The following files are generated upon successful compilation:
 245
 246 <variablelist>
 247 <varlistentry><term><filename>bin/yaz.dll</filename></term>
 248 <listitem><para>
 249 the multi-threaded &yaz; DLL.
 250 </para></listitem></varlistentry>
 251
 252 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 253 <listitem><para>
 254 A console Z39.50 client application.
 255 </para></listitem></varlistentry>
 256
 257 <varlistentry><term><filename>bin/yaz-ztest.exe</filename></term>
 258 <listitem><para>
 259 A console Z39.50 multi threaded server.
 260 </para></listitem></varlistentry>
 261
 262 </variablelist>
 263
 264 </para>
 265 </sect1>
 266 </chapter>
 267