2 <!-- ============= Installation ============================== -->
4 <chapter id="sec_install">
5 <title>Installation</title>
7 <sect1 id="inst_from_src">
8 <title>Installing from sources</title>
10 <para>Currently, the only intended way to install &appname; is starting
11 from its source code. </para>
13 <sect2 id="get_source_code">
14 <title>Getting the source code</title>
16 <para>You can get the &appname; source code in two ways:
19 <listitem> <para> go to the <ulink type="http"
20 url="http://matita.cs.unibo.it/download.shtml">download
21 page</ulink> and get the <ulink type="http"
22 url="http://matita.cs.unibo.it/sources/matita-latest.tar.gz"
23 >latest released source tarball</ulink>;</para> </listitem>
25 <listitem> <para> get the development sources from <ulink type="http"
26 url="http://helm.cs.unibo.it/websvn/listing.php?repname=helm&path=%2F&sc=0">our
27 SVN repository</ulink>. You will need the
28 <application>components/</application> and
29 <application>matita/</application> directories from the
30 <filename>trunk/helm/software/</filename> directory, plus the
31 <filename>configure</filename> and <filename>Makefile*</filename>
32 stuff from the same directory. </para>
34 <para>In this case you will need to run
35 <command>autoconf</command> before proceding with the building
36 instructions below.</para> </listitem>
43 <sect2 id="build_requirements">
44 <title>Requirements</title>
46 <para>In order to build &appname; from sources you will need some
47 tools and libraries. They are listed below.
50 <title>Note for Debian (and derivatives) users</title>
52 <para>If you are running a
54 url="http://www.debian.org">Debian GNU/Linux</ulink>
56 or any of its derivative like <ulink type="http"
57 url="http://ubuntu.com">Ubuntu</ulink>,
58 you can use APT to install all the required tools and
59 libraries since they are all part of the Debian archive.
62 apt-get install ocaml ocaml-findlib libgdome2-ocaml-dev liblablgtk2-ocaml-dev liblablgtkmathview-ocaml-dev liblablgtksourceview-ocaml-dev libsqlite3-ocaml-dev libocamlnet-ocaml-dev libzip-ocaml-dev libhttp-ocaml-dev ocaml-ulex08 libexpat-ocaml-dev libmysql-ocaml-dev camlp5
65 An official debian package is going to be added to the
72 <title>Required tools and libraries</title>
76 <application> <ulink type="http"
77 url="http://caml.inria.fr">OCaml</ulink> </application>
80 <para> the Objective Caml compiler, version 3.09 or above </para>
86 <application> <ulink type="http"
87 url="http://www.ocaml-programming.de/packages/">Findlib</ulink>
91 <para> OCaml package manager, version 1.1.1 or above</para>
97 <application> <ulink type="http"
98 url="http://www.xs4all.nl/~mmzeeman/ocaml/">OCaml
99 Expat</ulink> </application>
102 <para>OCaml bindings for the <application><ulink type="http"
103 url="http://expat.sourceforge.net/">expat</ulink>
104 library</application> </para>
110 <application> <ulink type="http"
111 url="http://gmetadom.sourceforge.net/">GMetaDOM</ulink>
115 <para>OCaml bindings for the <application><ulink type="http"
116 url="http://gdome2.cs.unibo.it/">Gdome 2</ulink>
117 library</application></para>
123 <application> <ulink type="http"
124 url="http://www.bononia.it/~zack/ocaml-http.en.html">OCaml
125 HTTP</ulink> </application>
128 <para> OCaml library to write HTTP daemons (and clients) </para>
134 <application> <ulink type="http"
135 url="http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html">LablGTK</ulink>
139 <para> OCaml bindings for the <application> <ulink type="http"
140 url="http://www.gtk.org"> GTK+</ulink> library
141 </application>, version 2.6.0 or above </para>
147 <application> <ulink type="http"
148 url="http://helm.cs.unibo.it/mml-widget/">GtkMathView</ulink>
152 <application> <ulink type="http"
153 url="http://helm.cs.unibo.it/mml-widget/">LablGtkMathView</ulink>
157 <para> GTK+ widget to render <ulink type="http"
158 url="http://www.w3.org/Math/">MathML</ulink> documents and its
159 OCaml bindings </para>
165 <application> <ulink type="http"
166 url="http://gtksourceview.sourceforge.net/">GtkSourceView</ulink>
170 <application> <ulink type="http"
171 url="http://helm.cs.unibo.it/software/lablgtksourceview/">LablGtkSourceView</ulink>
175 <para> extension for the GTK+ text widget (adding the typical
176 features of source code editors) and its OCaml bindings </para>
181 <term> &MYSQL; </term>
183 <application> <ulink type="http"
184 url="http://raevnos.pennmush.org/code/ocaml-mysql/">OCaml
185 MySQL</ulink> </application>
188 <para> SQL database and OCaml bindings for its client-side library
190 <para> The SQL database itself is not strictly needed to run
191 &appname;, but the client libraries are.</para>
196 <term> &Sqlite; </term>
200 url="http://ocaml.info/home/ocaml_sources.html">
202 </ulink> </application>
205 <para> Sqlite database and OCaml bindings
212 <application> <ulink type="http"
213 url="http://ocamlnet.sourceforge.net/">Ocamlnet</ulink>
217 <para> collection of OCaml libraries to deal with
218 application-level Internet protocols and conventions </para>
224 <application> <ulink type="http"
225 url="http://www.cduce.org/download.html">ulex</ulink>
229 <para> Unicode lexer generator for OCaml </para>
235 <application> <ulink type="http"
236 url="http://cristal.inria.fr/~xleroy/software.html">CamlZip</ulink>
240 <para> OCaml library to access <filename>.gz</filename> files
245 </variablelist> </para>
249 <sect2 id="database_setup">
250 <title>(optional) &MYSQL; setup</title>
252 <para> To fully exploit &appname; indexing and search capabilities
253 on a huge metadata set you may
254 need a working &MYSQL; database. Detalied instructions on how to do
255 it can be found in the <ulink type="http"
256 url="http://dev.mysql.com/doc/">MySQL documentation</ulink>. Here you
257 can find a quick howto. </para>
259 <para> In order to create a database you need administrator permissions on
260 your MySQL installation, usually the root account has them. Once you
261 have the permissions, a new database can be created executing
262 <userinput>mysqladmin create matita</userinput>
263 (<emphasis>matita</emphasis> is the default database name, you can
264 change it using the <parameter>db.user</parameter> key of the
265 configuration file). </para>
267 <para> Then you need to grant the necessary access permissions to the
268 database user of &appname;, typing <userinput>echo "grant all privileges
269 on matita.* to helm;" | mysql matita</userinput> should do the trick
270 (<emphasis>helm</emphasis> is the default user name used by &appname; to
271 access the database, you can change it using the
272 <parameter>db.user</parameter> key of the configuration file).
276 <para> This way you create a database named <emphasis>matita</emphasis>
277 on which anyone claiming to be the <emphasis>helm</emphasis> user can
278 do everything (like adding dummy data or destroying the contained
279 one). It is strongly suggested to apply more fine grained permissions,
280 how to do it is out of the scope of this manual.</para>
285 <sect2 id="build_instructions">
286 <title>Compiling and installing</title>
288 <para> Once you get the source code the installations steps should be
289 quite familiar.</para>
291 <para> First of all you need to configure the build process executing
292 <userinput>./configure</userinput>. This will check that all needed
293 tools and library are installed and prepare the sources for compilation
294 and installation. </para>
296 <para> Quite a few (optional) arguments may be passed to the
297 <application>configure</application> command line to change build time
298 parameters. They are listed below, together with their
299 default values: </para>
302 <title> <application>configure</application> command line
307 <userinput>--with-runtime-dir=<replaceable>dir</replaceable></userinput>
311 (<emphasis>Default:</emphasis>
312 <filename>/usr/local/matita</filename>) Runtime base directory
313 where all &appname; stuff (executables, configuration files,
314 standard library, ...) will be installed
321 <userinput>--with-dbhost=<replaceable>host</replaceable></userinput>
325 (<emphasis>Default:</emphasis> localhost) Default SQL server
326 hostname. Will be used while building the standard library
327 during the installation and to create the default &appname;
328 configuration. May be changed later in configuration file.
335 <userinput>--enable-debug</userinput>
339 (<emphasis>Default:</emphasis> disabled) Enable debugging code.
340 Not for the casual user.
346 <para> Then you will manage the build and install process using
347 <application><ulink type="http"
348 url="http://www.gnu.org/software/make/">make</ulink></application>
349 as usual. Below are reported the targets you have to invoke in sequence
350 to build and install:
354 <title><application>make</application> targets</title>
357 <term><userinput>world</userinput></term>
359 <para>builds components needed by &appname; and &appname; itself
360 (in bytecode or native code depending
361 on the availability of the OCaml native code compiler) </para>
366 <term><userinput>install</userinput></term>
368 <para>installs &appname; related tools, standard library and the
369 needed runtime stuff in the proper places on the filesystem.
371 <para>As a part of the installation process the &appname;
372 standard library will be compiled, thus testing that the just
373 built <application>matitac</application> compiler works
375 <para>For this step you will need a working SQL database (for
376 indexing the standard library while you are compiling it). See
377 <ulink type="http" url="#database_setup">Database setup</ulink>
378 for instructions on how to set it up.
389 <sect1 id="matita.conf.xml">
390 <title>Configuring &appname;</title>
392 The configuration file is divided in four sections. The user and
393 matita ones are self explicative and does not need user
394 intervention. Here we report a sample snippet for these two
395 sections. The remaining db and getter sections will be explained in
399 <section name="user">
400 <key name="home">$(HOME)</key>
401 <key name="name">$(USER)</key>
403 <section name="matita">
404 <key name="basedir">$(user.home)/.matita</key>
405 <key name="rt_base_dir">/usr/share/matita/</key>
406 <key name="owner">$(user.name)</key>
411 &appname; needs to store/fetch data and metadata. Data is essentially
412 composed of XML files, metadata is a set of tuples for a relational
413 model. Data and metadata can produced by the user or be already
414 available. Both kind of data/metadata can be local and/or remote.
417 The db section tells &appname; where to store and retrieve metadata,
418 while the getter section describes where XML files have to be
419 found. The following picture describes the suggested configuration.
420 Dashed arrows are determined by the configuration file.
422 <figure><title>Configuring the Databases</title>
425 <imagedata fileref="figures/database.png" format="PNG" srccredit="Enrico Tassi"/>
427 <textobject><phrase>How to configure the databases.</phrase></textobject>
430 <para>The getter</para>
432 Consider the following snippet and the URI
433 <userinput>cic:/matita/foo/bar.con</userinput>. If &appname;
434 is asked to read that object it will resolve the object trough
435 the getter. Since the first two entries are equally specific
436 (longest match rule applies) first the path
437 <userinput>file://$(matita.rt_base_dir)/xml/standard-library/foo/bar.con</userinput>
438 and then <userinput>file://$(user.home)/.matita/xml/matita/foo/bar.con</userinput>
442 <section name="getter">
443 <key name="cache_dir">$(user.home)/.matita/getter/cache</key>
446 file://$(matita.rt_base_dir)/xml/standard-library/
451 file://$(user.home)/.matita/xml/matita/
455 http://mowgli.cs.unibo.it/xml/
461 if the same URI has to be written, the former prefix is skipped
462 since it is marked as readonly (<userinput>ro</userinput>).
463 Objects resolved using the third prefix are readonly too, and are
464 retrieved using the network. There is no limit to the number of
465 prefixes the user can define. The distinction between prefixes marked
466 as readonly and legacy is that, legacy ones are really read only, while
467 the ones marked with <userinput>ro</userinput> are considered for
468 writing when &appname; is started in system mode (used to publish user
469 developments in the library space).
473 The database subsystem has three fron ends: library, user and
474 legacy. The latter is the only optional one. Every query is done on
475 every frontend, making the duplicate free union of the results.
476 The user front end kepps metadata produced by the user, and is thus
477 heavily accessed in read/write mode, while the library and legacy
478 fron ends are read only. Every front end can be connected to
479 backend, the storage actually.
480 Consider the following snippet.
484 <key name="metadata">mysql://mowgli.cs.unibo.it matita helm none legacy</key>
485 <key name="metadata">file://$(matita.rt_base_dir) metadata.db helm helm library</key>
486 <key name="metadata">file://$(matita.basedir) user.db helm helm user</key>
490 Here the usr database is a file (thus locally accessed trough the
491 Sqlite library) placed in the user's home directory. The library one is
492 placed in the &appname; runtime directory. The legacy fron end is
493 connected to a remote &MYSQL; based storage. Every metadata key
494 takes a path to the storage, the name of the database, the user name,
495 a password (or <userinput>none</userinput>) and the name of the front
496 end to which it is attached.