<!-- ============= 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>
- <listitem> <para>foo</para> </listitem>
- <listitem> <para>bar</para> </listitem>
+
+ <listitem> <para> go to the <ulink type="http"
+ url="http://matita.cs.unibo.it/download.shtml">download
+ page</ulink> and get the <ulink type="http"
+ url="http://matita.cs.unibo.it/sources/matita-latest.tar.gz"
+ >latest released source tarball</ulink>;</para> </listitem>
+
+ <listitem> <para> get the development sources from <ulink type="http"
+ url="http://helm.cs.unibo.it/websvn/listing.php?repname=helm&path=%2F&sc=0">our
+ SVN repository</ulink>. You will need the
+ <application>components/</application> and
+ <application>matita/</application> directories from the
+ <filename>trunk/helm/software/</filename> directory, plus the
+ <filename>configure</filename> and <filename>Makefile*</filename>
+ stuff from the same directory. </para>
+
+ <para>In this case you will need to run
+ <command>autoconf</command> before proceding with the building
+ instructions below.</para> </listitem>
+
</orderedlist>
</para>
- </sect3>
+ </sect2>
+
+ <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>
+
+ </note>
+
+ <variablelist>
+ <title>Required tools and libraries</title>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://caml.inria.fr">OCaml</ulink> </application>
+ </term>
+ <listitem>
+ <para> the Objective Caml compiler, version 3.09 or above </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://www.ocaml-programming.de/packages/">Findlib</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> OCaml package manager, version 1.1.1 or above</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://www.xs4all.nl/~mmzeeman/ocaml/">OCaml
+ Expat</ulink> </application>
+ </term>
+ <listitem>
+ <para>OCaml bindings for the <application><ulink type="http"
+ url="http://expat.sourceforge.net/">expat</ulink>
+ library</application> </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://gmetadom.sourceforge.net/">GMetaDOM</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para>OCaml bindings for the <application><ulink type="http"
+ url="http://gdome2.cs.unibo.it/">Gdome 2</ulink>
+ library</application></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://www.bononia.it/~zack/ocaml-http.en.html">OCaml
+ HTTP</ulink> </application>
+ </term>
+ <listitem>
+ <para> OCaml library to write HTTP daemons (and clients) </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://wwwfun.kurims.kyoto-u.ac.jp/soft/lsl/lablgtk.html">LablGTK</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> OCaml bindings for the <application> <ulink type="http"
+ url="http://www.gtk.org"> GTK+</ulink> library
+ </application>, version 2.6.0 or above </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://helm.cs.unibo.it/mml-widget/">GtkMathView</ulink>
+ </application>
+ </term>
+ <term>
+ <application> <ulink type="http"
+ url="http://helm.cs.unibo.it/mml-widget/">LablGtkMathView</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> GTK+ widget to render <ulink type="http"
+ url="http://www.w3.org/Math/">MathML</ulink> documents and its
+ OCaml bindings </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://gtksourceview.sourceforge.net/">GtkSourceView</ulink>
+ </application>
+ </term>
+ <term>
+ <application> <ulink type="http"
+ url="http://helm.cs.unibo.it/software/lablgtksourceview/">LablGtkSourceView</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> extension for the GTK+ text widget (adding the typical
+ features of source code editors) and its OCaml bindings </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> &MYSQL; </term>
+ <term>
+ <application> <ulink type="http"
+ url="http://raevnos.pennmush.org/code/ocaml-mysql/">OCaml
+ MySQL</ulink> </application>
+ </term>
+ <listitem>
+ <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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://ocamlnet.sourceforge.net/">Ocamlnet</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> collection of OCaml libraries to deal with
+ application-level Internet protocols and conventions </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://www.cduce.org/download.html">ulex</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> Unicode lexer generator for OCaml </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <application> <ulink type="http"
+ url="http://cristal.inria.fr/~xleroy/software.html">CamlZip</ulink>
+ </application>
+ </term>
+ <listitem>
+ <para> OCaml library to access <filename>.gz</filename> files
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist> </para>
+
+ </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>
+
+ <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 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 in the table below, together with their
+ default values.
+
+ <table frame="all">
+ <title> <application>configure</application> command line
+ arguments</title>
+ <tgroup cols="3" align="left" colsep="1" rowsep="1">
+ <thead>
+ <row>
+ <entry align="center">Argument</entry>
+ <entry align="center">Default</entry>
+ <entry align="center">Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <userinput>--with-runtime-dir=<replaceable>dir</replaceable></userinput>
+ </entry>
+ <entry> <filename>/usr/local/matita/</filename> </entry>
+ <entry> <para> Runtime base directory where all &appname; stuff
+ (executables, configuration files, standard
+ library, ...) will be installed </para> </entry>
+ </row>
+ <row>
+ <entry>
+ <userinput>--with-dbhost=<replaceable>host</replaceable></userinput>
+ </entry>
+ <entry> localhost </entry>
+ <entry> <para>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></entry>
+ </row>
+ <row>
+ <entry> <userinput>--enable-debug</userinput></entry>
+ <entry> disabled </entry>
+ <entry> <para> Enable debugging code. Not for the casual user.
+ </para> </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </para>
+
+ <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.
+
+ <variablelist>
+ <title><application>make</application> targets</title>
+
+ <varlistentry>
+ <term><userinput>world</userinput></term>
+ <listitem>
+ <para>builds components needed by &appname; and &appname; itself
+ (in bytecode or native code depending
+ on the availability of the OCaml native code compiler) </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.
+ </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>
+
+ </sect2>
- </sect2>
-</sect1>
+ </sect1>
+</chapter>
projects / helm.git / blobdiff