doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.18 2006-04-27 13:04:39 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>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-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><literal>src/libyazpp.la</literal></term>
  74       <listitem><para>
  75         The YAZ++ library.
  76         This library gets installed in your libraries directory
  77         (<parameter>prefix</parameter><literal>/lib</literal>).
  78        </para></listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><literal>src/libzoompp.la</literal></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><literal>/lib</literal>).
  87        </para></listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term><literal>include/yazpp/*.h</literal></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><literal>/include/yazpp</literal>).
  96        </para></listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><literal>yazpp-config</literal></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><literal>/bin</literal>).
 108        </para></listitem>
 109      </varlistentry>
 110
 111      <varlistentry>
 112       <term><literal>zoom/zclient</literal></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><literal>src/yaz-my-client</literal></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><literal>src/yaz-my-server</literal></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>Building 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 6 and .NET 2003 has been tested. We expect that YAZ++ compiles
 143     with version 5 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><literal>YAZ_DIR</literal></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        </para></listitem></varlistentry>
 202
 203      <varlistentry><term><filename>lib/yazpp.lib</filename></term>
 204       <listitem><para>
 205         Import library for <filename>yazpp.dll</filename>.
 206        </para></listitem></varlistentry>
 207
 208      <varlistentry><term><filename>bin/zclient.exe</filename></term>
 209       <listitem><para>
 210         ZOOM C++ demo client. A simple WIN32 console application.
 211        </para></listitem></varlistentry>
 212
 213     </variablelist>
 214
 215    </para>
 216
 217   </section>
 218  </chapter>
 219  <!-- Keep this comment at the end of the file
 220  Local variables:
 221  mode: sgml
 222  sgml-omittag:t
 223  sgml-shorttag:t
 224  sgml-minimize-attributes:nil
 225  sgml-always-quote-attributes:t
 226  sgml-indent-step:1
 227  sgml-indent-data:t
 228  sgml-parent-document: "yazpp.xml"
 229  sgml-local-catalogs: nil
 230  sgml-namecase-general:t
 231  End:
 232  -->