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           ·  The variable "linkopts" specifies additional linker options.
165
166           ·  The  variable  "error"  can  be used to signal error conditions.
167              When this  variable  is  applicable,  the  ocaml  compilers  are
168              stopped,  and  an  error  message is printed. The message is the
169              value of the variable.
170
171           ·  The variable "exists_if" can be used to disable subpackages. The
172              value of "exists_if" is a file; the subpackage is hidden if this
173              file does not exist. You can also enumerate several  files,  and
174              the subpackage is hidden if none of the files exist.
175
176       It is possible to define additional variables but there is currently no
177       software interpreting them.
178

PREDICATES

180       There is a list of standard predicates:
181
182           ·  The "byte" predicate means that the bytecode compiler is used.
183
184           ·  The "native" predicate means that the native compiler is used.
185
186           ·  The "toploop" predicate means that the toploop is  available  in
187              the  linked program. It is only set when the toploop is running,
188              not when the toploop is generated.
189
190           ·  The "create_toploop" predicate means that a toploop  is  created
191              (using ocamlmktop).
192
193           ·  The "mt" predicate means that the program is multi-threaded.
194
195           ·  The  "mt_posix"  predicate  means  that in the case "mt" is set,
196              too, the POSIX libraries are used to implement threads.
197
198           ·  The "mt_vm" predicate means that in the case "mt" is  set,  too,
199              the VM-based libraries are used to implement threads.
200
201           ·  The  "gprof"  predicate  means that in the case "native" is set,
202              too, the program is compiled for profiling
203
204           ·  The "autolink" predicate  means  that  ocamlc  can/will  perform
205              automatic linking.
206
207           ·  The  "preprocessor"  predicate means that the META variables are
208              scanned for preprocessor options.
209
210           ·  The "syntax" predicate means that the -syntax option is  present
211              on the command line.
212
213       In addition to these predicates, there are package predicates for every
214       package that is finally selected. Of course,  this  kind  of  predicate
215       must  not  be  used to select "directory" and "requires" variables, but
216       for the other variables they are perfectly valid.  The  package  predi‐
217       cates  have  the form "pkg_" plus the name of the package (fully quali‐
218       fied).
219
220
221
222User Manual          The findlib package manager for OCaml             META(5)
Impressum