doc/installation.xml

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