META - [File that specifies metainformation of OCaml packages]c

         metafile ::= entry*c




            entry ::= assignment | addition | subpackagec




       subpackage ::= "package" pkgname '(' metafile ')'c




       assignment ::= variable_name [ formal_predicates ] '='  valuec




         addition ::= variable_name [ formal_predicates ] '+=' valuec




formal_predicates ::= '(' formal_predicate { ',' formal_predicate } ')'c




    variable_name ::= namec




 formal_predicate ::= name | '-' namec




             name ::= [ 'A'-'Z' 'a'-'z' '0'-'9' '_' '.' ]+c




          pkgname ::= '"' (character but not '.')* '"'c




            value ::= '"' character* '"'c

If a package directory contains a file with the fixed name "META" itc is interpreted as described here. The file is a sequence of entriesc following the given grammar; every entry defines a variable under ac certain condition given by the list of formal predicates, or itc introduces a subpackage.c

There is a list of predefined variables and a list of standardc predicates. These variables define: required packages, description, versionc information, directories, archive files, and linker options. Thec predicates denote circumstances of the application of the variables:c whether the bytecode or the native compiler is used, if there is ac toploop compiled in, details of multi-threading execution, details ofc profiling.

The file consists of a sequence of entries which must be formed as thec grammar prescribes. The lexical tokens are names, values, andc interpunctuation like '(', ',' and so on. Note that linefeeds do notc play a special role, i.e. an entry definition may be given in more thanc one line, or several definitions may occur on a single line. There mayc 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 _. Namesc containing capital letters and names beginning with digits arec allowed but not recommended.c

Values are enclosed between double quotes. Values may contain anyc character. The characters " and \ must be preceded by backslashes.

Package names must not contain the '.' character because it is usedc as delimiter of compound names.c

The outermost variable assignments and additions belong to the mainc 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 suffixc of the META file (if the name of the META file is formed likec META.name).c

The keyword packagec starts the definitionc of a subpackage. There must not be two such definitions with thec same name. Within the parantheses, the variable assignments andc additions refer to the subpackage. It is allowed that a subpackagec contains further subpackages.c

The package name following packagec is the local name relative to the main package, i.e. thec name of the main package is not mentioned. At all other places,c however, the subpackage must be prefixed by the name of thec containing package, separated by a '.'.c

Subpackages are independent of the containing package, exceptc that the subpackage points to the same installation directory asc the containing package (i.e. the location of the installation directoryc is inherited from the containing package).c

In order to determine the value of a variable, first all assignmentsc are inspected, and the most specific assignment is taken (if there isc 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 orderc they occur in the file, and the values of all matching additions arec appended to the current value. In the following, it is furtherc clarified which assignment is the most specific, which additionsc actually match, and how the details of the value addition look like.c

The most specific assignment is selected upon a set of actualc predicates, i.e. the set of predicates that are assumed to be true.c The predicates occuring in the definitions of assignments andc additions are called formal predicates. They may be positive orc negative; the latter are prepended by a '-' sign. In order toc determine the value after the evaluation of the assignments, thec following rules apply:

h'-3m'z•h'3m'c An assignment can only be used if all positive formalc predicates are included in the set of actual predicates, and if allc negative formal predicates are not included in the set of actualc predicates. Such an assignment is calledc applicablec . If there is no such assignment, thec variable will have no value. h'-3m'z•h'3m'c If there is more than one applicable assignment, the definition withc 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 definedc first is selected.c

An addition is matching when all positive formal predicates arec included in the set of actual predicates, and all negative formalc predicates are not included.c

The value of an addition is appended to the current value withc implicit white space as separator.c

There is a set of variables with predefined meaning:c

h'-3m'z•h'3m'c Thec variable "directory" redefines the location of the packagec directory. Normally, the META file is the first file read in thec package directory, and before any other file is read, the "directory"c variable is evaluated in order to see if the package directory must bec changed. The value of the "directory" variable is determined with anc empty set of actual predicates. The value must be either: an absolutec path name of the alternate directory, or a path name relative to thec stdlib directory of OCaml (written "+path"), or a normal relative pathc name (without special syntax). In the latter case, the interpretationc depends on whether it is contained in a main or sub package, andc whether the standard repository layout or the alternate layout is inc effect (see site-libc for these terms).c For a main package in standard layout the base directory is thec directory physically containing the META file, and the relative pathc is interpreted for this base directory. For a main package inc alternate layout the base directory is the directory physicallyc containing the META.pkg files. The base directory for subpackages isc the package directory of the containing package. (In the casec that a subpackage definition does not have a "directory" setting,c the subpackage simply inherits the package directory of the containingc package. By writing a "directory" directive one can change thisc location again.)c h'-3m'z•h'3m'c The variable "requires" specifies the list of required packages. Thec 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 byc '.').c h'-3m'z•h'3m'c The variable "description" may include a short description of thec package (displayed by ocamlfind listc ).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. Thesec files should be given either as (1) plain names without any directoryc information; they are only searched in the package directory.c (2) Or they have the form "+path" in which case the files are looked upc 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 directoryc of another package. (4) Or they are given as absolute paths.c

Thec names of the files must be separated by white space and/or commas.c In the preprocessor stage, the archive files are passed as extensionsc to the preprocessor (camlp4) call. In the linker stage (-linkpkg), the archivec 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. Whenc this variable is applicable, the ocaml compilers are stopped, andc 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. Thec value of "exists_if" is a file; the subpackage is hidden if thisc file does not exist. You can also enumerate several files, and thec subpackage is hidden if none of the files exist.c

It is possible to define additional variables but there is currentlyc no software interpreting them.c

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 thec linked program. It is only set when the toploop is running, not whenc the toploop is generated.c h'-3m'z•h'3m'c The "create_toploop" predicate means that a toploop is created (usingc 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, thec 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, thec 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, thec program is compiled for profilingc 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 forc preprocessor options.c h'-3m'z•h'3m'c The "syntax" predicate means that the -syntax option is present on thec command line.c

In addition to these predicates, there are package predicatesc for every package that is finally selected. Of course, this kind ofc 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 thec package (fully qualified).c