doc/installation.xml

   1 <chapter id="installation">
   2   <!-- $Id: installation.xml,v 1.6 2004-04-23 16:10:24 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 such as
 121         configuration files, XSLT files, CQL to RPN conversion files,
 122         a sample start/stop control script
 123         <filename>yazproxy.ctl.sh</filename> that can be used as
 124         template for an <filename>/etc/init.d</filename> script.
 125         These files are installed in the YAZ proxy's data area
 126         (<parameter>prefix</parameter><literal>/share/yazproxy</literal>).
 127        </para></listitem>
 128      </varlistentry>
 129
 130     </variablelist>
 131    </para>
 132   </section>
 133   <section id="windows">
 134    <title>Building on Windows</title>
 135    <para>
 136     YAZ++ is shipped with "makefiles" for the NMAKE tool that comes
 137     with <ulink url="http://msdn.microsoft.com/vstudio/">
 138      Microsoft Visual Studio</ulink>.
 139     Version 6 and .NET has been tested. We expect that YAZ++ compiles
 140     with version 5 as well.
 141    </para>
 142    <note>
 143     <para>
 144      The YAZ proxy has never been used in production on Windows. Although
 145      it compiles and runs, doesn't mean it scale on that platform.
 146      Furthermore the
 147      YAZ proxy currently doesn't run as a Service - only as a Console
 148      application.
 149     </para>
 150    </note>
 151    <para>
 152     Start a command prompt and switch the sub directory
 153     <filename>WIN</filename> where the file <filename>makefile</filename>
 154     is located. Customize the installation by editing the
 155     <filename>makefile</filename> file (for example by using notepad).
 156
 157     The following summarizes the most important settings in that file:
 158
 159     <variablelist>
 160      <varlistentry><term><literal>DEBUG</literal></term>
 161       <listitem><para>
 162         If set to 1, the software is
 163         compiled with debugging libraries (code generation is
 164         multi-threaded debug DLL).
 165         If set to 0, the software is compiled with release libraries
 166         (code generation is multi-threaded DLL).
 167        </para></listitem>
 168      </varlistentry>
 169
 170      <varlistentry><term><literal>YAZ_DIR</literal></term>
 171       <listitem><para>
 172         This must be set to the home of the YAZ source directory.
 173        </para></listitem>
 174      </varlistentry>
 175
 176      <varlistentry><term><literal>YAZPP_DIR</literal></term>
 177       <listitem><para>
 178         This must be set to the home of the YAZ++ source directory.
 179        </para></listitem>
 180      </varlistentry>
 181
 182      <varlistentry>
 183       <term><literal>HAVE_XSLT</literal>,
 184        <literal>LIBXSLT_DIR</literal></term>
 185       <listitem>
 186        <para>
 187         If <literal>HAVE_LIBXSLT</literal> is set to 1, the proxy is compiled
 188         with XSLT and XML support. In this configuration, set
 189         <literal>LIBXSLT_DIR</literal> to the
 190         <ulink url="http://www.xmlsoft.org/">libXSLT</ulink> source
 191         directory.
 192        </para>
 193
 194        <note>
 195         <para>
 196          If you enable libXSLT you have to enable libxml2 and its
 197          sub components zlib and iconv as well.
 198         </para>
 199        </note>
 200
 201        <para>
 202         Windows versions of libXSLT, libxml2, zlib and iconv can be found
 203         <ulink url="http://www.zlatkovic.com/libxml.en.html">
 204          here</ulink>.
 205        </para>
 206       </listitem>
 207      </varlistentry>
 208
 209      <varlistentry>
 210       <term><literal>HAVE_ICONV</literal>,
 211        <literal>ICONV_DIR</literal></term>
 212       <listitem><para>
 213         If <literal>HAVE_ICONV</literal> is set to 1, the proxy is
 214         compiled with iconv support. In this configuration, set
 215         <literal>ICONV_DIR</literal> to the iconv source directory.
 216        </para></listitem>
 217      </varlistentry>
 218
 219      <varlistentry>
 220       <term><literal>HAVE_LIBXML2</literal>,
 221        <literal>LIBXML2_DIR</literal></term>
 222       <listitem>
 223        <para>
 224         If <literal>HAVE_LIBXML2</literal> is set to 1, the proxy is compiled
 225         with XML support. In this configuration, set
 226         <literal>LIBXML2_DIR</literal> to the
 227         <ulink url="http://www.xmlsoft.org/">libxml2</ulink> source directory
 228         and
 229         <literal>ZLIB_DIR</literal> to the zlib directory.
 230        </para>
 231
 232        <note>
 233         <para>
 234          YAZ++ is not using ZLIB. But libxml2 is.
 235         </para>
 236        </note>
 237       </listitem>
 238      </varlistentry>
 239
 240     </variablelist>
 241    </para>
 242    <para>
 243     When satisfied with the settings in the makefile, type
 244     <screen>
 245      nmake
 246     </screen>
 247    </para>
 248    <tip>
 249     <para>
 250      If the <filename>nmake</filename> command is not found on your system
 251      you probably haven't defined the environment variables required to
 252      use that tool. To fix that, find and run the batch file
 253      <filename>vcvars32.bat</filename>. You need to run it from within
 254      the command prompt or set the environment variables "globally";
 255      otherwise it doesn't work.
 256     </para>
 257    </tip>
 258    <para>
 259     If you wish to recompile YAZ++ - for example if you modify
 260     settings in the <filename>makefile</filename> you can delete
 261     object files, etc by running.
 262     <screen>
 263      nmake clean
 264     </screen>
 265    </para>
 266    <para>
 267     The following files are generated upon successful compilation:
 268
 269     <variablelist>
 270      <varlistentry><term><filename>bin/yazproxy.dll</filename></term>
 271       <listitem><para>
 272         YAZ proxy DLL.
 273        </para></listitem></varlistentry>
 274
 275      <varlistentry><term><filename>lib/yazproxy.lib</filename></term>
 276       <listitem><para>
 277         Import library for <filename>yazproxy.dll</filename>.
 278        </para></listitem></varlistentry>
 279
 280      <varlistentry><term><filename>bin/yazproxy.exe</filename></term>
 281       <listitem><para>
 282         YAZ proxy. It's a WIN32 console application.
 283        </para></listitem></varlistentry>
 284
 285     </variablelist>
 286
 287    </para>
 288
 289   </section>
 290  </chapter>
 291  <!-- Keep this comment at the end of the file
 292  Local variables:
 293  mode: sgml
 294  sgml-omittag:t
 295  sgml-shorttag:t
 296  sgml-minimize-attributes:nil
 297  sgml-always-quote-attributes:t
 298  sgml-indent-step:1
 299  sgml-indent-data:t
 300  sgml-parent-document: "yazproxy.xml"
 301  sgml-local-catalogs: nil
 302  sgml-namecase-general:t
 303  End:
 304  -->