doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.1 2004-04-11 11:36:52 adam Exp $ -->
   3   <title>Installation</title>
   4   <para>
   5    You need a C++ compiler to compile and use YAZ++.
   6    The software was implemented using GCC so we know that works
   7    well with YAZ++. From time to time the software has been
   8    compiled on Windows using Visual C++. Other compilers should
   9    work too. Let us know of portability problems, etc. with
  10    your system.
  11   </para>
  12   <para>
  13    YAZ++ is built on top of the
  14    <ulink url="http://indexdata.dk/yaz/">YAZ</ulink>
  15    toolkit.
  16    You need to install that first.
  17    For some platforms there are binary packages for YAZ.
  18   </para>
  19   <section id="unix">
  20    <title>Building on Unix</title>
  21    <para>On UNIX, the software is compiled as follows:
  22     <screen>
  23      $ ./configure
  24      $ make
  25      $ su
  26      # make install
  27     </screen>
  28    </para>
  29    <para>
  30     You can supply options for the <literal>configure</literal> script.
  31     The most useful ones are:
  32     <variablelist>
  33      <varlistentry>
  34       <term><literal>--prefix </literal>directory</term>
  35       <listitem><para>
  36         Specifies installation prefix. By default
  37         <literal>/usr/local</literal> is used.
  38        </para></listitem>
  39      </varlistentry>
  40      <varlistentry>
  41       <term><literal>--with-yazconfig </literal>directory</term>
  42       <listitem><para>
  43         Specifies the location of <filename>yaz-config</filename>.
  44         The <filename>yaz-config</filename> program is generated in
  45         the source directory of YAZ as well as the binaries
  46         directory when YAZ is installed (via make install).
  47         </para>
  48        <para>
  49         If you don't supply this option, <literal>configure</literal> will
  50         look for <filename>yaz-config</filename> in directories of the
  51         <envar>PATH</envar> environment - which is nearly always
  52         what you want.
  53        </para></listitem>
  54      </varlistentry>
  55      <varlistentry>
  56       <term><literal>--with-xslt </literal>directory</term>
  57       <listitem><para>
  58         Specifies prefix for libxslt (and libxml2).
  59         configure must be able to locate <command>xslt-config</command>
  60         in PREFIX/bin. If this option is omitted, configure looks
  61         for <command>xslt-config</command> in the current PATH.
  62        </para></listitem>
  63      </varlistentry>
  64     </variablelist>
  65     For the whole list of <literal>configure</literal> options, refer
  66     to the help:
  67     <literal>./configure --help</literal>.
  68    </para>
  69    <para>
  70     Configure uses GCC's C/C++ compiler if available. To specify another
  71     compiler, set <literal>CXX</literal>. To use other compiler flags,
  72     specify <literal>CXXFLAGS</literal>. To use <literal>CC</literal>
  73     with debugging you could use:
  74     <screen>
  75      CXXFLAGS="-g" CXX=CC ./configure
  76     </screen>
  77    </para>
  78    <para>
  79     This is what you have after successful compilation:
  80     <variablelist>
  81      <varlistentry>
  82       <term><literal>proxy/yaz-proxy</literal></term>
  83       <listitem><para>
  84         The YAZ <link linkend="proxy">Z39.50 Proxy</link>.
  85         This program gets installed in your binaries directory
  86         (<parameter>prefix</parameter><literal>/bin</literal>).
  87        </para></listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term><literal>src/libyazcpp.la</literal></term>
  92       <listitem><para>
  93         The YAZ++ library.
  94         This library gets installed in your libraries directory
  95         (<parameter>prefix</parameter><literal>/lib</literal>).
  96        </para></listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><literal>src/libzoomcpp.la</literal></term>
 101       <listitem><para>
 102         The <link linkend="zoom">ZOOM-C++</link> library.
 103         This library gets installed in your libraries directory
 104         (<parameter>prefix</parameter><literal>/lib</literal>).
 105        </para></listitem>
 106      </varlistentry>
 107
 108      <varlistentry>
 109       <term><literal>proxy/libyazproxy.la</literal></term>
 110       <listitem><para>
 111         The YAZ proxy library. This library gets installed in
 112         your libraries directory
 113         (<parameter>prefix</parameter><literal>/lib</literal>).
 114        </para></listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><literal>include/yaz++/*.h</literal></term>
 119       <listitem><para>
 120         Various C++ header files, which you'll need for YAZ++
 121         development. All these are installed in your header files area
 122         (<parameter>prefix</parameter><literal>/include/yaz++</literal>).
 123        </para></listitem>
 124      </varlistentry>
 125
 126      <varlistentry>
 127       <term><literal>yaz++-config</literal></term>
 128       <listitem><para>
 129         A Bourne shell-script utility that returns the values of the
 130         <envar>CFLAGS</envar> and <envar>LIBS</envar>
 131         environment variables
 132         needed in order to compile your applications with the YAZ++
 133         library.  This script gets installed in your binaries directory
 134         (<parameter>prefix</parameter><literal>/bin</literal>).
 135        </para></listitem>
 136      </varlistentry>
 137
 138      <varlistentry>
 139       <term><literal>zoom/zclient</literal></term>
 140       <listitem><para>
 141         ZOOM C++ demonstration client that uses the ZOOM C++ classes.
 142         This client does not get installed in the system directories.
 143        </para></listitem>
 144      </varlistentry>
 145
 146      <varlistentry>
 147       <term><literal>src/yaz-my-client</literal></term>
 148       <listitem><para>
 149         YAZ C++ demonstration client. This client does not
 150         get installed in the system directories.
 151        </para></listitem>
 152      </varlistentry>
 153
 154      <varlistentry>
 155       <term><literal>src/yaz-my-server</literal></term>
 156       <listitem><para>
 157         YAZ C++ demonstration server. This server does not
 158         get installed in the system directories.
 159        </para></listitem>
 160      </varlistentry>
 161     </variablelist>
 162    </para>
 163   </section>
 164   <section id="windows">
 165    <title>Building on Windows</title>
 166    <para>
 167     YAZ++ is shipped with "makefiles" for the NMAKE tool that comes
 168     with <ulink url="http://msdn.microsoft.com/vstudio/">
 169      Microsoft Visual Studio</ulink>.
 170     Version 6 and .NET has been tested. We expect that YAZ++ compiles
 171     with version 5 as well.
 172    </para>
 173     <para>
 174     Start a command prompt and switch the sub directory
 175     <filename>WIN</filename> where the file <filename>makefile</filename>
 176     is located. Customize the installation by editing the
 177     <filename>makefile</filename> file (for example by using notepad).
 178
 179     The following summarizes the most important settings in that file:
 180
 181     <variablelist>
 182      <varlistentry><term><literal>DEBUG</literal></term>
 183       <listitem><para>
 184         If set to 1, the software is
 185         compiled with debugging libraries (code generation is
 186         multi-threaded debug DLL).
 187         If set to 0, the software is compiled with release libraries
 188         (code generation is multi-threaded DLL).
 189        </para></listitem>
 190      </varlistentry>
 191
 192      <varlistentry>
 193       <term><literal>HAVE_XSLT</literal>,
 194        <literal>LIBXSLT_DIR</literal></term>
 195       <listitem>
 196        <para>
 197         If <literal>HAVE_LIBXSLT</literal> is set to 1, the proxy is compiled
 198         with XSLT and XML support. In this configuration, set
 199         <literal>LIBXSLT_DIR</literal> to the
 200         <ulink url="http://www.xmlsoft.org/">libxslt</ulink> source
 201         directory.
 202        </para>
 203
 204        <note>
 205         <para>
 206          If you enable libXSLT you have to enable libxml2 and its
 207          sub components zlib and iconv as well.
 208         </para>
 209        </note>
 210
 211        <para>
 212         Windows versions of libxslt, libxml2, zlib and iconv can be found
 213         <ulink url="http://www.zlatkovic.com/libxml.en.html">
 214          here</ulink>.
 215        </para>
 216       </listitem>
 217      </varlistentry>
 218
 219      <varlistentry>
 220       <term><literal>HAVE_ICONV</literal>,
 221        <literal>ICONV_DIR</literal></term>
 222       <listitem><para>
 223         If <literal>HAVE_ICONV</literal> is set to 1, the proxy is
 224         compiled with iconv support. In this configuration, set
 225         <literal>ICONV_DIR</literal> to the iconv source directory.
 226        </para></listitem>
 227      </varlistentry>
 228
 229      <varlistentry>
 230       <term><literal>HAVE_LIBXML2</literal>,
 231        <literal>LIBXML2_DIR</literal></term>
 232       <listitem>
 233        <para>
 234         If <literal>HAVE_LIBXML2</literal> is set to 1, the proxy is compiled
 235         with XML support. In this configuration, set
 236         <literal>LIBXML2_DIR</literal> to the
 237         <ulink url="http://www.xmlsoft.org/">libxml2</ulink> source directory
 238         and
 239         <literal>ZLIB_DIR</literal> to the zlib directory.
 240        </para>
 241
 242        <note>
 243         <para>
 244          YAZ++ is not using ZLIB. But libxml2 is.
 245         </para>
 246        </note>
 247       </listitem>
 248      </varlistentry>
 249
 250     </variablelist>
 251    </para>
 252    <para>
 253     When satisfied with the settings in the makefile, type
 254     <screen>
 255      nmake
 256     </screen>
 257    </para>
 258    <tip>
 259     <para>
 260      If the <filename>nmake</filename> command is not found on your system
 261      you probably haven't defined the environment variables required to
 262      use that tool. To fix that, find and run the batch file
 263      <filename>vcvars32.bat</filename>. You need to run it from within
 264      the command prompt or set the environment variables "globally";
 265      otherwise it doesn't work.
 266     </para>
 267    </tip>
 268    <para>
 269     If you wish to recompile YAZ++ - for example if you modify
 270     settings in the <filename>makefile</filename> you can delete
 271     object files, etc by running.
 272     <screen>
 273      nmake clean
 274     </screen>
 275    </para>
 276    <para>
 277     The following files are generated upon successful compilation:
 278
 279     <variablelist>
 280      <varlistentry><term><filename>bin/yazpp.dll</filename></term>
 281       <listitem><para>
 282         YAZ++ DLL . Includes ZOOM C++ as well.
 283        </para></listitem></varlistentry>
 284
 285      <varlistentry><term><filename>lib/yaz.lib</filename></term>
 286       <listitem><para>
 287         Import library for <filename>yazpp.dll</filename>.
 288        </para></listitem></varlistentry>
 289
 290      <varlistentry><term><filename>bin/yazproxy.dll</filename></term>
 291       <listitem><para>
 292         YAZ proxy DLL.
 293        </para></listitem></varlistentry>
 294
 295      <varlistentry><term><filename>lib/yazproxy.lib</filename></term>
 296       <listitem><para>
 297         Import library for <filename>yazproxy.dll</filename>.
 298        </para></listitem></varlistentry>
 299
 300      <varlistentry><term><filename>bin/yaz-proxy.exe</filename></term>
 301       <listitem><para>
 302         YAZ proxy. It's a WIN32 console application.
 303         See <xref linkend="proxy"/> for more information.
 304        </para></listitem></varlistentry>
 305
 306      <varlistentry><term><filename>bin/zclient.exe</filename></term>
 307       <listitem><para>
 308         ZOOM C++ demo client. A simple WIN32 console application.
 309        </para></listitem></varlistentry>
 310
 311     </variablelist>
 312
 313    </para>
 314
 315   </section>
 316  </chapter>
 317  <!-- Keep this comment at the end of the file
 318  Local variables:
 319  mode: sgml
 320  sgml-omittag:t
 321  sgml-shorttag:t
 322  sgml-minimize-attributes:nil
 323  sgml-always-quote-attributes:t
 324  sgml-indent-step:1
 325  sgml-indent-data:t
 326  sgml-parent-document: "yaz++.xml"
 327  sgml-local-catalogs: nil
 328  sgml-namecase-general:t
 329  End:
 330  -->