doc/installation.xml

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