doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.11 2004-04-11 12:13:32 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     </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     </variablelist>
 165    </para>
 166    <para>
 167     When satisfied with the settings in the makefile, type
 168     <screen>
 169      nmake
 170     </screen>
 171    </para>
 172    <tip>
 173     <para>
 174      If the <filename>nmake</filename> command is not found on your system
 175      you probably haven't defined the environment variables required to
 176      use that tool. To fix that, find and run the batch file
 177      <filename>vcvars32.bat</filename>. You need to run it from within
 178      the command prompt or set the environment variables "globally";
 179      otherwise it doesn't work.
 180     </para>
 181    </tip>
 182    <para>
 183     If you wish to recompile YAZ++ - for example if you modify
 184     settings in the <filename>makefile</filename> you can delete
 185     object files, etc by running.
 186     <screen>
 187      nmake clean
 188     </screen>
 189    </para>
 190    <para>
 191     The following files are generated upon successful compilation:
 192
 193     <variablelist>
 194      <varlistentry><term><filename>bin/yazpp.dll</filename></term>
 195       <listitem><para>
 196         YAZ++ DLL . Includes ZOOM C++ as well.
 197        </para></listitem></varlistentry>
 198
 199      <varlistentry><term><filename>lib/yazpp.lib</filename></term>
 200       <listitem><para>
 201         Import library for <filename>yazpp.dll</filename>.
 202        </para></listitem></varlistentry>
 203
 204      <varlistentry><term><filename>bin/zclient.exe</filename></term>
 205       <listitem><para>
 206         ZOOM C++ demo client. A simple WIN32 console application.
 207        </para></listitem></varlistentry>
 208
 209     </variablelist>
 210
 211    </para>
 212
 213   </section>
 214  </chapter>
 215  <!-- Keep this comment at the end of the file
 216  Local variables:
 217  mode: sgml
 218  sgml-omittag:t
 219  sgml-shorttag:t
 220  sgml-minimize-attributes:nil
 221  sgml-always-quote-attributes:t
 222  sgml-indent-step:1
 223  sgml-indent-data:t
 224  sgml-parent-document: "yaz++.xml"
 225  sgml-local-catalogs: nil
 226  sgml-namecase-general:t
 227  End:
 228  -->