doc/installation.xml

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