<!-- ============= Installation ============================== -->
-<sect1 id="sec_install">
+<chapter id="sec_install">
<title>Installation</title>
- <sect2>
- <title>Installing &appname; from sources</title>
+ <sect1 id="inst_from_src">
+ <title>Installing from sources</title>
<para>Currently, the only intended way to install &appname; is starting
from its source code. </para>
- <sect3>
+ <sect2 id="get_source_code">
<title>Getting the source code</title>
<para>You can get the &appname; source code in two ways:
</orderedlist>
</para>
- </sect3>
+ </sect2>
- <sect3 id="build_requirements">
+ <sect2 id="build_requirements">
<title>Requirements</title>
<para>In order to build &appname; from sources you will need some
tools and libraries. They are listed below.
<note>
- <title>Note for Debian users</title>
-
- <para>If you are running a <ulink type="http"
- url="http://www.debian.org">Debian GNU/Linux</ulink> distribution
- you can have APT install all the required tools and libraries by
- adding the following repository to your
- <filename>/etc/apt/sources.list</filename>: <programlisting>
- deb <ulink type="http"
- url="http://people.debian.org/~zack">http://people.debian.org/~zack</ulink> unstable helm
- </programlisting> and installing the
- <application>helm-matita-deps</application> package.</para>
+ <title>Note for Debian (and derivatives) users</title>
+
+ <para>If you are running a
+ <ulink type="http"
+ url="http://www.debian.org">Debian GNU/Linux</ulink>
+ distribution,
+ or any of its derivative like <ulink type="http"
+ url="http://ubuntu.com">Ubuntu</ulink>,
+ you can use APT to install all the required tools and
+ libraries since they are all part of the Debian archive.
+ </para>
+ <para>
+ 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
+ </para>
+ <para>
+ An official debian package is going to be added to the
+ archive too.
+ </para>
</note>
</varlistentry>
<varlistentry>
- <term>
- <application> <ulink type="http"
- url="http://www.mysql.com">MySQL</ulink> </application>
- </term>
+ <term> &MYSQL; </term>
<term>
<application> <ulink type="http"
url="http://raevnos.pennmush.org/code/ocaml-mysql/">OCaml
<para> SQL database and OCaml bindings for its client-side library
</para>
<para> The SQL database itself is not strictly needed to run
- &appname;, but we stronly encourage its use since a lot of
- features are disabled without it. Still, the OCaml bindings of
- the library are needed at compile time.</para>
+ &appname;, but the client libraries are.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> &Sqlite; </term>
+ <term>
+ <application>
+ <ulink type="http"
+ url="http://ocaml.info/home/ocaml_sources.html">
+ OCaml Sqlite3
+ </ulink> </application>
+ </term>
+ <listitem>
+ <para> Sqlite database and OCaml bindings
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<application> <ulink type="http"
- url="http://www.cduce.org/download.html#side">ulex</ulink>
+ url="http://www.cduce.org/download.html">ulex</ulink>
</application>
</term>
<listitem>
<varlistentry>
<term>
<application> <ulink type="http"
- url="http://cristal.inria.fr/~xleroy/software.html#camlzip">CamlZip</ulink>
+ url="http://cristal.inria.fr/~xleroy/software.html">CamlZip</ulink>
</application>
</term>
<listitem>
</variablelist> </para>
- </sect3>
+ </sect2>
+
+ <sect2 id="database_setup">
+ <title>Database setup</title>
+
+ <para> To fully exploit &appname; indexing and search capabilities you
+ will need a working &MYSQL; database. Detalied instructions on how to do
+ it can be found in the <ulink type="http"
+ url="http://dev.mysql.com/doc/">MySQL documentation</ulink>. Here you
+ can find a quick howto. </para>
+
+ <para> In order to create a database you need administrator permissions on
+ your MySQL installation, usually the root account has them. Once you
+ have the permissions, a new database can be created executing
+ <userinput>mysqladmin create matita</userinput>
+ (<emphasis>matita</emphasis> is the default database name, you can
+ change it using the <parameter>db.user</parameter> key of the
+ configuration file). </para>
+
+ <para> Then you need to grant the necessary access permissions to the
+ database user of &appname;, typing <userinput>echo "grant all privileges
+ on matita.* to helm;" | mysql matita</userinput> should do the trick
+ (<emphasis>helm</emphasis> is the default user name used by &appname; to
+ access the database, you can change it using the
+ <parameter>db.user</parameter> key of the configuration file).
+ </para>
- <sect3 id="build_instructions">
- <title>Instructions</title>
+ <note>
+ <para> This way you create a database named <emphasis>matita</emphasis>
+ on which anyone claiming to be the <emphasis>helm</emphasis> user can
+ do everything (like adding dummy data or destroying the contained
+ one). It is strongly suggested to apply more fine grained permissions,
+ how to do it is out of the scope of this manual.</para>
+ </note>
+
+ </sect2>
+
+ <sect2 id="build_instructions">
+ <title>Compiling and installing</title>
<para> Once you get the source code the installations steps should be
quite familiar.</para>
<para> First of all you need to configure the build process executing
<userinput>./configure</userinput>. This will check that all needed
- tools and library are installed. You may need to pass on the command
- line some of the parameters riported below:
+ tools and library are installed and prepare the sources for compilation
+ and installation. </para>
+
+ <para> Quite a few (optional) arguments may be passed to the
+ <application>configure</application> command line to change build time
+ parameters. They are listed below, together with their
+ default values: </para>
<variablelist>
- <title><application>configure</application> parameters</title>
+ <title> <application>configure</application> command line
+ arguments</title>
<varlistentry>
- <term>&TODO;</term>
- <listitem><para>&TODO;</para></listitem>
+ <term>
+ <userinput>--with-runtime-dir=<replaceable>dir</replaceable></userinput>
+ </term>
+ <listitem>
+ <para>
+ (<emphasis>Default:</emphasis>
+ <filename>/usr/local/matita</filename>) Runtime base directory
+ where all &appname; stuff (executables, configuration files,
+ standard library, ...) will be installed
+ </para>
+ </listitem>
</varlistentry>
- </variablelist>
+ <varlistentry>
+ <term>
+ <userinput>--with-dbhost=<replaceable>host</replaceable></userinput>
+ </term>
+ <listitem>
+ <para>
+ (<emphasis>Default:</emphasis> localhost) Default SQL server
+ hostname. Will be used while building the standard library
+ during the installation and to create the default &appname;
+ configuration. May be changed later in configuration file.
+ </para>
+ </listitem>
+ </varlistentry>
- </para>
+ <varlistentry>
+ <term>
+ <userinput>--enable-debug</userinput>
+ </term>
+ <listitem>
+ <para>
+ (<emphasis>Default:</emphasis> disabled) Enable debugging code.
+ Not for the casual user.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <para> Then you will manage the build process using <application><ulink
- type="http"
+ <para> Then you will manage the build and install process using
+ <application><ulink type="http"
url="http://www.gnu.org/software/make/">make</ulink></application>
as usual. Below are reported the targets you have to invoke in sequence
- to build and install.
+ to build and install:
+ </para>
<variablelist>
<title><application>make</application> targets</title>
<term><userinput>world</userinput></term>
<listitem>
<para>builds components needed by &appname; and &appname; itself
- (in bytecode only or in both bytecode and native code depending
+ (in bytecode or native code depending
on the availability of the OCaml native code compiler) </para>
</listitem>
</varlistentry>
- <varlistentry>
- <term><userinput>library</userinput></term>
- <listitem>
- <para>uses the (just built) <application>matitac</application>
- compiler to build the &appname; standard library. </para>
- <para>For this step you will need a working SQL database (for
- indexing the standard library while you are compiling it). See
- &TODO; for instructions on how to set it up.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><userinput>install</userinput></term>
<listitem>
<para>installs &appname; related tools, standard library and the
- needed runtime stuff in the proper places on the filesystem
+ needed runtime stuff in the proper places on the filesystem.
+ </para>
+ <para>As a part of the installation process the &appname;
+ standard library will be compiled, thus testing that the just
+ built <application>matitac</application> compiler works
+ properly.</para>
+ <para>For this step you will need a working SQL database (for
+ indexing the standard library while you are compiling it). See
+ <ulink type="http" url="#database_setup">Database setup</ulink>
+ for instructions on how to set it up.
</para>
</listitem>
</varlistentry>
</variablelist>
-
- </para>
- </sect3>
-
- </sect2>
-</sect1>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="matita.conf.xml">
+ <title>Configuring Matita</title>
+ <para>
+ The file <emphasis>matita.conf.xml</emphasis>...
+ &TODO;
+ </para>
+ <figure><title>Configuring the Databases</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="figures/database.png" format="PNG" srccredit="Enrico Tassi"/>
+ </imageobject>
+ <textobject><phrase>How to configure the databases.</phrase></textobject>
+ </mediaobject>
+ </figure>
+ </sect1>
+
+</chapter>
projects / helm.git / blobdiff