1META(5)                       File Formats Manual                      META(5)
2
3
4

NAME

6       META - [File that specifies metainformation of OCaml packages]
7

GRAMMAR

9                metafile ::= entry*
10                   entry ::= assignment | addition | subpackage
11              subpackage ::= "package" pkgname '(' metafile ')'
12              assignment ::= variable_name [ formal_predicates ] '='  value
13                addition ::= variable_name [ formal_predicates ] '+=' value
14       formal_predicates ::= '(' formal_predicate { ',' formal_predicate } ')'
15           variable_name ::= name
16        formal_predicate ::= name | '-' name
17                    name ::= [ 'A'-'Z' 'a'-'z' '0'-'9' '_' '.' ]+
18                 pkgname ::= '"' (character but not '.')* '"'
19                   value ::= '"' character* '"'
20

DESCRIPTION

22       If a package directory contains a file with the fixed name "META" it is
23       interpreted as described here. The file is a sequence of  entries  fol‐
24       lowing  the  given grammar; every entry defines a variable under a cer‐
25       tain condition given by the list of formal predicates, or it introduces
26       a subpackage.
27
28       There  is  a list of predefined variables and a list of standard predi‐
29       cates. These variables define: required packages, description,  version
30       information, directories, archive files, and linker options. The predi‐
31       cates denote circumstances of the application of the variables: whether
32       the bytecode or the native compiler is used, if there is a toploop com‐
33       piled in, details of multi-threading execution, details of profiling.
34

DETAILS OF THE FILE FORMAT

36       The file consists of a sequence of entries which must be formed as  the
37       grammar  prescribes.  The  lexical tokens are names, values, and inter‐
38       punctuation like '(', ',' and so on. Note that linefeeds do not play  a
39       special  role,  i.e.  an entry definition may be given in more than one
40       line, or several definitions may occur on a single line. There  may  be
41       comments which begin with '#' and run until the end of the line.
42
43       Names  are  sequences of the characters A-Z, a-z, 0-9, or _. Names con‐
44       taining capital letters and names beginning with digits are allowed but
45       not recommended.
46
47       Values are enclosed between double quotes. Values may contain any char‐
48       acter. The characters " and \ must be preceded by backslashes.
49
50       Package names must not contain the '.' character because it is used  as
51       delimiter of compound names.
52

MAIN PACKAGES AND SUBPACKAGES

54       The  outermost  variable  assignments  and additions belong to the main
55       package. The name of the main package is not defined within META; it is
56       either  the  name of the directory containing META or the suffix of the
57       META file (if the name of the META file is formed like META.name).
58
59       The keyword package starts the definition of a subpackage.  There  must
60       not be two such definitions with the same name. Within the parantheses,
61       the variable assignments and additions refer to the subpackage.  It  is
62       allowed that a subpackage contains further subpackages.
63
64       The  package  name  following package is the local name relative to the
65       main package, i.e. the name of the main package is  not  mentioned.  At
66       all  other places, however, the subpackage must be prefixed by the name
67       of the containing package, separated by a '.'.
68
69       Subpackages are independent of the containing package, except that  the
70       subpackage  points to the same installation directory as the containing
71       package (i.e. the location of the installation directory  is  inherited
72       from the containing package).
73

SEMANTICS OF VARIABLE DEFINITIONS

75       In  order  to  determine the value of a variable, first all assignments
76       are inspected, and the most specific assignment is taken (if  there  is
77       none,  the  empty string will be taken as value). In a second step, all
78       additions are gone through one after the other in the order they  occur
79       in  the  file, and the values of all matching additions are appended to
80       the current value. In the following,  it  is  further  clarified  which
81       assignment  is  the  most specific, which additions actually match, and
82       how the details of the value addition look like.
83
84       The most specific assignment is selected upon a set  of  actual  predi‐
85       cates,  i.e.  the  set  of  predicates that are assumed to be true. The
86       predicates occuring in the definitions of assignments and additions are
87       called  formal predicates. They may be positive or negative; the latter
88       are prepended by a '-' sign. In order to determine the value after  the
89       evaluation of the assignments, the following rules apply:
90
91           ·  An assignment can only be used if all positive formal predicates
92              are included in the set of actual predicates, and if  all  nega‐
93              tive  formal  predicates  are  not included in the set of actual
94              predicates. Such an assignment is called applicable. If there is
95              no such assignment, the variable will have no value.
96
97           ·  If  there is more than one applicable assignment, the definition
98              with the biggest number of formal predicates is selected.
99
100           ·  If there is still more  than  one  applicable  assignment,  both
101              applicable   and with a maximum number of formal predicates, the
102              definition that is defined first is selected.
103
104       An addition  is  matching  when  all  positive  formal  predicates  are
105       included in the set of actual predicates, and all negative formal pred‐
106       icates are not included.
107
108       The value of an addition is appended to the current value with implicit
109       white space as separator.
110

VARIABLES

