Module B0.Env

module Env: sig .. end
Build environment.

The build environment controls build tool lookups and spawn processes environments.

Build aims

type build_aim = [ `Build_os | `Host_os ] 
The type for build aims. Whenever a build unit is built, its build outcome may be aimed at either the `Build_os or the `Host_os:

Most of the time the build OS coincides with the host OS. The build OS does however differ in cross-compiled builds. In this case tool lookup, process environments and configuration needs to be distinguished in case the build system is creating build outcomes to be used by the build system itself.

This happens for example if pre-processors or programs generating source files are built and used by the build itself. If these pre-processors also need to be used on the host OS this lead those units being built twice: once for the build OS and once for the host OS. Units can specify that they support only one mode of building, this is mainly used for programs that are built for the build but are not deployed to the host OS.

Tool lookups

type tool_lookup = B0.Fpath.t list -> B0.Fpath.t B0.result 
The type for tool lookups. Given a list of tool alternatives returns the exectuable of the first one which can be found in the environment.

The expected semantics is similar to a lookup made in a POSIX PATH environment variable. Notably if a given path has a B0.Fpath.dir_sep no search should occur and the path be returned as is. However this is left to the discretion of the entity that setups the environment.

If no tool can be found the function should return an intellligible error message that mentions the given tools and where exactly it was looked up.

val pp_tool_alts : B0.Fpath.t list B0.Fmt.t
pp_tool_alts can be used as a preamble for reporting failures to lookup tools e.g. R.error_msgf "%a: Not found in ..." pp_tool_alts tools.
val env_tool_lookup : ?sep:string -> ?var:string -> B0.OS.Env.t -> tool_lookup
env_tool_lookup ~sep ~var env is a tool lookup that gets the value of the var variable (defaults to PATH) in env and performs a POSIX PATH variable search. Directories in the search path are separated by sep (defaults to ";" if Sys.win32 is true and ":" otherwise).


type t 
The type for build environments.
val v : ?build_lookup:tool_lookup ->
?build_forced_env:B0.OS.Env.t ->
?build_env:B0.OS.Env.t ->
?host_lookup:tool_lookup ->
?host_forced_env:B0.OS.Env.t -> B0.OS.Env.t -> t
v ~build_lookup ~build_forced_env ~build_env ~host_lookup ~host_forced_env host_env is an environment with:
val env : t -> build_aim -> B0.OS.Env.t
env e aim is e's consulted process environment for tools runs which aim at producing artefacts for aim.
val forced_env : t -> build_aim -> B0.OS.Env.t
forced_env e aim is e's forced process environment for tools which aim at producing artefacts for aim.
val tool : t -> build_aim -> B0.Fpath.t list -> B0.Fpath.t B0.result
tool e aim tools is the first file executable which can be found among tools for spawns which aim at producing artefacts for aim.
Raises Invalid_argument if tools is empty.