doc/installation.xml

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