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