Module Topkg.Conf

module Conf: sig .. end
Build configuration.

Tool lookup

If your package description needs to run tools (e.g. in the pre and post build hooks, see it should get the tool to invoke with the following function. This allows to control the executable being run which is useful for cross-compilation scenarios.

type os = [ `Build_os | `Host_os ] 
The type for operating systems.
val tool : string -> os -> Topkg.Cmd.t
tool cmd os is a command cmd which can be run on the build OS which produces output suitable for the OS os.

The actual command returned depends on the following lookup procedure, here exemplified on the invocation tool "mytool" `Host_os (resp. `Build_os).

  1. Cmd.v "cmd", if the environment variable HOST_OS_MYTOOL (resp. BUILD_OS_MYTOOL) is set to "cmd"
  2. Cmd.v (Fpath.append path "mytool"), if the environment variable HOST_OS_XBIN (resp. BUILD_OS_BIN) is set to path.
  3. Cmd.v ("mytool" ^ "suff"), if the environment variable HOST_OS_SUFF (resp. BUILD_OS_SUFF).
  4. Cmd.(v "ocamlfind" % "mytool") if "mytool" is part of the OCaml tools that can be invoked through ocamlfind.
  5. Cmd.v "mytool" otherwise.

Key value converters

type 'a conv 
The type for key value converters.
val conv : ?docv:string ->
(string -> 'a Topkg.result) ->
(Format.formatter -> 'a -> unit) -> 'a conv
conv ~docv parse print is a configuration value converter parsing values with parse and printing them with print. docv is a documentation meta-variable used in the documentation to stand for the configuration value, defaults to "VALUE".
val bool : bool conv
bool is a converter for booleans.
val int : int conv
int is a converter for integers.
val string : string conv
string is a converter for strings.
val fpath : Topkg.fpath conv
fpath is a converter for file paths.
val some : ?none:string -> 'a conv -> 'a option conv
some conv is like conv but wraps the parsed value in Some. none is the string printed for None by the converter printer, defaults to "".


Warning. Configuration keys must be created before the call to Topkg.Pkg.describe. Yes you are right, that's a little bit dirty.

type 'a key 
The type for configuration keys whose lookup value is of type 'a.

A configuration key has a name and represents a value of type 'a in a build configuration. If "name" is the name of the key then its value can be specified on the command line using --name v where v is the value of the key and is parsed according to the key's value converter.

There are a few predefined key, see the configuration section.

val key : ?docv:string ->
?doc:string ->
?env:string -> string -> 'a conv -> absent:'a -> 'a key
key name conv ~absent ~env ~doc ~docv is a configuration key with name name parsed from the command line with conv. absent is used if the value is not specified on the command line. If env is specified and exists in the process environment, the value of the variable is parsed with conv and used instead of absent when needed.

doc is a documentation string for the key. docv is a meta is a documentation to stand for the key value, defaults to the docv of conv. In doc occurences of the substring "$(docv)" are replaced by the value of docv.

val discovered_key : ?docv:string ->
?doc:string ->
?env:string ->
string ->
'a conv -> absent:(unit -> 'a Topkg.result) -> 'a key
discovered_key is like Topkg.Conf.key but the absent value is discovered, if needed, with absent.
val with_pkg : ?default:bool -> string -> bool key
with_pkg ~default pkg is a boolean configuration key named (strf "with-%s" pkg) to assert existence of OPAM packages. If absent defaults to default.

Usually specified in OPAM build instructions with:

"--with-thatpkg" thatpkg:installed
along with an entry in the depopt field of the OPAM file.

Warning. Only use this combinator for denoting OPAM package existence, the resulting key may switch to a discovery process in the future.


type t 
The type for configurations.
val value : t -> 'a key -> 'a
value c k is the value of configuration key k in c.
Raises Invalid_argument If k was (illegaly) created after the call to Topkg.Pkg.describe or if dirty tricks are being played.
val pkg_name : t -> string
pkg_name c is either the value of the package name as given to Topkg.Pkg.describe or the value of a predefined key --pkg-name which overrides the package name. This defines the name of the generated OPAM install file. Used to handle multiple OPAM packages.
val build_dir : t -> Topkg.fpath
build_dir c is either the value of build directory as given to Topkg.Pkg.describe via or the value of a predefined key --build-dir which overrides the package definition.
val vcs : t -> bool
vcs c is the value of a predefined key --vcs. It is true if the package directory is VCS managed. Usually should not be specified manually: if absent it is determined automatically by using Topkg.Vcs.find and used to determine the Topkg.Conf.build_context.
val pinned : t -> bool
pinned c is the value of a predefined key --pinned. It is true if the build is initiated by an installer like OPAM and the package is pinned. If absent defaults to false. Usually specified in OPAM build instructions with:
"--pinned" pinned

type build_context = [ `Dev | `Distrib | `Pin ] 
The type for build contexts. See Topkg.Conf.build_context for semantics.
val build_context : t -> [ `Dev | `Distrib | `Pin ]
build_context c is the build context of c. This is derived from Topkg.Conf.vcs and Topkg.Conf.pinned as follows.
val build_tests : t -> bool
build_tests c is the value of a predefined key --tests that indicates if the tests should be built. If absent the value depends on the Topkg.Conf.build_context, it is true in the `Dev context and false in the other contexts.
val debug : t -> bool
debug c is the value of a predefined key --debug that indicates if the build should include debugging information in the build artefacts. If absent the value is true or the value of the environment variable TOPKG_CONF_DEBUG if specified.
val profile : t -> bool
profile c is the value of a predefined key --profile that indicates if the build artefacts include run-time profiling support. If absent the value is false or the value of the environment variable TOPKG_CONF_PROFILE if specified.
val dump : Format.formatter -> t -> unit
dump ppf c formats an unspecified representation of c on ppf.

OCaml configuration

module OCaml: sig .. end
OCaml configuration.