X-Git-Url: http://matita.cs.unibo.it/gitweb/?p=helm.git;a=blobdiff_plain;f=matita%2Fhelp%2FC%2Fsec_install.xml;fp=matita%2Fhelp%2FC%2Fsec_install.xml;h=7dc37937b7525a8e0df725a5a32eb16b337858bd;hp=0000000000000000000000000000000000000000;hb=f61af501fb4608cc4fb062a0864c774e677f0d76;hpb=58ae1809c352e71e7b5530dc41e2bfc834e1aef1 diff --git a/matita/help/C/sec_install.xml b/matita/help/C/sec_install.xml new file mode 100644 index 000000000..7dc37937b --- /dev/null +++ b/matita/help/C/sec_install.xml @@ -0,0 +1,501 @@ + + + + + Installation + + + Installing from sources + + Currently, the only intended way to install &appname; is starting + from its source code. + + + Getting the source code + + You can get the &appname; source code in two ways: + + + go to the download + page and get the latest released source tarball; + + get the development sources from our + SVN repository. You will need the + components/ and + matita/ directories from the + trunk/helm/software/ directory, plus the + configure and Makefile* + stuff from the same directory. + + In this case you will need to run + autoconf before proceding with the building + instructions below. + + + + + + + + Requirements + + In order to build &appname; from sources you will need some + tools and libraries. They are listed below. + + + Note for Debian (and derivatives) users + + If you are running a + Debian GNU/Linux + distribution, + or any of its derivative like Ubuntu, + you can use APT to install all the required tools and + libraries since they are all part of the Debian archive. + + + 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 + + + An official debian package is going to be added to the + archive too. + + + + + + Required tools and libraries + + + + OCaml + + + the Objective Caml compiler, version 3.09 or above + + + + + + Findlib + + + + OCaml package manager, version 1.1.1 or above + + + + + + OCaml + Expat + + + OCaml bindings for the expat + library + + + + + + GMetaDOM + + + + OCaml bindings for the Gdome 2 + library + + + + + + OCaml + HTTP + + + OCaml library to write HTTP daemons (and clients) + + + + + + LablGTK + + + + OCaml bindings for the GTK+ library + , version 2.6.0 or above + + + + + + GtkMathView + + + + LablGtkMathView + + + + GTK+ widget to render MathML documents and its + OCaml bindings + + + + + + GtkSourceView + + + + LablGtkSourceView + + + + extension for the GTK+ text widget (adding the typical + features of source code editors) and its OCaml bindings + + + + + &MYSQL; + + OCaml + MySQL + + + SQL database and OCaml bindings for its client-side library + + The SQL database itself is not strictly needed to run + &appname;, but the client libraries are. + + + + + &Sqlite; + + + + OCaml Sqlite3 + + + + Sqlite database and OCaml bindings + + + + + + + Ocamlnet + + + + collection of OCaml libraries to deal with + application-level Internet protocols and conventions + + + + + + ulex + + + + Unicode lexer generator for OCaml + + + + + + CamlZip + + + + OCaml library to access .gz files + + + + + + + + + + (optional) &MYSQL; setup + + To fully exploit &appname; indexing and search capabilities + on a huge metadata set you may + need a working &MYSQL; database. Detalied instructions on how to do + it can be found in the MySQL documentation. Here you + can find a quick howto. + + 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 + mysqladmin create matita + (matita is the default database name, you can + change it using the db.user key of the + configuration file). + + Then you need to grant the necessary access permissions to the + database user of &appname;, typing echo "grant all privileges + on matita.* to helm;" | mysql matita should do the trick + (helm is the default user name used by &appname; to + access the database, you can change it using the + db.user key of the configuration file). + + + + This way you create a database named matita + on which anyone claiming to be the helm 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. + + + + + + Compiling and installing + + Once you get the source code the installations steps should be + quite familiar. + + First of all you need to configure the build process executing + ./configure. This will check that all needed + tools and library are installed and prepare the sources for compilation + and installation. + + Quite a few (optional) arguments may be passed to the + configure command line to change build time + parameters. They are listed below, together with their + default values: + + + <application>configure</application> command line + arguments + + + + --with-runtime-dir=dir + + + + (Default: + /usr/local/matita) Runtime base directory + where all &appname; stuff (executables, configuration files, + standard library, ...) will be installed + + + + + + + --with-dbhost=host + + + + (Default: 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. + + + + + + + --enable-debug + + + + (Default: disabled) Enable debugging code. + Not for the casual user. + + + + + + Then you will manage the build and install process using + make + as usual. Below are reported the targets you have to invoke in sequence + to build and install: + + + + <application>make</application> targets + + + world + + builds components needed by &appname; and &appname; itself + (in bytecode or native code depending + on the availability of the OCaml native code compiler) + + + + + install + + installs &appname; related tools, standard library and the + needed runtime stuff in the proper places on the filesystem. + + As a part of the installation process the &appname; + standard library will be compiled, thus testing that the just + built matitac compiler works + properly. + For this step you will need a working SQL database (for + indexing the standard library while you are compiling it). See + Database setup + for instructions on how to set it up. + + + + + + + + + + + + Configuring &appname; + + The configuration file is divided in four sections. The user and + matita ones are self explicative and does not need user + intervention. Here we report a sample snippet for these two + sections. The remaining db and getter sections will be explained in + details later. + + + $(HOME) + $(USER) + +
+ $(user.home)/.matita + /usr/share/matita/ + $(user.name) +
+]]> + + + &appname; needs to store/fetch data and metadata. Data is essentially + composed of XML files, metadata is a set of tuples for a relational + model. Data and metadata can produced by the user or be already + available. Both kind of data/metadata can be local and/or remote. + + + The db section tells &appname; where to store and retrieve metadata, + while the getter section describes where XML files have to be + found. The following picture describes the suggested configuration. + Dashed arrows are determined by the configuration file. + +
Configuring the Databases + + + + + How to configure the databases. + +
+ The getter + + Consider the following snippet and the URI + cic:/matita/foo/bar.con. If &appname; + is asked to read that object it will resolve the object trough + the getter. Since the first two entries are equally specific + (longest match rule applies) first the path + file://$(matita.rt_base_dir)/xml/standard-library/foo/bar.con + and then file://$(user.home)/.matita/xml/matita/foo/bar.con + are inspected. + + + $(user.home)/.matita/getter/cache + + cic:/matita/ + file://$(matita.rt_base_dir)/xml/standard-library/ + ro + + + cic:/matita/ + file://$(user.home)/.matita/xml/matita/ + + + cic:/Coq/ + http://mowgli.cs.unibo.it/xml/ + legacy + + +]]> + + if the same URI has to be written, the former prefix is skipped + since it is marked as readonly (ro). + Objects resolved using the third prefix are readonly too, and are + retrieved using the network. There is no limit to the number of + prefixes the user can define. The distinction between prefixes marked + as readonly and legacy is that, legacy ones are really read only, while + the ones marked with ro are considered for + writing when &appname; is started in system mode (used to publish user + developments in the library space). + + The db + + The database subsystem has three fron ends: library, user and + legacy. The latter is the only optional one. Every query is done on + every frontend, making the duplicate free union of the results. + The user front end kepps metadata produced by the user, and is thus + heavily accessed in read/write mode, while the library and legacy + fron ends are read only. Every front end can be connected to + backend, the storage actually. + Consider the following snippet. + + + mysql://mowgli.cs.unibo.it matita helm none legacy + file://$(matita.rt_base_dir) metadata.db helm helm library + file://$(matita.basedir) user.db helm helm user + +]]> + + Here the usr database is a file (thus locally accessed trough the + Sqlite library) placed in the user's home directory. The library one is + placed in the &appname; runtime directory. The legacy fron end is + connected to a remote &MYSQL; based storage. Every metadata key + takes a path to the storage, the name of the database, the user name, + a password (or none) and the name of the front + end to which it is attached. + + + + +