Read me for developers

How to use the FoCaLiZe Makefile

Cleaning

One target clean.

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/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. 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 focalize then in zvtov.

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 named .config_var.

From the "toplevel" directory focalize, variables variables are set to state

the various OCaml and Coq commands are set.
where to find the OCaml, Coq, zenon, that will be invoked by focalizec, i.e. by the built compiler.
where to install focalizec and its accompanying commands.
whether the installed Coq version is < 8.3pl2, in which case the building phase must invoke focalizec with the -coq_older option (idem later for the user when he will compile its own developments).
=> Generated the file .config_var.

The configure file 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 script if you have a non-standard installation of OCaml or Coq, if you want to use a special version of zenon or if you want to install FoCaLiZe in another directory, you must invoke the configure script with some of the following options:

[-]-install_prefix <directory>: set <directory> as the directory prefix for installation of the FoCaLize commands.(Default value for <directory> is /usr/local).
[-]-interactive: run interactively, asking questions.
[-]-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.
[-]-no-doc: do not generate the PDF documentation files.

Warnings and error: by default, the configure file 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 developer, if you're interesting in cleaning your code, you may manually edit the file .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 disappear by code cleaning (at least really harmful warnings).

The building phase

The building phase must compile zvtov, the FoCaLiZe compiler (focalizec) and its associated dependency checker (focalizedep). The necessary building sequence is as follows:

compile and install zvtov:
- make depend: compute dependencies for zvtov sources.
- make all: build binaries and libraries.
- make doc: build the doc.
- make install: install everything.
compile and install focalizec :
- make depend: compute dependencies for the compiler sources.
- make world: build build binaries and libraries. More detailed:
  - make byt bin: really build the binaries (bytecode and native versions).
  - make lib-depend: now that focalizedep is built by the previous stage, compute dependencies in the FoCaLize and OCaml sources of the library.
  - make lib: now that the dependencies are computed, build the stdlib, extlib and the contribs.
- make doc: build the doc (reference manual and tutorial).
- make install: install everything.

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 the server sosie.inria.fr)

git clone myname@sosie.inria.fr:/home/git/focalize.git

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

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:

$ROOT_DIR/focalizec/src/basement/configuration.ml (the version for FoCaLiZe is in this file).
$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:

edit the version files:
1. $ROOT_DIR/focalizec/doc_src/man/*.1 (change the version).
2. $ROOT_DIR/focalizec/doc_src/tex/refman/macros.tex (change the definitions \def\month{mm} \def\year{yy} \def\focalversion{\sf vv}).
3. $ROOT_DIR/focalizec/doc_src/tex/refman/macros.hva (change the definitions \def\month{mm} \def\year{yy} \def\focalversion{\sf vv}).
4. $ROOT_DIR/focalizec/doc_src/tex/tutorial/macros.tex (change the definitions \def\month{mm} \def\year{yy} \def\focalversion{\sf vv}).
5. $ROOT_DIR/doc_src/Includes/project.env (change the definition version_number_full).

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

Change everywhere focalize-old.version.number.tgz by focalize-new.version.number.tgz.

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.