doc/installation.xml

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