Provided by: ocaml-findlib_1.7.3-2_amd64 bug

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).