Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
META(5)			      File Formats Manual		       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  fol-
       lowing  the  given grammar; every entry defines a variable under	a cer-
       tain 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	predi-
       cates. These variables define: required packages, description,  version
       information, directories, archive files,	and linker options. The	predi-
       cates denote circumstances of the application of	the variables: whether
       the bytecode or the native compiler is used, if there is	a toploop com-
       piled 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	inter-
       punctuation 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 con-
       taining capital letters and names beginning with	digits are allowed but
       not recommended.

       Values are enclosed between double quotes. Values may contain any char-
       acter. 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  as-
       signment	 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	predi-
       cates,  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:

	   o  An assignment can	only be	used if	all positive formal predicates
	      are included in the set of actual	predicates, and	if  all	 nega-
	      tive  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.

	   o  If  there	is more	than one applicable assignment,	the definition
	      with the biggest number of formal	predicates is selected.

	   o  If there is still	more than one applicable assignment, both  ap-
	      plicable	  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  in-
       cluded  in the set of actual predicates,	and all	negative formal	predi-
       cates 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:

	   o  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 "di-
	      rectory" 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	direc-
	      tory, or a path name relative to the stdlib directory  of	 OCaml
	      (written	"+path"), or a normal relative path name (without spe-
	      cial 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 ef-
	      fect (see	site-lib for these terms). For a main package in stan-
	      dard layout the base directory is	the directory physically  con-
	      taining  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	 pack-
	      age  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 contain-
	      ing package. By writing a	"directory" directive one  can	change
	      this location again.)

	   o  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 '.').

	   o  The  variable  "description"  may	include	a short	description of
	      the package (displayed by	ocamlfind list).

	   o  The variable "version" specifies the version string.

	   o  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".

	   o  The variable "plugin" specifies the plugin archives of the pack-
	      age. These can be	dynamically loaded with	the Fl_dynload module.
	      The plugin archives can have ".cmo", ".cma", or ".cmxs" suffix.

	   o  The variable "linkopts" specifies	additional linker options.

	   o  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.

	   o  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.

	   o  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.	 @oth-
	      erpkg/cmd).   Additional	arguments  can	be  specified  on  the
	      ocamlfind	command	line with the -ppxopt option or	 the  "ppxopt"
	      variable.

	   o  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 con-
	      sists of several comma-separated subparts; the first subpart in-
	      dicates  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. @oth-
	      erpkg/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:

	   o  The "byte" predicate means that the bytecode compiler is used.

	   o  The "native" predicate means that	the native compiler is used.

	   o  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.

	   o  The  "create_toploop"  predicate means that a toploop is created
	      (using ocamlmktop).

	   o  The "mt" predicate means that the	program	is multi-threaded.

	   o  The "mt_posix" predicate means that in the  case	"mt"  is  set,
	      too, the POSIX libraries are used	to implement threads.

	   o  The  "mt_vm"  predicate means that in the	case "mt" is set, too,
	      the VM-based libraries are used to implement threads.

	   o  The "gprof" predicate means that in the case  "native"  is  set,
	      too, the program is compiled for profiling

	   o  The  "autolink" predicate	means that ocamlc can/will perform au-
	      tomatic linking.

	   o  The "preprocessor" predicate means that the META	variables  are
	      scanned for preprocessor options.

	   o  The  "syntax" predicate means that the -syntax option is present
	      on the command line.

	   o  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	predi-
       cates have the form "pkg_" plus the name	of the package	(fully	quali-
       fied).

User Manual	     The findlib package manager for OCaml	       META(5)

NAME | GRAMMAR | DESCRIPTION | DETAILS OF THE FILE FORMAT | MAIN PACKAGES AND SUBPACKAGES | SEMANTICS OF VARIABLE DEFINITIONS | VARIABLES | PREDICATES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=META&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help