doc/installation.xml

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