Module B0.Tool

module Tool: sig .. end
Build tools.

Define command line tools used by the build.

In order to improve build reproduciblity B0 runs command line tools with minimal process environments. As such tools need to declare the environment variables they want to access. Only these variables are automatically passed to the tool, provided they are present in the build's environment.

The final environment given to a tool on a build spawn is the value of these variables in the build's environment, overriden by the variables specified during the spawn operation overriden by the build's forced environment.

WARNING. Windows users, do not add the .exe extension to tool names, this is handled transparently by the system for portability.

Environment variables

type env_vars = string list 
The type for lists of environment variable names.
val tmp_vars : env_vars
tmp_vars is ["TMPDIR"; "TEMP"; "TMP"].


type t 
The type for tools.
val v : ?internal:env_vars ->
?env_vars:env_vars -> string -> t
v ~internal ~env_vars name is a tool looked up in the build's search path as name. env_vars are the environment variables read from the build's environment and that affect the tool's outputs (defaults to []). internal are the environment variables that are read from the build's environment and that do not affect the tool's output (defaults to B0.Tool.tmp_vars).
Raises Invalid_argument if name contains B0.Fpath.dir_sep, use B0.Tool.of_file to specify tools as file paths.
val of_file : ?internal:env_vars ->
?env_vars:env_vars -> B0.Fpath.t -> t
of_file ~internal ~env_vars file is like B0.Tool.v but if file is:
val of_unit_file : B0.Unit.t ->
?internal:env_vars ->
?env_vars:env_vars -> B0.Fpath.t -> t
of_unit_file ~internal_env_vars ~env_vars file is like B0.Tool.of_file but the given relative file is located in the build directory of B0.Unit. Build spawns that need this tool automatically build the unit in `Build_os mode and make sure to add the tool to the read set of the spawn.

FIXME. This feels ad-hoc maybe better primitives are needed in Build.t and then B0.Tool.of_file can be used, this can then be hidden in a larger combinator.

Tool configuration keys

val key : ?loc:B0.Def.loc ->
?doc:string ->
?group:B0.Conf.Group.t ->
?internal:env_vars ->
?env_vars:env_vars ->
?tools:B0.Fpath.t list -> string -> t B0.Conf.key
key ~internal ~env_vars ~tools name is a command line tool and configuration key named name, and that can manifest itself as one of tools (defaults to [Fpath.v name]). The first match is taken, files are looked up like in B0.Tool.of_file and None is returned if none can be found. FIXME I guess it errors, also att opt_key that doesn't error.