doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.13 2004-09-09 09:43:20 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-yaz-config </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/libyazcpp.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/libzoomcpp.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/yaz++/*.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/yaz++</literal>).
  96        </para></listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><literal>yaz++-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="http://msdn.microsoft.com/vstudio/">
 142      Microsoft Visual Studio</ulink>.
 143     Version 6 and .NET has been tested. We expect that YAZ++ compiles
 144     with version 5 as well.
 145    </para>
 146     <para>
 147     Start a command prompt and switch the sub directory
 148     <filename>WIN</filename> where the file <filename>makefile</filename>
 149     is located. Customize the installation by editing the
 150     <filename>makefile</filename> file (for example by using notepad).
 151
 152     The following summarizes the most important settings in that file:
 153
 154     <variablelist>
 155      <varlistentry><term><literal>DEBUG</literal></term>
 156       <listitem><para>
 157         If set to 1, the software is
 158         compiled with debugging libraries (code generation is
 159         multi-threaded debug DLL).
 160         If set to 0, the software is compiled with release libraries
 161         (code generation is multi-threaded DLL).
 162        </para></listitem>
 163      </varlistentry>
 164      <varlistentry><term><literal>YAZ_DIR</literal></term>
 165       <listitem><para>
 166         Specifies the directory of the YAZ source.
 167        </para></listitem>
 168      </varlistentry>
 169     </variablelist>
 170    </para>
 171    <para>
 172     When satisfied with the settings in the makefile, type
 173     <screen>
 174      nmake
 175     </screen>
 176    </para>
 177    <tip>
 178     <para>
 179      If the <filename>nmake</filename> command is not found on your system
 180      you probably haven't defined the environment variables required to
 181      use that tool. To fix that, find and run the batch file
 182      <filename>vcvars32.bat</filename>. You need to run it from within
 183      the command prompt or set the environment variables "globally";
 184      otherwise it doesn't work.
 185     </para>
 186    </tip>
 187    <para>
 188     If you wish to recompile YAZ++ - for example if you modify
 189     settings in the <filename>makefile</filename> you can delete
 190     object files, etc by running.
 191     <screen>
 192      nmake clean
 193     </screen>
 194    </para>
 195    <para>
 196     The following files are generated upon successful compilation:
 197
 198     <variablelist>
 199      <varlistentry><term><filename>bin/yazpp.dll</filename></term>
 200       <listitem><para>
 201         YAZ++ DLL . Includes ZOOM C++ as well.
 202        </para></listitem></varlistentry>
 203
 204      <varlistentry><term><filename>lib/yazpp.lib</filename></term>
 205       <listitem><para>
 206         Import library for <filename>yazpp.dll</filename>.
 207        </para></listitem></varlistentry>
 208
 209      <varlistentry><term><filename>bin/zclient.exe</filename></term>
 210       <listitem><para>
 211         ZOOM C++ demo client. A simple WIN32 console application.
 212        </para></listitem></varlistentry>
 213
 214     </variablelist>
 215
 216    </para>
 217
 218   </section>
 219  </chapter>
 220  <!-- Keep this comment at the end of the file
 221  Local variables:
 222  mode: sgml
 223  sgml-omittag:t
 224  sgml-shorttag:t
 225  sgml-minimize-attributes:nil
 226  sgml-always-quote-attributes:t
 227  sgml-indent-step:1
 228  sgml-indent-data:t
 229  sgml-parent-document: "yaz++.xml"
 230  sgml-local-catalogs: nil
 231  sgml-namecase-general:t
 232  End:
 233  -->