doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.19 2006-04-30 12:53:14 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 <ulink url="&url.gcc;">GCC</ulink>
   7    so we know that works well with YAZ++. From time to time the
   8    software is compiled on Windows using Visual C++.
   9    Other compilers should work too. Let us know of portability
  10    problems, etc. with your system.
  11   </para>
  12   <para>
  13    YAZ++ is built on top of the
  14    <ulink url="&url.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>Installation on Unix (from source)</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         <filename>/usr/local</filename> is used.
  38        </para></listitem>
  39      </varlistentry>
  40      <varlistentry>
  41       <term><literal>--with-yaz </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     </variablelist>
  56     For the whole list of <literal>configure</literal> options, refer
  57     to the help:
  58     <literal>./configure --help</literal>.
  59    </para>
  60    <para>
  61     Configure uses GCC's C/C++ compiler if available. To specify another
  62     compiler, set <literal>CXX</literal>. To use other compiler flags,
  63     specify <literal>CXXFLAGS</literal>. To use <literal>CC</literal>
  64     with debugging you could use:
  65     <screen>
  66      CXXFLAGS="-g" CXX=CC ./configure
  67     </screen>
  68    </para>
  69    <para>
  70     This is what you have after successful compilation:
  71     <variablelist>
  72      <varlistentry>
  73       <term><filename>src/libyazpp.la</filename></term>
  74       <listitem><para>
  75         The YAZ++ library.
  76         This library gets installed in your libraries directory
  77         (<parameter>prefix</parameter><filename>/lib</filename>).
  78        </para></listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><filename>src/libzoompp.la</filename></term>
  83       <listitem><para>
  84         The <link linkend="zoom">ZOOM-C++</link> library.
  85         This library gets installed in your libraries directory
  86         (<parameter>prefix</parameter><filename>/lib</filename>).
  87        </para></listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term><filename>include/yazpp/*.h</filename></term>
  92       <listitem><para>
  93         Various C++ header files, which you'll need for YAZ++
  94         development. All these are installed in your header files area
  95         (<parameter>prefix</parameter><filename>/include/yazpp</filename>).
  96        </para></listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><filename>yazpp-config</filename></term>
 101       <listitem><para>
 102         A Bourne shell-script utility that returns the values of the
 103         <envar>CFLAGS</envar> and <envar>LIBS</envar>
 104         environment variables
 105         needed in order to compile your applications with the YAZ++
 106         library.  This script gets installed in your binaries directory
 107         (<parameter>prefix</parameter><filename>/bin</filename>).
 108        </para></listitem>
 109      </varlistentry>
 110
 111      <varlistentry>
 112       <term><filename>zoom/zclient</filename></term>
 113       <listitem><para>
 114         ZOOM C++ demonstration client that uses the ZOOM C++ classes.
 115         This client does not get installed in the system directories.
 116        </para></listitem>
 117      </varlistentry>
 118
 119      <varlistentry>
 120       <term><filename>src/yaz-my-client</filename></term>
 121       <listitem><para>
 122         YAZ C++ demonstration client. This client does not
 123         get installed in the system directories.
 124        </para></listitem>
 125      </varlistentry>
 126
 127      <varlistentry>
 128       <term><filename>src/yaz-my-server</filename></term>
 129       <listitem><para>
 130         YAZ C++ demonstration server. This server does not
 131         get installed in the system directories.
 132        </para></listitem>
 133      </varlistentry>
 134     </variablelist>
 135    </para>
 136   </section>
 137   <section id="windows">
 138    <title>Installation on Windows</title>
 139    <para>
 140     YAZ++ is shipped with "makefiles" for the NMAKE tool that comes
 141     with <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
 142     Version 2003 (7) and 2005 (8) has been tested.
 143     We expect that YAZ++ compiles with versions 5 and 6 as well.
 144    </para>
 145    <para>
 146     Start a command prompt and switch the sub directory
 147     <filename>WIN</filename> where the file <filename>makefile</filename>
 148     is located. Customize the installation by editing the
 149     <filename>makefile</filename> file (for example by using notepad).
 150
 151     The following summarizes the most important settings in that file:
 152
 153     <variablelist>
 154      <varlistentry><term><literal>DEBUG</literal></term>
 155       <listitem><para>
 156         If set to 1, the software is
 157         compiled with debugging libraries (code generation is
 158         multi-threaded debug DLL).
 159         If set to 0, the software is compiled with release libraries
 160         (code generation is multi-threaded DLL).
 161        </para></listitem>
 162      </varlistentry>
 163      <varlistentry><term><filename>YAZ_DIR</filename></term>
 164       <listitem><para>
 165         Specifies the directory of the YAZ source.
 166        </para></listitem>
 167      </varlistentry>
 168     </variablelist>
 169    </para>
 170    <para>
 171     When satisfied with the settings in the makefile, type
 172     <screen>
 173      nmake
 174     </screen>
 175    </para>
 176    <tip>
 177     <para>
 178      If the <filename>nmake</filename> command is not found on your system
 179      you probably haven't defined the environment variables required to
 180      use that tool. To fix that, find and run the batch file
 181      <filename>vcvars32.bat</filename>. You need to run it from within
 182      the command prompt or set the environment variables "globally";
 183      otherwise it doesn't work.
 184     </para>
 185    </tip>
 186    <para>
 187     If you wish to recompile YAZ++ - for example if you modify
 188     settings in the <filename>makefile</filename> you can delete
 189     object files, etc by running.
 190     <screen>
 191      nmake clean
 192     </screen>
 193    </para>
 194    <para>
 195     The following files are generated upon successful compilation:
 196
 197     <variablelist>
 198      <varlistentry><term><filename>bin/yazpp.dll</filename></term>
 199       <listitem><para>
 200         YAZ++ DLL . Includes ZOOM C++ as well.
 201         For the debug version <filename>lib/yazppd.dll</filename>
 202         is created instead.
 203        </para></listitem></varlistentry>
 204
 205      <varlistentry><term><filename>lib/yazpp.lib</filename></term>
 206       <listitem><para>
 207         Import library for <filename>yazpp.dll</filename>.
 208         For the debug version <filename>lib/yazppd.lib</filename>
 209         is created instead.
 210        </para></listitem></varlistentry>
 211
 212      <varlistentry><term><filename>bin/yaz-my-client.exe</filename></term>
 213       <listitem><para>
 214         Z39.50 client demonstrating the YAZ++ API.
 215        </para></listitem></varlistentry>
 216
 217      <varlistentry><term><filename>bin/yaz-my-server.exe</filename></term>
 218       <listitem><para>
 219         Z39.50 server demonstrating the YAZ++ API.
 220        </para></listitem></varlistentry>
 221
 222      <varlistentry><term><filename>bin/zclient.exe</filename></term>
 223       <listitem><para>
 224         ZOOM C++ demo client. A simple WIN32 console application.
 225        </para></listitem></varlistentry>
 226
 227     </variablelist>
 228
 229    </para>
 230
 231   </section>
 232  </chapter>
 233  <!-- Keep this comment at the end of the file
 234  Local variables:
 235  mode: sgml
 236  sgml-omittag:t
 237  sgml-shorttag:t
 238  sgml-minimize-attributes:nil
 239  sgml-always-quote-attributes:t
 240  sgml-indent-step:1
 241  sgml-indent-data:t
 242  sgml-parent-document: "yazpp.xml"
 243  sgml-local-catalogs: nil
 244  sgml-namecase-general:t
 245  End:
 246  -->