d0670d17d24322850fab4cb9ed891da98d542465
[idzebra-moved-to-github.git] / doc / installation.xml
1  <chapter id="installation">
2   <title>Installation</title>
3   <para>
4    &zebra; is written in &acro.ansi; C and was implemented with portability in mind. 
5    We primarily use <ulink url="&url.gcc;">GCC</ulink> on UNIX and 
6    <ulink url="&url.vstudio;">Microsoft Visual C++</ulink> on Windows.
7   </para>
8
9   <para>
10    The software is regularly tested on
11    <ulink url="&url.debian;">Debian GNU/Linux</ulink>,
12    <ulink url="&url.redhat;">Red Hat Linux</ulink>,
13    <ulink url="&url.gentoo;">Gentoo Linux</ulink>,
14    <ulink url="&url.suse;">SuSE Linux</ulink>,
15    <ulink url="&url.freebsd;">FreeBSD (i386)</ulink>,
16    <ulink url="&url.macosx;">MAC OSX</ulink>,
17    <ulink url="&url.solaris;">SunOS 5.9
18     (sparc)</ulink>,
19    <ulink url="&url.windows2000;">Windows 2000</ulink>.
20   </para>
21   
22   <para>
23    &zebra; can be configured to use the following utilities (most of
24    which are optional):
25
26    <variablelist>
27     <varlistentry>
28      <term><ulink url="&url.yaz;">&yaz;</ulink>
29       (required)</term>
30      <listitem>
31       <para>
32        &zebra; uses &yaz; to support <ulink url="&url.z39.50;">&acro.z3950;</ulink> / 
33        <ulink url="&url.sru;">&acro.sru;</ulink>.
34        Zebra also uses a lot of other utilities (not related to networking),
35        such as memory management and XML support.
36       </para>
37       <para>
38        For the <link linkend="record-model-domxml">DOM XML</link>
39        / <link linkend="record-model-alvisxslt">ALVIS</link>
40        record filters, &yaz; must be compiled with 
41        <ulink url="&url.libxml2;">Libxml2</ulink>
42        and
43        <ulink url="&url.libxslt;">Libxslt</ulink>
44        support and Libxml2 must be version 2.6.15 or later.
45       </para>
46      </listitem>
47     </varlistentry>
48     <varlistentry>
49      <term><ulink url="&url.libiconv;">iconv</ulink>
50       (optional)</term>
51      <listitem>
52       <para>
53        Character set conversion. This is required if you're
54        going to use any other character set than UTF-8 and ISO-8859-1
55        for records. Note that some Unixes has iconv built-in.
56       </para>
57      </listitem>
58     </varlistentry>
59     <varlistentry>
60      <term><ulink url="&url.expat;">Expat</ulink>
61       (optional)</term>
62      <listitem>
63       <para>
64        &acro.xml; parser. If you're going to index real &acro.xml; you should
65        install this (filter grs.xml). On most systems you should be able
66        to find binary Expat packages.
67       </para>
68      </listitem>
69     </varlistentry>
70     
71     <varlistentry>
72      <term><ulink url="&url.tcl;">Tcl</ulink> (optional)</term>
73      <listitem>
74       <para>
75        Tcl is required if you  need to use the Tcl record filter
76        for &zebra;. You can find binary packages for Tcl for many
77        Unices and Windows.
78       </para>
79      </listitem>
80     </varlistentry>
81     
82     <varlistentry>
83      <term>
84       <ulink url="&url.autoconf;">Autoconf</ulink>,
85       <ulink url="&url.automake;">Automake</ulink>
86       (optional)</term>
87      <listitem>
88       <para>
89        GNU Automake and Autoconf are only required if you're
90        using the CVS version of &zebra;. You do not need these
91        if you have fetched a &zebra; tar.
92       </para>
93      </listitem>
94     </varlistentry>
95     
96     <varlistentry>
97      <term><ulink url="&url.docbook;">Docbook</ulink>
98       and friends (optional)</term>
99      <listitem>
100       <para>
101        These tools are only required if you're writing
102        documentation for &zebra;. You need the following
103        Debian packages: docbook, docbook-xml, docbook-xsl,
104        docbook-utils, xsltproc.
105       </para>
106      </listitem>
107     </varlistentry>
108    </variablelist>
109   </para>
110
111   <section id="installation-unix"><title>UNIX</title>
112    <para>
113     On Unix, GCC works fine, but any native
114     C compiler should be possible to use as long as it is 
115     &acro.ansi; C compliant.
116    </para>
117    
118    <para>
119     Unpack the distribution archive. The <literal>configure</literal>
120     shell script attempts to guess correct values for various
121     system-dependent variables used during compilation.
122     It uses those values to create a <literal>Makefile</literal> in each
123     directory of &zebra;.
124    </para>
125    
126    <para>
127     To run the configure script type:
128     
129     <screen>
130      ./configure
131     </screen>
132     
133    </para>
134    
135    <para>
136     The configure script attempts to use C compiler specified by
137     the <literal>CC</literal> environment variable.
138     If this is not set, <literal>cc</literal> or GNU C will be used.
139     The <literal>CFLAGS</literal> environment variable holds
140     options to be passed to the C compiler. If you're using a
141     Bourne-shell compatible shell you may pass something like this:
142     
143     <screen>
144      CC=/opt/ccs/bin/cc CFLAGS=-O ./configure
145     </screen>
146    </para>
147    <para>
148     The configure script support various options: you can see what they
149     are with
150     <screen>
151      ./configure --help
152     </screen>
153    </para>
154    
155    <para>
156     Once the build environment is configured, build the software by
157     typing:
158     <screen>
159      make
160     </screen>
161    </para>
162    
163    <para>
164     If the build is successful, two executables are created in the
165     sub-directory <literal>index</literal>:
166     <variablelist>
167      
168      <varlistentry>
169       <term><literal>zebrasrv</literal></term>
170       <listitem>
171        <para>
172         The &acro.z3950; server and search engine.
173        </para>
174       </listitem>
175      </varlistentry>
176      <varlistentry>
177      <term><literal>zebraidx</literal></term>
178       <listitem>
179        <para>
180         The administrative indexing tool.
181        </para>
182       </listitem>
183      </varlistentry>
184
185      <varlistentry>
186      <term><literal>index/*.so</literal></term>
187       <listitem>
188        <para>
189         The <literal>.so</literal>-files are &zebra; record filter modules.
190         There are modules for reading 
191         &acro.marc; (<filename>mod-grs-marc.so</filename>),
192         &acro.xml; (<filename>mod-grs-xml.so</filename>) , etc. 
193        </para>
194       </listitem>
195      </varlistentry>
196
197     </variablelist>
198    </para>
199
200    <note>
201     <para>
202      Using configure option <literal>--disable-shared</literal> builds
203      &zebra; statically and links "in" &zebra; filter code statically, i.e.
204      no <literal>.so-files</literal> are generated
205     </para>
206    </note>
207
208    <para>
209     You can now use &zebra;. If you wish to install it system-wide, then
210     as root type
211     <screen>
212      make install
213     </screen>
214     By default this will install the &zebra; executables in 
215     <filename>/usr/local/bin</filename>,
216     and the standard configuration files in 
217     <filename>/usr/local/share/idzebra-2.0</filename>. If
218     shared modules are built, these are installed in
219     <filename>/usr/local/lib/idzebra-2.0/modules</filename>.
220     You can override this with the <literal>--prefix</literal> option
221     to configure.
222    </para>
223   </section>
224
225   <section id="installation-debian"><title>GNU/Debian</title>
226    <section id="installation-debian-linux"><title>GNU/Debian Linux on
227    i686 Platform</title>
228     <para>
229      Index Data provides pre-compiled GNU/Debian i686 Linux packages
230      at our Debian package archive, both for
231      the Sarge and the Etch release. 
232     </para>
233     
234     <para>
235      To install these packages, you need to add two lines to your
236      <filename>/etc/apt/sources.list</filename> configuration file,
237      either the Sarge sources found at
238      <screen>
239       deb http://ftp.indexdata.dk/debian sarge main
240       deb-src http://ftp.indexdata.dk/debian sarge main
241      </screen>
242      or the Etch sources from 
243      <screen>
244       deb http://ftp.indexdata.dk/debian etch main
245       deb-src http://ftp.indexdata.dk/debian etch main
246      </screen>
247      After refreshing the package cache with the command
248      <screen>
249       apt-get update
250      </screen>
251      as <literal>root</literal>, the 
252      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
253      easily installed issuing
254      <screen>
255       apt-get install idzebra-2.0 idzebra-2.0-doc
256      </screen>
257     </para>
258    </section>
259    
260    <section id="installation-debia-nother">
261     <title>Ubuntu/Debian and GNU/Debian on other platforms</title>
262     <para>
263      These <ulink url="&url.idzebra;">&zebra;</ulink>
264      packages are specifically compiled for
265      GNU/Debian Linux systems. Installation on other 
266      GNU/Debian systems is possible by
267      re-compilation the Debian way: you need to add only the 
268      <literal>deb-src</literal> sources lines to the 
269      <filename>/etc/apt/sources.list</filename> configuration file,
270      that is either the Sarge sources
271      <screen>
272       deb-src http://ftp.indexdata.dk/debian sarge main
273      </screen>
274      or the Etch sources
275      <screen>
276       deb-src http://ftp.indexdata.dk/debian etch main
277      </screen>
278      After refreshing the package cache with the command
279      <screen>
280       apt-get update
281       apt-get build-dep idzebra-2.0
282      </screen>
283      as <literal>root</literal>, the 
284      <ulink url="&url.idzebra;">&zebra;</ulink> indexer is
285      recompiled and installed issuing
286      <screen>
287       fakeroot apt-get source --compile idzebra-2.0
288      </screen>
289      as normal user.
290      The compiled GNU/Debian packages can then be
291      installed as <literal>root</literal> issuing
292      <screen>
293       dpkg -i install idzebra-2.0*.deb libidzebra-2.0*.deb
294      </screen>
295     </para>
296    </section>
297   </section>
298
299   <section id="installation-win32"><title>WIN32</title>
300    <para>The easiest way to install &zebra; on Windows is by downloading
301     an installer from 
302     <ulink url="&url.idzebra.download.win32;">here</ulink>.
303     The installer comes with source too - in case you wish to
304     compile &zebra; with different Compiler options.
305    </para>
306    
307    <para>
308     &zebra; is shipped with "makefiles" for the NMAKE tool that comes
309     with <ulink url="&url.vstudio;">Microsoft Visual C++</ulink>.
310     Version 2003 and 2005 has been tested. We expect that zebra compiles
311     with version 6 as well.
312    </para>
313    <para>
314     Start a command prompt and switch the sub directory
315     <filename>WIN</filename> where the file <filename>makefile</filename>
316     is located. Customize the installation by editing the
317     <filename>makefile</filename> file (for example by using notepad).
318     
319     The following summarizes the most important settings in that file:
320     
321     <variablelist>
322      <varlistentry><term><literal>DEBUG</literal></term>
323       <listitem><para>
324         If set to 1, the software is
325         compiled with debugging libraries (code generation is
326         multi-threaded debug DLL).
327         If set to 0, the software is compiled with release libraries
328         (code generation is multi-threaded DLL).
329        </para></listitem>
330      </varlistentry>
331      
332      <varlistentry>
333       <term><literal>YAZDIR</literal></term>
334       <listitem><para>
335         Directory of &yaz; source. &zebra;'s makefile expects to find
336         <filename>yaz.lib</filename>, <filename>yaz.dll</filename> 
337         in <replaceable>yazdir</replaceable><literal>/lib</literal> and
338         <replaceable>yazdir</replaceable><literal>/bin</literal> respectively.
339        </para>
340       </listitem>
341      </varlistentry>
342      
343      <varlistentry>
344       <term><literal>HAVE_EXPAT</literal>,
345        <literal>EXPAT_DIR</literal></term>
346       <listitem><para>
347         If <literal>HAVE_EXPAT</literal> is set to 1, &zebra; is compiled
348         with <ulink url="&url.expat;">Expat</ulink> support.
349         In this configuration, set 
350         <literal>ZEBRA_DIR</literal> to the Expat source directory.
351         Windows version of Expat can be downloaded from
352         <ulink url="&url.expat;">SourceForge</ulink>.
353        </para></listitem>
354      </varlistentry>
355      
356      <varlistentry>
357       <term><literal>HAVE_ICONV</literal>,
358        <literal>ICONV_DIR</literal></term>
359        <listitem><para>
360         If <literal>HAVE_ICONV</literal> is set to 1, &zebra; is compiled
361         with iconv support. In this configuration, set 
362         <literal>ICONV_DIR</literal> to the iconv source directory.
363         Iconv binaries can be downloaded from
364         <ulink url="&url.libxml2.download.win32;">this site</ulink>.
365        </para>
366       </listitem>
367      </varlistentry>
368      
369      <varlistentry>
370       <term><literal>BZIP2INCLUDE</literal>,
371        <literal>BZIP2LIB</literal>,
372        <literal>BZIP2DEF</literal>
373       </term>
374       <listitem><para>
375         Define these symbols if &zebra; is to be compiled with
376         <ulink url="&url.bzip2;">BZIP2</ulink> record compression support.
377        </para></listitem>
378      </varlistentry>
379      
380     </variablelist>
381    </para>
382    <warning>
383     <para>
384      The <literal>DEBUG</literal> setting in the makefile for &zebra; must
385      be set to the same value as <literal>DEBUG</literal> setting in the
386      makefile for &yaz;.
387      If not, the &zebra; server/indexer will crash.
388     </para>
389    </warning>
390    <para>
391     When satisfied with the settings in the makefile, type
392     <screen>
393      nmake
394     </screen>
395    </para>
396    <note>
397     <para>
398      If the <filename>nmake</filename> command is not found on your system
399      you probably haven't defined the environment variables required to
400      use that tool. To fix that, find and run the batch file
401      <filename>vcvars32.bat</filename>. You need to run it from within
402      the command prompt or set the environment variables "globally";
403      otherwise it doesn't work.
404     </para>
405    </note>
406    <para>
407     If you wish to recompile &zebra; - for example if you modify
408      settings in the <filename>makefile</filename> you can delete
409     object files, etc by running.
410     <screen>
411      nmake clean
412     </screen>
413    </para>
414    <para>
415     The following files are generated upon successful compilation:
416     
417     <variablelist>
418      <varlistentry><term><filename>bin/zebraidx.exe</filename></term>
419       <listitem><para>
420         The &zebra; indexer.
421        </para></listitem></varlistentry>
422      
423      <varlistentry><term><filename>bin/zebrasrv.exe</filename></term>
424       <listitem><para>
425         The &zebra; server.
426        </para></listitem></varlistentry>
427      
428     </variablelist>
429     
430    </para>
431   </section>
432
433
434   <section id="installation-upgrade">
435    <title>Upgrading from &zebra; version 1.3.x</title>
436    <para>
437     &zebra;'s installation directories have changed a bit. In addition,
438     the new loadable modules must be defined in the 
439     master <filename>zebra.cfg</filename> configuration file. The old
440     version 1.3.x configuration options
441     <screen>
442      # profilePath - where to look for config files
443      profilePath: some/local/path:/usr/share/idzebra/tab
444     </screen>
445     must be changed to 
446     <screen>
447      # profilePath - where to look for config files
448      profilePath: some/local/path:/usr/share/idzebra-2.0/tab
449
450      # modulePath - where to look for loadable zebra modules
451      modulePath: /usr/lib/idzebra-2.0/modules
452     </screen>
453    </para>
454    <note>
455     <para>
456      The internal binary register structures have changed; all &zebra;
457      databases must be re-indexed after upgrade.
458     </para>
459    </note>
460    <para>
461     The attribute set definition files may no longer contain
462     redirection to other fields. 
463     For example the following snippet of
464     a custom <filename>custom/bib1.att</filename> 
465     &acro.bib1; attribute set definition file is no
466     longer supported:
467     <screen>
468      att 1016            Any            1016,4,1005,62
469     </screen>
470     and should be changed to 
471     <screen>
472      att 1016            Any
473     </screen>
474    </para>
475    <para>
476     Similar behaviour can be expressed in the new release by defining
477     a new index <literal>Any:w</literal> in all &acro.grs1;
478     <filename>*.abs</filename> record indexing configuration files.
479     The above example configuration needs to make the changes
480     from version 1.3.x indexing instructions
481     <screen>
482      xelm /*/alternative  Body-of-text:w,Title:s,Title:w
483      xelm /*/title        Body-of-text:w,Title:s,Title:w
484     </screen>
485     to version 2.0.0 indexing instructions
486     <screen>
487      xelm /*/alternative  Any:w,Body-of-text:w,Title:s,Title:w
488      xelm /*/title        Any:w,Body-of-text:w,Title:s,Title:w
489     </screen>
490    </para>
491    <para>
492     It is also possible to map the numerical attribute value  
493     <literal>@attr 1=1016</literal> onto another already existing huge
494     index, in this example, one could for example use the mapping
495     <screen>
496      att 1016            Body-of-text
497     </screen>
498     with equivalent outcome without editing all  &acro.grs1;
499     <filename>*.abs</filename> record indexing configuration files.
500    </para>
501
502    <para>
503     Server installations which use the special
504     <literal>&acro.idxpath;</literal> attribute set must add the following
505     line to the <filename>zebra.cfg</filename> configuration file:
506     <screen>
507      attset: idxpath.att
508     </screen>
509     </para>
510   </section>
511   
512  </chapter>
513  <!-- Keep this comment at the end of the file
514  Local variables:
515  mode: sgml
516  sgml-omittag:t
517  sgml-shorttag:t
518  sgml-minimize-attributes:nil
519  sgml-always-quote-attributes:t
520  sgml-indent-step:1
521  sgml-indent-data:t
522  sgml-parent-document: "zebra.xml"
523  sgml-local-catalogs: nil
524  sgml-namecase-general:t
525  End:
526  -->