META(5)

🎀 NAME 🎀

META — the file that holds all the metainformation for OCaml packages 💖 (yes bestie, this is META(5), the File Formats Manual page, and it's a whole vibe)

---

✨ GRAMMAR ✨

okay so here's the literal shape of the thing, no notes:

                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 🌸

So if a package directory has a file in it with the fixed name META, it gets read exactly like this page says. The file is just a sequence of entries following that grammar up there 👆 — and every entry either defines a variable under a certain condition (that condition being the list of formal predicates), or it introduces a subpackage. That's it, that's the whole thing 🦋

There's a list of predefined variables and a list of standard predicates. Those variables define: required packages, description, version information, directories, archive files, and linker options. And the predicates are the circumstances where the variables apply — like whether you're using the bytecode compiler or the native compiler, whether there's a toploop compiled in, the details of multi-threading execution, and the details of profiling. It's giving "conditional logic but make it declarative" 💅

---

🔍 DETAILS OF THE FILE FORMAT 🔍

The file is a sequence of entries, and they must be formed exactly how the grammar prescribes, fr fr. The lexical tokens are names, values, and interpunctuation like (, , and so on.

Not me about to tell you that linefeeds do not play a special role 👀 — so an entry definition can absolutely be spread over more than one line, and several definitions can chill on a single line. It doesn't care.

There can also 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 (they're allowed, they're just lowkey not the move).

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's used as the delimiter of compound names. That dot is booked and busy 🚫

---

👑 MAIN PACKAGES AND SUBPACKAGES 👑

The outermost variable assignments and additions belong to the main package. And plot twist — the name of the main package is not defined inside META. It's 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). Iconic, honestly.

The keyword package starts the definition of a subpackage. There must not be two such definitions with the same name. Inside the parentheses, the variable assignments and additions refer to the subpackage. And yes, it's allowed that a subpackage contains further subpackages — subpackages all the way down, nesting is the moment 🧚

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 there. At all other places, though, the subpackage must be prefixed by the name of the containing package, separated by a ..

Subpackages are independent of the containing package, except for one thing: 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). Inherited, like a family trait 💜

---

💅 SEMANTICS OF VARIABLE DEFINITIONS 💅

okay this is the part where it gets real, stay with me.

To figure out the value of a variable, first all the assignments get inspected, and the most specific assignment is taken (if there is none, the empty string will be taken as value). Then, in a second step, all the 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.

Below, it's 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 occurring 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. Space does the work, no cap 🫶

---

🌈 VARIABLES 🌈

There's a set of variables with predefined meaning, and here's the whole roster:

• 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 "warning" can be used to signal warnings. When this variable is applicable, the warning is printed, but the compilation continues. 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. (Build your own lore, bestie, nobody's reading it yet 😭)

---

and that's part 1, we are NOT done, stay tuned for more ✨

✨ PREDICATES ✨

okay bestie so there's a whole roster of standard predicates and they're basically vibe checks the build system runs before it decides what to do. here's the full lineup, no skips, no cuts 💅

• byte — this one means the bytecode compiler is being used. simple as that.
• native — this one means the native compiler is being used. slay.
• toploop — means the toploop is available in the linked program. ⚠️ careful tho: it's only set when the toploop is running, not when the toploop is being generated. two different moments, don't mix them up 🙈
• create_toploop — means a toploop is being created (via ocamlmktop). it's giving construction site energy 👷‍♀️
• mt — means the program is multi-threaded. threads!! 🧵
• mt_posix — this one only kicks in in the case mt is set, too, and it means the POSIX libraries are used to implement threads.
• mt_vm — same deal, only when mt is set, too, and it means the VM-based libraries are used to implement threads.
• gprof — only when native is set, too, this means the program is compiled for profiling. 📊
• autolink — means ocamlc can/will perform automatic linking. it does it itself, main character energy fr fr.
• preprocessor — means the META variables get scanned for preprocessor options. 👀
• syntax — means the -syntax option is present on the command line. periodt.
• Legacy: plugin — in some versions of findlib this could be used to select cmxs archives instead of cmxa archives. you can still use it like that, but it's discouraged — it's giving expired trend, we don't do that anymore bestie 💀

---

okay and there's more ✨

On top of all those, there are also package predicates for every single package that is finally selected. so like, every package that made the cut gets its own lil predicate.

⚠️ but listen: this kind of predicate must not be used to select the directory and requires variables. absolutely not, no cap. for the other variables though? perfectly valid, go off 🎀

The package predicates have the form pkg_ plus the name of the package (fully qualified). so package foo.bar → predicate pkg_foo.bar, iykyk 💖

---

and that's the whole page babes 🫶 this was the findlib package manager for OCaml's very own user manual, page META(5) — drink water, read your META files, and go be iconic 👑💜