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