META(5)

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" itis interpreted as described here. The file is a sequence of entriesfollowing the given grammar; every entry defines a variable under acertain condition given by the list of formal predicates, or itintroduces a subpackage.

There is a list of predefined variables and a list of standardpredicates. These variables define: required packages, description, versioninformation, directories, archive files, and linker options. Thepredicates denote circumstances of the application of the variables:whether the bytecode or the native compiler is used, if there is atoploop compiled in, details of multi-threading execution, details ofprofiling.

DETAILS OF THE FILE FORMAT
The file consists of a sequence of entries which must be formed as thegrammar prescribes. The lexical tokens are names, values, andinterpunctuation like '(', ',' and so on. Note that linefeeds do notplay a special role, i.e. an entry definition may be given in more thanone line, or several definitions may occur on a single line. There maybe 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 _. Namescontaining capital letters and names beginning with digits areallowed but not recommended.

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

Package names must not contain the '.' character because it is usedas delimiter of compound names.

MAIN PACKAGES AND SUBPACKAGES
The outermost variable assignments and additions belong to the mainpackage. The name of the main package is not defined within META;it is either the name of the directory containing META or the suffixof the META file (if the name of the META file is formed likeMETA.name).

The keyword packagestarts the definitionof a subpackage. There must not be two such definitions with thesame name. Within the parantheses, the variable assignments andadditions refer to the subpackage. It is allowed that a subpackagecontains further subpackages.

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

Subpackages are independent of the containing package, exceptthat the subpackage points to the same installation directory asthe containing package (i.e. the location of the installation directoryis inherited from the containing package).

SEMANTICS OF VARIABLE DEFINITIONS
In order to determine the value of a variable, first all assignmentsare inspected, and the most specific assignment is taken (if there isnone, the empty string will be taken as value). In a second step,all additions are gone through one after the other in the orderthey occur in the file, and the values of all matching additions areappended to the current value. In the following, it is furtherclarified which assignment is the most specific, which additionsactually match, and how the details of the value addition look like.

The most specific assignment is selected upon a set of actualpredicates, i.e. the set of predicates that are assumed to be true.The predicates occuring in the definitions of assignments andadditions are called formal predicates. They may be positive ornegative; the latter are prepended by a '-' sign. In order todetermine the value after the evaluation of the assignments, thefollowing rules apply:

    • An assignment can only be used if all positive formalpredicates are included in the set of actual predicates, and if allnegative formal predicates are not included in the set of actualpredicates. Such an assignment is calledapplicable. If there is no such assignment, thevariable will have no value.

    • If there is more than one applicable assignment, the definition withthe 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 definedfirst is selected.

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

The value of an addition is appended to the current value withimplicit white space as separator.

VARIABLES
There is a set of variables with predefined meaning:

    • Thevariable "directory" redefines the location of the packagedirectory. Normally, the META file is the first file read in thepackage directory, and before any other file is read, the "directory"variable is evaluated in order to see if the package directory must bechanged. The value of the "directory" variable is determined with anempty set of actual predicates. The value must be either: an absolutepath name of the alternate directory, or a path name relative to thestdlib directory of OCaml (written "+path"), or a normal relative pathname (without special syntax). In the latter case, the interpretationdepends on whether it is contained in a main or sub package, andwhether the standard repository layout or the alternate layout is ineffect (see site-libfor these terms).For a main package in standard layout the base directory is thedirectory physically containing the META file, and the relative pathis interpreted for this base directory. For a main package inalternate layout the base directory is the directory physicallycontaining the META.pkg files. The base directory for subpackages isthe package directory of the containing package. (In the casethat a subpackage definition does not have a "directory" setting,the subpackage simply inherits the package directory of the containingpackage. By writing a "directory" directive one can change thislocation again.)

    • The variable "requires" specifies the list of required packages. Thenames 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 thepackage (displayed by ocamlfind list).

    • The variable "version" specifies the version string.

    • The variable "archive" specifies the list of archive files. Thesefiles should be given either as (1) plain names without any directoryinformation; they are only searched in the package directory.(2) Or they have the form "+path" in which case the files are looked uprelative to the standard library. (3) Or they have the form "@name/file"in which case the files are looked up in the package directoryof another package. (4) Or they are given as absolute paths.

    Thenames of the files must be separated by white space and/or commas.In the preprocessor stage, the archive files are passed as extensionsto the preprocessor (camlp4) call. In the linker stage (-linkpkg), the archivefiles are linked. In the compiler stage, the archive files are ignored.

    Note that "archive" should only be used for archive files that areintended to be included in executables or loaded into toploops. Formodules 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_dynloadmodule. 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. Whenthis variable is applicable, the ocaml compilers are stopped, andan error message is printed. The message is the value of the variable.

    • The variable "warning" can be used to signal warnings. Whenthis variable is applicable, the warning is printed, but thecompilation continues. The message is the value of the variable.

    • The variable "exists_if" can be used to disable subpackages. Thevalue of "exists_if" is a file; the subpackage is hidden if thisfile does not exist. You can also enumerate several files, and thesubpackage is hidden if none of the files exist.

    • The variable "ppx" is a command that is added to the compiler invocationvia the -ppx option (available since OCaml-4.01). If the command isrelative to the current directory (e.g. ./cmd), the command is expectedin the package directory. The special forms as defined for "archive"are also available (e.g. @otherpkg/cmd). Additional arguments can bespecified on the ocamlfind command line with the -ppxopt optionor the "ppxopt" variable.

    • The variable "ppxopt" is a set of options that are added to the ppxrewriter invocation. The contents of the variable consists of one orseveral whitespace-separated parts. Every part consists of severalcomma-separated subparts; the first subpart indicates the packagethat contains the ppx rewriter invocation, the rest contain the optionsto 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 currentlyno 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 thelinked program. It is only set when the toploop is running, not whenthe toploop is generated.

    • The "create_toploop" predicate means that a toploop is created (usingocamlmktop).

    • The "mt" predicate means that the program is multi-threaded.

    • The "mt_posix" predicate means that in the case "mt" is set, too, thePOSIX libraries are used to implement threads.

    • The "mt_vm" predicate means that in the case "mt" is set, too, theVM-based libraries are used to implement threads.

    • The "gprof" predicate means that in the case "native" is set, too, theprogram 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 forpreprocessor options.

    • The "syntax" predicate means that the -syntax option is present on thecommand line.

    • Legacy: The "plugin" predicate could be used in some versions of findlibto select cmxs archives instead of cmxa archives. This use is still possiblebut discouraged.

In addition to these predicates, there are package predicatesfor every package that is finally selected. Of course, this kind ofpredicate 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 thepackage (fully qualified).