Added more URLs to YAZ ZOOM doc
[yazpp-moved-to-github.git] / doc / installation.xml
1 <chapter id="installation">
2   <!-- $Id: installation.xml,v 1.19 2006-04-30 12:53:14 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 <ulink url="&url.gcc;">GCC</ulink>
7    so we know that works well with YAZ++. From time to time the
8    software is compiled on Windows using Visual C++.
9    Other compilers should work too. Let us know of portability
10    problems, etc. with your system.
11   </para>
12   <para>
13    YAZ++ is built on top of the 
14    <ulink url="&url.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>Installation on Unix (from source)</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         <filename>/usr/local</filename> is used.
38        </para></listitem>
39      </varlistentry>
40      <varlistentry>
41       <term><literal>--with-yaz </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     </variablelist>
56     For the whole list of <literal>configure</literal> options, refer
57     to the help:
58     <literal>./configure --help</literal>.
59    </para>
60    <para>
61     Configure uses GCC's C/C++ compiler if available. To specify another
62     compiler, set <literal>CXX</literal>. To use other compiler flags,
63     specify <literal>CXXFLAGS</literal>. To use <literal>CC</literal> 
64     with debugging you could use:
65     <screen>
66      CXXFLAGS="-g" CXX=CC ./configure
67     </screen>
68    </para>
69    <para>
70     This is what you have after successful compilation:
71     <variablelist>
72      <varlistentry>
73       <term><filename>src/libyazpp.la</filename></term> 
74       <listitem><para>
75         The YAZ++ library.
76         This library gets installed in your libraries directory
77         (<parameter>prefix</parameter><filename>/lib</filename>).
78        </para></listitem>
79      </varlistentry>
80      
81      <varlistentry>
82       <term><filename>src/libzoompp.la</filename></term> 
83       <listitem><para>
84         The <link linkend="zoom">ZOOM-C++</link> library.
85         This library gets installed in your libraries directory
86         (<parameter>prefix</parameter><filename>/lib</filename>).
87        </para></listitem>
88      </varlistentry>
89      
90      <varlistentry>
91       <term><filename>include/yazpp/*.h</filename></term> 
92       <listitem><para>
93         Various C++ header files, which you'll need for YAZ++
94         development. All these are installed in your header files area
95         (<parameter>prefix</parameter><filename>/include/yazpp</filename>).
96        </para></listitem>
97      </varlistentry>
98      
99      <varlistentry>
100       <term><filename>yazpp-config</filename></term> 
101       <listitem><para>
102         A Bourne shell-script utility that returns the values of the
103         <envar>CFLAGS</envar> and <envar>LIBS</envar>
104         environment variables
105         needed in order to compile your applications with the YAZ++
106         library.  This script gets installed in your binaries directory
107         (<parameter>prefix</parameter><filename>/bin</filename>).
108        </para></listitem>
109      </varlistentry>
110
111      <varlistentry>
112       <term><filename>zoom/zclient</filename></term> 
113       <listitem><para>
114         ZOOM C++ demonstration client that uses the ZOOM C++ classes.
115         This client does not get installed in the system directories.
116        </para></listitem>
117      </varlistentry>
118
119      <varlistentry>
120       <term><filename>src/yaz-my-client</filename></term> 
121       <listitem><para>
122         YAZ C++ demonstration client. This client does not
123         get installed in the system directories.
124        </para></listitem>
125      </varlistentry>
126
127      <varlistentry>
128       <term><filename>src/yaz-my-server</filename></term> 
129       <listitem><para>
130         YAZ C++ demonstration server. This server does not
131         get installed in the system directories.
132        </para></listitem>
133      </varlistentry>
134     </variablelist>
135    </para>
136   </section>
137   <section id="windows">
138    <title>Installation on Windows</title>
139    <para>
140     YAZ++ is shipped with "makefiles" for the NMAKE tool that comes
141     with <ulink url="&url.vstudio;">Microsoft Visual Studio</ulink>.
142     Version 2003 (7) and 2005 (8) has been tested.
143     We expect that YAZ++ compiles with versions 5 and 6 as well.
144    </para>
145    <para>
146     Start a command prompt and switch the sub directory
147     <filename>WIN</filename> where the file <filename>makefile</filename>
148     is located. Customize the installation by editing the
149     <filename>makefile</filename> file (for example by using notepad).
150     
151     The following summarizes the most important settings in that file:
152     
153     <variablelist>
154      <varlistentry><term><literal>DEBUG</literal></term>
155       <listitem><para>
156         If set to 1, the software is
157         compiled with debugging libraries (code generation is
158         multi-threaded debug DLL).
159         If set to 0, the software is compiled with release libraries
160         (code generation is multi-threaded DLL).
161        </para></listitem>
162      </varlistentry>
163      <varlistentry><term><filename>YAZ_DIR</filename></term>
164       <listitem><para>
165         Specifies the directory of the YAZ source.
166        </para></listitem>
167      </varlistentry>
168     </variablelist>
169    </para>
170    <para>
171     When satisfied with the settings in the makefile, type
172     <screen>
173      nmake
174     </screen>
175    </para>
176    <tip>
177     <para>
178      If the <filename>nmake</filename> command is not found on your system
179      you probably haven't defined the environment variables required to
180      use that tool. To fix that, find and run the batch file
181      <filename>vcvars32.bat</filename>. You need to run it from within
182      the command prompt or set the environment variables "globally";
183      otherwise it doesn't work.
184     </para>
185    </tip>
186    <para>
187     If you wish to recompile YAZ++ - for example if you modify
188     settings in the <filename>makefile</filename> you can delete
189     object files, etc by running.
190     <screen>
191      nmake clean
192     </screen>
193    </para>
194    <para>
195     The following files are generated upon successful compilation:
196     
197     <variablelist>
198      <varlistentry><term><filename>bin/yazpp.dll</filename></term>
199       <listitem><para>
200         YAZ++ DLL . Includes ZOOM C++ as well.
201         For the debug version <filename>lib/yazppd.dll</filename>
202         is created instead.
203        </para></listitem></varlistentry>
204      
205      <varlistentry><term><filename>lib/yazpp.lib</filename></term>
206       <listitem><para>
207         Import library for <filename>yazpp.dll</filename>.
208         For the debug version <filename>lib/yazppd.lib</filename>
209         is created instead.
210        </para></listitem></varlistentry>
211      
212      <varlistentry><term><filename>bin/yaz-my-client.exe</filename></term>
213       <listitem><para>
214         Z39.50 client demonstrating the YAZ++ API.
215        </para></listitem></varlistentry>
216
217      <varlistentry><term><filename>bin/yaz-my-server.exe</filename></term>
218       <listitem><para>
219         Z39.50 server demonstrating the YAZ++ API.
220        </para></listitem></varlistentry>
221
222      <varlistentry><term><filename>bin/zclient.exe</filename></term>
223       <listitem><para>
224         ZOOM C++ demo client. A simple WIN32 console application.
225        </para></listitem></varlistentry>
226      
227     </variablelist>
228     
229    </para>
230    
231   </section>
232  </chapter>
233  <!-- Keep this comment at the end of the file
234  Local variables:
235  mode: sgml
236  sgml-omittag:t
237  sgml-shorttag:t
238  sgml-minimize-attributes:nil
239  sgml-always-quote-attributes:t
240  sgml-indent-step:1
241  sgml-indent-data:t
242  sgml-parent-document: "yazpp.xml"
243  sgml-local-catalogs: nil
244  sgml-namecase-general:t
245  End:
246  -->