112       There is a set of variables with predefined meaning:
113
114           ·  The  variable  "directory" redefines the location of the package
115              directory. Normally, the META file is the first file read in the
116              package  directory,  and  before  any  other  file  is read, the
117              "directory" variable is evaluated in order to see if the package
118              directory must be changed. The value of the "directory" variable
119              is determined with an empty set of actual predicates. The  value
120              must  be  either:  an absolute path name of the alternate direc‐
121              tory, or a path name relative to the stdlib directory  of  OCaml
122              (written  "+path"), or a normal relative path name (without spe‐
123              cial syntax). In the latter case, the interpretation depends  on
124              whether  it  is  contained in a main or sub package, and whether
125              the standard repository layout or the  alternate  layout  is  in
126              effect  (see  site-lib  for  these terms). For a main package in
127              standard layout the base directory is the  directory  physically
128              containing  the  META file, and the relative path is interpreted
129              for this base directory. For a main package in alternate  layout
130              the  base  directory  is the directory physically containing the
131              META.pkg files. The base directory for subpackages is the  pack‐
132              age  directory  of  the  containing package. (In the case that a
133              subpackage definition does not have a "directory"  setting,  the
134              subpackage simply inherits the package directory of the contain‐
135              ing package. By writing a "directory" directive one  can  change
136              this location again.)
137
138           ·  The variable "requires" specifies the list of required packages.
139              The names of the packages  must  be  separated  by  white  space
140              and/or commas. The names must be fully qualified (i.e. when they
141              refer to a subpackage, the names of all containing packages must
142              be prepended, separated by '.').
143
144           ·  The  variable  "description"  may include a short description of
145              the package (displayed by ocamlfind list).
146
147           ·  The variable "version" specifies the version string.
148
149           ·  The variable "archive" specifies  the  list  of  archive  files.
150              These  files  should  be given either as (1) plain names without
151              any directory information; they are only searched in the package
152              directory.  (2)  Or they have the form "+path" in which case the
153              files are looked up relative to the  standard  library.  (3)  Or
154              they  have  the  form  "@name/file"  in which case the files are
155              looked up in the package directory of another  package.  (4)  Or
156              they are given as absolute paths.
157
158              The  names  of the files must be separated by white space and/or
159              commas. In the preprocessor stage, the archive files are  passed
160              as  extensions  to the preprocessor (camlp4) call. In the linker
161              stage (-linkpkg), the archive files are linked. In the  compiler
162              stage, the archive files are ignored.
163
164              Note  that  "archive" should only be used for archive files that
165              are intended to  be  included  in  executables  or  loaded  into
166              toploops.  For  modules  loaded at runtime there is the separate
167              variable "plugin".
168
169           ·  The variable "plugin" specifies the plugin archives of the pack‐
170              age. These can be dynamically loaded with the Fl_dynload module.
171              The plugin archives can have ".cmo", ".cma", or ".cmxs" suffix.
172
173           ·  The variable "linkopts" specifies additional linker options.
174
175           ·  The variable "error" can be used  to  signal  error  conditions.
176              When  this  variable  is  applicable,  the  ocaml  compilers are
177              stopped, and an error message is printed.  The  message  is  the
178              value of the variable.
179
180           ·  The variable "warning" can be used to signal warnings. When this
181              variable is applicable, the warning is printed, but the compila‐
182              tion continues. The message is the value of the variable.
183
184           ·  The variable "exists_if" can be used to disable subpackages. The
185              value of "exists_if" is a file; the subpackage is hidden if this
186              file  does  not exist. You can also enumerate several files, and
187              the subpackage is hidden if none of the files exist.
188
189           ·  The variable "ppx" is a command that is added  to  the  compiler
190              invocation  via the -ppx option (available since OCaml-4.01). If
191              the command is relative to the current directory  (e.g.  ./cmd),
192              the  command  is  expected in the package directory. The special
193              forms as defined for "archive" are also  available  (e.g.  @oth‐
194              erpkg/cmd).   Additional  arguments  can  be  specified  on  the
195              ocamlfind command line with the -ppxopt option or  the  "ppxopt"
196              variable.
197
198           ·  The  variable "ppxopt" is a set of options that are added to the
199              ppx rewriter invocation. The contents of the  variable  consists
200              of  one  or  several whitespace-separated parts. Every part con‐
201              sists of several comma-separated  subparts;  the  first  subpart
202              indicates the package that contains the ppx rewriter invocation,
203              the rest contain the options to be appended. If the option is  a
204              path  relative  to  the  current directory (e.g. ./foo.cma), the
205              path is expanded relative to the package directory. The  special
206              forms  as  defined  for "archive" are also available (e.g. @oth‐
207              erpkg/foo.cma).
208
209       It is possible to define additional variables but there is currently no
210       software interpreting them.
211

PREDICATES

213       There is a list of standard predicates:
214
215           ·  The "byte" predicate means that the bytecode compiler is used.
216
217           ·  The "native" predicate means that the native compiler is used.
218
219           ·  The  "toploop"  predicate means that the toploop is available in
220              the linked program. It is only set when the toploop is  running,
221              not when the toploop is generated.
222
223           ·  The  "create_toploop"  predicate means that a toploop is created
224              (using ocamlmktop).
225
226           ·  The "mt" predicate means that the program is multi-threaded.
227
228           ·  The "mt_posix" predicate means that in the  case  "mt"  is  set,
229              too, the POSIX libraries are used to implement threads.
230
231           ·  The  "mt_vm"  predicate means that in the case "mt" is set, too,
232              the VM-based libraries are used to implement threads.
233
234           ·  The "gprof" predicate means that in the case  "native"  is  set,
235              too, the program is compiled for profiling
236
237           ·  The  "autolink"  predicate  means  that  ocamlc can/will perform
238              automatic linking.
239
240           ·  The "preprocessor" predicate means that the META  variables  are
241              scanned for preprocessor options.
242
243           ·  The  "syntax" predicate means that the -syntax option is present
244              on the command line.
245
246           ·  Legacy: The "plugin" predicate could be used in some versions of
247              findlib  to  select cmxs archives instead of cmxa archives. This
248              use is still possible but discouraged.
249
250       In addition to these predicates, there are package predicates for every
251       package  that  is  finally  selected. Of course, this kind of predicate
252       must not be used to select "directory" and  "requires"  variables,  but
253       for  the  other  variables they are perfectly valid. The package predi‐
254       cates have the form "pkg_" plus the name of the package  (fully  quali‐
255       fied).
256
257
258
259User Manual          The findlib package manager for OCaml             META(5)
Impressum