doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.5 2004-04-22 07:52:51 adam Exp $ -->
   3   <title>Installation</title>
   4   <para>
   5    You need a C++ compiler to compile and use YAZ proxy.
   6    The software was implemented using GCC so we know that works
   7    well with YAZ proxy. 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 proxy is built on top of the
  14    <ulink url="http://indexdata.dk/yaz/">YAZ</ulink> and
  15    <ulink url="http://indexdata.dk/yazplusplus/">YAZ++</ulink>
  16    toolkits.
  17    You need to install these first.
  18    For some platforms there are binary packages for YAZ/YAZ++.
  19   </para>
  20   <para>
  21    We also highly recommend that
  22    <ulink url="http://xmlsoft.org/">libxml2</ulink> and
  23    <ulink url="http://xmlsoft.org/XSLT/">libXSLT</ulink> are installed.
  24    YAZ must be configured with libxml2 support.
  25    If not, SRW/SRU is not supported.
  26    The YAZ Proxy uses libXSLT for record conversions via XSLT.
  27   </para>
  28   <section id="unix">
  29    <title>Building on Unix</title>
  30    <para>On UNIX, the software is compiled as follows:
  31     <screen>
  32      $ ./configure
  33      $ make
  34      $ su
  35      # make install
  36     </screen>
  37    </para>
  38    <para>
  39     You can supply options for the <literal>configure</literal> script.
  40     The most useful ones are:
  41     <variablelist>
  42      <varlistentry>
  43       <term><literal>--prefix </literal>directory</term>
  44       <listitem><para>
  45         Specifies installation prefix. By default
  46         <literal>/usr/local</literal> is used.
  47        </para></listitem>
  48      </varlistentry>
  49      <varlistentry>
  50       <term><literal>--with-yazpp </literal>directory</term>
  51       <listitem><para>
  52         Specifies the location of <filename>yaz++-config</filename>.
  53         The <filename>yaz++-config</filename> program is generated in
  54         the source directory of YAZ++ as well as the binaries
  55         directory when YAZ++ is installed (via make install).
  56         </para>
  57        <para>
  58         If you don't supply this option, <literal>configure</literal> will
  59         look for <filename>yaz++-config</filename> in directories of the
  60         <envar>PATH</envar> environment - which is nearly always
  61         what you want.
  62        </para></listitem>
  63      </varlistentry>
  64      <varlistentry>
  65       <term><literal>--with-xslt </literal>directory</term>
  66       <listitem><para>
  67         Specifies prefix for libXSLT (and libxml2).
  68         configure must be able to locate <command>xslt-config</command>
  69         in PREFIX/bin. If this option is omitted, configure looks
  70         for <command>xslt-config</command> in the current PATH.
  71        </para></listitem>
  72      </varlistentry>
  73     </variablelist>
  74     For the whole list of <literal>configure</literal> options, refer
  75     to the help:
  76     <literal>./configure --help</literal>.
  77    </para>
  78    <para>
  79     Configure uses GCC's C/C++ compiler if available. To specify another
  80     compiler, set <literal>CXX</literal>. To use other compiler flags,
  81     specify <literal>CXXFLAGS</literal>. For example, to use
  82     <literal>CC</literal> with debugging do:
  83     <screen>
  84      CXXFLAGS="-g" CXX=CC ./configure
  85     </screen>
  86    </para>
  87    <para>
  88     This is what you have after successful compilation:
  89     <variablelist>
  90      <varlistentry>
  91       <term><literal>src/yazproxy</literal></term>
  92       <listitem><para>
  93         The YAZ Proxy program.
  94         It gets installed in your binaries directory
  95         (<parameter>prefix</parameter><literal>/bin</literal>).
  96        </para></listitem>
  97      </varlistentry>
  98
  99      <varlistentry>
 100       <term><literal>src/libyazproxy.la</literal></term>
 101       <listitem><para>
 102         The YAZ proxy library. This library gets installed in
 103         the libraries directory
 104         (<parameter>prefix</parameter><literal>/lib</literal>).
 105        </para></listitem>
 106      </varlistentry>
 107
 108      <varlistentry>
 109       <term><literal>include/yazproxy/*.h</literal></term>
 110       <listitem><para>
 111         C++ header files, which you'll need for YAZ proxy
 112         development. All these are installed in the header files area
 113         (<parameter>prefix</parameter><literal>/include/yazproxy</literal>).
 114        </para></listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><literal>etc</literal></term>
 119       <listitem><para>
 120         Various files that may be read by YAZ proxy - including
 121         configuration file, XSLT files, CQL to RPN conversion.
 122         These files are installed in the YAZ proxy's data area
 123         (<parameter>prefix</parameter><literal>/share/yazproxy</literal>).
 124        </para></listitem>
 125      </varlistentry>
 126
 127     </variablelist>
 128    </para>
 129   </section>
 130   <section id="windows">
 131    <title>Building on Windows</title>
 132    <para>
 133     YAZ++ is shipped with "makefiles" for the NMAKE tool that comes
 134     with <ulink url="http://msdn.microsoft.com/vstudio/">
 135      Microsoft Visual Studio</ulink>.
 136     Version 6 and .NET has been tested. We expect that YAZ++ compiles
 137     with version 5 as well.
 138    </para>
 139    <note>
 140     <para>
 141      The YAZ proxy has never been used in production on Windows. Although
 142      it compiles and runs, doesn't mean it scale on that platform.
 143      Furthermore the
 144      YAZ proxy currently doesn't run as a Service - only as a Console
 145      application.
 146     </para>
 147    </note>
 148    <para>
 149     Start a command prompt and switch the sub directory
 150     <filename>WIN</filename> where the file <filename>makefile</filename>
 151     is located. Customize the installation by editing the
 152     <filename>makefile</filename> file (for example by using notepad).
 153
 154     The following summarizes the most important settings in that file:
 155
 156     <variablelist>
 157      <varlistentry><term><literal>DEBUG</literal></term>
 158       <listitem><para>
 159         If set to 1, the software is
 160         compiled with debugging libraries (code generation is
 161         multi-threaded debug DLL).
 162         If set to 0, the software is compiled with release libraries
 163         (code generation is multi-threaded DLL).
 164        </para></listitem>
 165      </varlistentry>
 166
 167      <varlistentry><term><literal>YAZ_DIR</literal></term>
 168       <listitem><para>
 169         This must be set to the home of the YAZ source directory.
 170        </para></listitem>
 171      </varlistentry>
 172
 173      <varlistentry><term><literal>YAZPP_DIR</literal></term>
 174       <listitem><para>
 175         This must be set to the home of the YAZ++ source directory.
 176        </para></listitem>
 177      </varlistentry>
 178
 179      <varlistentry>
 180       <term><literal>HAVE_XSLT</literal>,
 181        <literal>LIBXSLT_DIR</literal></term>
 182       <listitem>
 183        <para>
 184         If <literal>HAVE_LIBXSLT</literal> is set to 1, the proxy is compiled
 185         with XSLT and XML support. In this configuration, set
 186         <literal>LIBXSLT_DIR</literal> to the
 187         <ulink url="http://www.xmlsoft.org/">libXSLT</ulink> source
 188         directory.
 189        </para>
 190
 191        <note>
 192         <para>
 193          If you enable libXSLT you have to enable libxml2 and its
 194          sub components zlib and iconv as well.
 195         </para>
 196        </note>
 197
 198        <para>
 199         Windows versions of libXSLT, libxml2, zlib and iconv can be found
 200         <ulink url="http://www.zlatkovic.com/libxml.en.html">
 201          here</ulink>.
 202        </para>
 203       </listitem>
 204      </varlistentry>
 205
 206      <varlistentry>
 207       <term><literal>HAVE_ICONV</literal>,
 208        <literal>ICONV_DIR</literal></term>
 209       <listitem><para>
 210         If <literal>HAVE_ICONV</literal> is set to 1, the proxy is
 211         compiled with iconv support. In this configuration, set
 212         <literal>ICONV_DIR</literal> to the iconv source directory.
 213        </para></listitem>
 214      </varlistentry>
 215
 216      <varlistentry>
 217       <term><literal>HAVE_LIBXML2</literal>,
 218        <literal>LIBXML2_DIR</literal></term>
 219       <listitem>
 220        <para>
 221         If <literal>HAVE_LIBXML2</literal> is set to 1, the proxy is compiled
 222         with XML support. In this configuration, set
 223         <literal>LIBXML2_DIR</literal> to the
 224         <ulink url="http://www.xmlsoft.org/">libxml2</ulink> source directory
 225         and
 226         <literal>ZLIB_DIR</literal> to the zlib directory.
 227        </para>
 228
 229        <note>
 230         <para>
 231          YAZ++ is not using ZLIB. But libxml2 is.
 232         </para>
 233        </note>
 234       </listitem>
 235      </varlistentry>
 236
 237     </variablelist>
 238    </para>
 239    <para>
 240     When satisfied with the settings in the makefile, type
 241     <screen>
 242      nmake
 243     </screen>
 244    </para>
 245    <tip>
 246     <para>
 247      If the <filename>nmake</filename> command is not found on your system
 248      you probably haven't defined the environment variables required to
 249      use that tool. To fix that, find and run the batch file
 250      <filename>vcvars32.bat</filename>. You need to run it from within
 251      the command prompt or set the environment variables "globally";
 252      otherwise it doesn't work.
 253     </para>
 254    </tip>
 255    <para>
 256     If you wish to recompile YAZ++ - for example if you modify
 257     settings in the <filename>makefile</filename> you can delete
 258     object files, etc by running.
 259     <screen>
 260      nmake clean
 261     </screen>
 262    </para>
 263    <para>
 264     The following files are generated upon successful compilation:
 265
 266     <variablelist>
 267      <varlistentry><term><filename>bin/yazproxy.dll</filename></term>
 268       <listitem><para>
 269         YAZ proxy DLL.
 270        </para></listitem></varlistentry>
 271
 272      <varlistentry><term><filename>lib/yazproxy.lib</filename></term>
 273       <listitem><para>
 274         Import library for <filename>yazproxy.dll</filename>.
 275        </para></listitem></varlistentry>
 276
 277      <varlistentry><term><filename>bin/yazproxy.exe</filename></term>
 278       <listitem><para>
 279         YAZ proxy. It's a WIN32 console application.
 280        </para></listitem></varlistentry>
 281
 282     </variablelist>
 283
 284    </para>
 285
 286   </section>
 287  </chapter>
 288  <!-- Keep this comment at the end of the file
 289  Local variables:
 290  mode: sgml
 291  sgml-omittag:t
 292  sgml-shorttag:t
 293  sgml-minimize-attributes:nil
 294  sgml-always-quote-attributes:t
 295  sgml-indent-step:1
 296  sgml-indent-data:t
 297  sgml-parent-document: "yazproxy.xml"
 298  sgml-local-catalogs: nil
 299  sgml-namecase-general:t
 300  End:
 301  -->