META
NAME
META - [File that specifies metainformation of OCaml packages]\c
GRAMMAR
metafile ::= entry*\c
entry ::= assignment | addition | subpackage\c
subpackage ::= "package" pkgname '(' metafile ')'\c
assignment ::= variable_name [ formal_predicates ] '=' value\c
addition ::= variable_name [ formal_predicates ] '+=' value\c
formal_predicates ::= '(' formal_predicate { ',' formal_predicate } ')'\c
variable_name ::= name\c
formal_predicate ::= name | '-' name\c
name ::= [ 'A'-'Z' 'a'-'z' '0'-'9' '_' '.' ]+\c
pkgname ::= '"' (character but not '.')* '"'\c
value ::= '"' character* '"'\c
DESCRIPTION
If a package directory contains a file with the fixed name "META" it\c
is interpreted as described here. The file is a sequence of entries\c
following the given grammar; every entry defines a variable under a\c
certain condition given by the list of formal predicates, or it\c
introduces a subpackage.\c
There is a list of predefined variables and a list of standard\c
predicates. These variables define: required packages, description, version\c
information, directories, archive files, and linker options. The\c
predicates denote circumstances of the application of the variables:\c
whether the bytecode or the native compiler is used, if there is a\c
toploop compiled in, details of multi-threading execution, details of\c
profiling.
DETAILS OF THE FILE FORMAT
The file consists of a sequence of entries which must be formed as the\c
grammar prescribes. The lexical tokens are names, values, and\c
interpunctuation like '(', ',' and so on. Note that linefeeds do not\c
play a special role, i.e. an entry definition may be given in more than\c
one line, or several definitions may occur on a single line. There may\c
be comments which begin with '#' and run until the end of the line.\c
Names are sequences of the characters A-Z, a-z, 0-9, or _. Names\c
containing capital letters and names beginning with digits are\c
allowed but not recommended.\c
Values are enclosed between double quotes. Values may contain any\c
character. The characters " and must be preceded by backslashes.
Package names must not contain the '.' character because it is used\c
as delimiter of compound names.\c
MAIN PACKAGES AND SUBPACKAGES
The outermost variable assignments and additions belong to the main\c
package. The name of the main package is not defined within META;\c
it is either the name of the directory containing META or the suffix\c
of the META file (if the name of the META file is formed like\c
META.name).\c
The keyword
package\c
starts the definition\c
of a subpackage. There must not be two such definitions with the\c
same name. Within the parantheses, the variable assignments and\c
additions refer to the subpackage. It is allowed that a subpackage\c
contains further subpackages.\c
The package name following
package\c
is the local name relative to the main package, i.e. the\c
name of the main package is not mentioned. At all other places,\c
however, the subpackage must be prefixed by the name of the\c
containing package, separated by a '.'.\c
Subpackages are independent of the containing package, except\c
that the subpackage points to the same installation directory as\c
the containing package (i.e. the location of the installation directory\c
is inherited from the containing package).\c
SEMANTICS OF VARIABLE DEFINITIONS
In order to determine the value of a variable, first all assignments\c
are inspected, and the most specific assignment is taken (if there is\c
none, the empty string will be taken as value). In a second step,\c
all additions are gone through one after the other in the order\c
they occur in the file, and the values of all matching additions are\c
appended to the current value. In the following, it is further\c
clarified which assignment is the most specific, which additions\c
actually match, and how the details of the value addition look like.\c
The most specific assignment is selected upon a set of actual\c
predicates, i.e. the set of predicates that are assumed to be true.\c
The predicates occuring in the definitions of assignments and\c
additions are called formal predicates. They may be positive or\c
negative; the latter are prepended by a '-' sign. In order to\c
determine the value after the evaluation of the assignments, the\c
following rules apply:
\h'-3m'\z\h'3m'\c
An assignment can only be used if all positive formal\c
predicates are included in the set of actual predicates, and if all\c
negative formal predicates are not included in the set of actual\c
predicates. Such an assignment is called\c
applicable\c
. If there is no such assignment, the\c
variable will have no value.
\h'-3m'\z\h'3m'\c
If there is more than one applicable assignment, the definition with\c
the biggest number of formal predicates is selected.\c
\h'-3m'\z\h'3m'\c
If there is still more than one applicable assignment, both applicable
and with a maximum number of formal predicates, the definition that is defined\c
first is selected.\c
An addition is matching when all positive formal predicates are\c
included in the set of actual predicates, and all negative formal\c
predicates are not included.\c
The value of an addition is appended to the current value with\c
implicit white space as separator.\c
VARIABLES
There is a set of variables with predefined meaning:\c
\h'-3m'\z\h'3m'\c
The\c
variable "directory" redefines the location of the package\c
directory. Normally, the META file is the first file read in the\c
package directory, and before any other file is read, the "directory"\c
variable is evaluated in order to see if the package directory must be\c
changed. The value of the "directory" variable is determined with an\c
empty set of actual predicates. The value must be either: an absolute\c
path name of the alternate directory, or a path name relative to the\c
stdlib directory of OCaml (written "+path"), or a normal relative path\c
name (without special syntax). In the latter case, the interpretation\c
depends on whether it is contained in a main or sub package, and\c
whether the standard repository layout or the alternate layout is in\c
effect (see
site-lib\c
for these terms).\c
For a main package in standard layout the base directory is the\c
directory physically containing the META file, and the relative path\c
is interpreted for this base directory. For a main package in\c
alternate layout the base directory is the directory physically\c
containing the META.pkg files. The base directory for subpackages is\c
the package directory of the containing package. (In the case\c
that a subpackage definition does not have a "directory" setting,\c
the subpackage simply inherits the package directory of the containing\c
package. By writing a "directory" directive one can change this\c
location again.)\c
\h'-3m'\z\h'3m'\c
The variable "requires" specifies the list of required packages. The\c
names of the packages must be separated by white space and/or commas.\c
The names must be fully qualified (i.e. when they refer to a subpackage,\c
the names of all containing packages must be prepended, separated by\c
'.').\c
\h'-3m'\z\h'3m'\c
The variable "description" may include a short description of the\c
package (displayed by
ocamlfind list\c
).\c
\h'-3m'\z\h'3m'\c
The variable "version" specifies the version string.\c
\h'-3m'\z\h'3m'\c
The variable "archive" specifies the list of archive files. These\c
files should be given either as (1) plain names without any directory\c
information; they are only searched in the package directory.\c
(2) Or they have the form "+path" in which case the files are looked up\c
relative to the standard library. (3) Or they have the form "@name/file"\c
in which case the files are looked up in the package directory\c
of another package. (4) Or they are given as absolute paths.\c
The\c
names of the files must be separated by white space and/or commas.\c
In the preprocessor stage, the archive files are passed as extensions\c
to the preprocessor (camlp4) call. In the linker stage (-linkpkg), the archive\c
files are linked. In the compiler stage, the archive files are ignored.\c
\h'-3m'\z\h'3m'\c
The variable "linkopts" specifies additional linker options.\c
\h'-3m'\z\h'3m'\c
The variable "error" can be used to signal error conditions. When\c
this variable is applicable, the ocaml compilers are stopped, and\c
an error message is printed. The message is the value of the variable.\c
\h'-3m'\z\h'3m'\c
The variable "exists_if" can be used to disable subpackages. The\c
value of "exists_if" is a file; the subpackage is hidden if this\c
file does not exist. You can also enumerate several files, and the\c
subpackage is hidden if none of the files exist.\c
It is possible to define additional variables but there is currently\c
no software interpreting them.\c
PREDICATES
There is a list of standard predicates:\c
\h'-3m'\z\h'3m'\c
The "byte" predicate means that the bytecode compiler is used.\c
\h'-3m'\z\h'3m'\c
The "native" predicate means that the native compiler is used.\c
\h'-3m'\z\h'3m'\c
The "toploop" predicate means that the toploop is available in the\c
linked program. It is only set when the toploop is running, not when\c
the toploop is generated.\c
\h'-3m'\z\h'3m'\c
The "create_toploop" predicate means that a toploop is created (using\c
ocamlmktop).\c
\h'-3m'\z\h'3m'\c
The "mt" predicate means that the program is multi-threaded.\c
\h'-3m'\z\h'3m'\c
The "mt_posix" predicate means that in the case "mt" is set, too, the\c
POSIX libraries are used to implement threads.\c
\h'-3m'\z\h'3m'\c
The "mt_vm" predicate means that in the case "mt" is set, too, the\c
VM-based libraries are used to implement threads.\c
\h'-3m'\z\h'3m'\c
The "gprof" predicate means that in the case "native" is set, too, the\c
program is compiled for profiling\c
\h'-3m'\z\h'3m'\c
The "autolink" predicate means that ocamlc can/will perform automatic linking.\c
\h'-3m'\z\h'3m'\c
The "preprocessor" predicate means that the META variables are scanned for\c
preprocessor options.\c
\h'-3m'\z\h'3m'\c
The "syntax" predicate means that the -syntax option is present on the\c
command line.\c
In addition to these predicates, there are package predicates\c
for every package that is finally selected. Of course, this kind of\c
predicate must not be used to select "directory" and "requires"\c
variables, but for the other variables they are perfectly valid.\c
The package predicates have the form "pkg_" plus the name of the\c
package (fully qualified).\c
