META(5)
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).
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
