1META(5) File Formats Manual META(5)
2
6 META - [File that specifies metainformation of OCaml packages]
7
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
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 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
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 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 Values are enclosed between double quotes. Values may contain any char‐
48 acter. The characters " and \ must be preceded by backslashes.
49 Package names must not contain the '.' character because it is used as
51 delimiter of compound names.
52
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 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 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 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
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 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 · 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 · If there is more than one applicable assignment, the definition
98 with the biggest number of formal predicates is selected.
99 · 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 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 The value of an addition is appended to the current value with implicit
109 white space as separator.
110
112 There is a set of variables with predefined meaning:
113 · 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 · 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 · The variable "description" may include a short description of
145 the package (displayed by ocamlfind list).
146 · The variable "version" specifies the version string.
148 · 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 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 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 · 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 · The variable "linkopts" specifies additional linker options.
174 · 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 · 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 · 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 · 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 · 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 It is possible to define additional variables but there is currently no
210 software interpreting them.
211
213 There is a list of standard predicates:
214 · The "byte" predicate means that the bytecode compiler is used.
216 · The "native" predicate means that the native compiler is used.
218 · 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 · The "create_toploop" predicate means that a toploop is created
224 (using ocamlmktop).
225 · The "mt" predicate means that the program is multi-threaded.
227 · The "mt_posix" predicate means that in the case "mt" is set,
229 too, the POSIX libraries are used to implement threads.
230 · The "mt_vm" predicate means that in the case "mt" is set, too,
232 the VM-based libraries are used to implement threads.
233 · The "gprof" predicate means that in the case "native" is set,
235 too, the program is compiled for profiling
236 · The "autolink" predicate means that ocamlc can/will perform
238 automatic linking.
239 · The "preprocessor" predicate means that the META variables are
241 scanned for preprocessor options.
242 · The "syntax" predicate means that the -syntax option is present
244 on the command line.
245 · 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 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).
256User Manual The findlib package manager for OCaml META(5)