How to use the FoCaLiZe Makefile

Cleaning

One target clean.
  1. clean: applied from the "toplevel" directory focalize, cleans the tools, i.e. zenon, zvtov, focalizeXXX executables, libraries and contributions.
    When applied from a subdirectory (focalize/zenon, focalize/zvtov, focalize/focalizec, focalize/focalizec/src/stdlib ...), cleans the corresponding source files tree.

Making

From the the "toplevel" directory focalize, one targets "all" (got via make). The Makefile is in charge of running the configuration script, build and install for all the components of the FoCaLiZe package, i.e. zenon, zvtov and focalizec, including documentation.

The internals of configuration

Before the building phase can really start, each component of the FoCaLiZe package are configured, in addition to a "toplevel", general configuration. Configurations are performed by invocation of a configure in each relevant directory (i.e. focalize then zenon then zvtov and finally focalizec).

Two builtin and hand-written configuration files exist: Makefile.rules and Makefile.utils that are included in the Makefile.common file. This latter also includes the "toplevel" .config_var and is the common primitive configuration to include in further Makefiles. The file Makefile.rules contains the default rules make must apply to build targets from prerequisites. The file Makefile.utils contains the basic commands (cd, make, latex ...) used during the building phase. This latter should not be often modified since these commands are either available and have a well-established name, or simply not available.

The configure shell scripts perform various validity checks, commands searches then record all the configuration variables into files nammed .config_var.

Configure options

Each configure behaves by default (i.e. if invoked without option) without asking questions, guessing and setting things according what it finds and assumes (commands present in the paths, default installation directories).
To control the configure scripts if you have a non-standard installation of OCaml or Coq, if you want to use a special version of zenon or zvtov or if you want to install FoCaLiZe in another directory, you must invoke the configure scripts with some of the following options:
  1. focalize/configure:
    1. [-]-interactive: run interactively, asking questions.
    2. [-]-tools_prefix <directory>:  set <directory> as the directory prefix where tools required to build FoCaLiZe are installed. The currently required non-common tools are OCaml and Coq.
  2. focalize/zenon/configure:
    1. [-]-interactive: run interactively, asking questions.
    2. [-]-install_prefix <directory>: set <directory> as the directory prefix for installation of the FoCaLize commands. (Default value for <directory> is /usr/local).
  3. focalize/zvtov/configure: Same than for focalize/zenon/configure.
  4. focalize/focalizec/configure:
    1. [-]-interactive: run interactively, asking questions.
    2. [-]-install_prefix <directory>: set <directory> as the directory prefix for installation of the FoCaLize commands. (Default value for <directory> is /usr/local).
    3. [-]-tools_prefix <directory>: set <directory> as the directory prefix where tools required to build FoCaLiZe are installed. The currently required tools (other than OCaml and Coq already configured) are zenon, zvtov.
Warnings and error: by default, the "toplevel" configure generates a variable WARN_ERROR set to a. This variable controls the amount if warnings considered as errors when compiling OCaml code. It is set by default to "no warnings are error" (i.e. a) to ensure that when building by default, as a user, the FoCaLiZe stuff, compilation won't fail due to errors. As  a developper, if you're interesting in cleaning your code, you may manually edit the "toplevel" focalizec/.config_var and change the value of this variable to A. This way, all warnings will be considered as errors. On the long term, warnings should disapear by code cleaning (at least really harmful warnings).

The building phase

The building phase must compile the FoCaLiZe compiler (focalizec) and its associated dependency compiler (focalizedep). To achieve this goal, we MUST have the suitable zenon and zvtov in order to compile and certify the FoCaLiZe libraries. So, the necessary building sequence is as follows:

How to get the current branch for FoCaLiZe

# Go to the FoCaLiZe sources directory
cd ~/src/focalize

# Create a distribution sub directory to check out the distribution branch.
mkdir distribution
cd distribution

# Checkout a fresh distribution branch.
# (Change the name "myname" by your own login name on our CVS server
# modulogic.inria.fr)

cvs -d myname@modulogic.inria.fr:/home/cvs \
 co focalize

# Configure the FoCaLiZe, compile and install it
cd focalize
make

How to add a new directory to the FoCaLiZe hierarchy

Compilation from the focalize/focalizec directory is automatic in FoCaLiZe. The Makefile in this directory contains lists of sub-directories that are visited to perform the necessary tasks.

COMPILER_DIRS describes directories involved in the compiler itself.
LIB_DIRS describes directories involved the libraries.
DOC_DIRS describes directories involved the documentation.
ALL_DIRS is the union of all the previous.

#!/bin/sh

#**********************************************************************#
#                                                                      #
#                        FoCaLiZe compiler                             #
...


ROOT_DIR=..

include $(ROOT_DIR)/Makefile.common

COMPILER_DIRS=\
 src/basement src/parser src/typing\
 src/docgen src/commoncodegen src/mlcodegen src/coqcodegen\
 src/testing src/relation_extraction\
 src/toplevel src/focalizedep src/focalizetest src/focalizeig

LIB_DIRS=\
 src/stdlib src/extlib src/contribs

DOC_DIRS=\
 doc_src

ALL_DIRS=\
 $(COMPILER_DIRS) $(LIB_DIRS) $(DOC_DIRS)

...

You must add the new directory in the list(s) at its proper place in the list. Note also, that you must also add all the sub directories of the new directory if any.

You also must add the files names (full path from the root, including the $ROOT_DIR/ directory -- usually focalize/) to the list of files to include in a distribution if you intend to have your files belonging to the standard distribution of FoCaLize. Add files names to the file $ROOT_DIR/files-for-distrib.lst.

How to release

When a release is to be completed, and preferably before branching, you must consolidate the version number of every component of FoCaLiZe.

For the entire FoCaLiZe system, it means to edit and verify the following files:

  1. $ROOT_DIR/focalizec/src/basement/configuration.ml (the version for FoCaLiZe is in this file).
  2. $ROOT_DIR/zenon/versionnum.ml (the version for zenon is in this file).
  3. $ROOT_DIR/zvtov/version.ml (the version for zvtov is in this file).

The Release documentation has to be recompiled with the new version numbers. You need to:

Finally, the Makefile creating the distribution must be updated with the version number: focalize/Makefile. In the Makefile entry distrib:

The list of all the files to include in the distribution is $ROOT_DIR/files-for-distrib.lst.
Then, from $ROOT_DIR, invoke make distrib. The resulting archive will be located in $ROOT_DIR/focalize-current.version.number.tgz.