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