package b0

  1. Overview
  2. Docs
Software construction and deployment kit

Install 

dune-project
 Dependency

erratique.ch Readme Changelog ISC; BSD-2-Clause License Edit opam file Versions (2)

Authors

  1. T
    The b0 programmers

Maintainers

  1. Daniel Bünzli

Sources

b0-0.0.6.tbz
sha512=e9aa779e66c08fc763019f16d4706f465d16c05d6400b58fbd0313317ef33ddea51952e2b058db28e65f7ddb7012f328c8bf02d8f1da17bb543348541a2587f0

doc/b0.file/B0_unit/Action/index.html

Module B0_unit.ActionSource

Actions.

Actions allow to operate on build outcomes as is done for example by the b0 or b0 test commands. See Running to see how they are run.

Sourcetype b0_unit := t

Environment

Sourcetype env = [
  1. | `Build_env
    (*

    The build environment.

    *)
  2. | `Driver_env
    (*

    The b0 invocation process environment.

    *)
  3. | `Override of [ `Build_env | `Driver_env ] * B0_std.Os.Env.t
    (*

    Environment overriden by given values.

    *)
  4. | `Env of B0_std.Os.Env.t
    (*

    This exact environment.

    *)
  5. | `Fun of string * (B0_env.t -> b0_unit -> (B0_std.Os.Env.t, string) result)
    (*

    Doc string and function.

    *)
]

The type for action execution environments.

env specifies the environement for executing a unit. If unspecified this is `Build_env.

Sourceval get_env : B0_env.t -> b0_unit -> (B0_std.Os.Env.t, string) result

get_env env u performs the logic to get the execution environment env for unit u in environment env.

Cwd

Sourcetype cwd = [
  1. | `Cwd
    (*

    The user's current working directory.

    *)
  2. | `Root_dir
    (*

    The root b0 file directory.

    *)
  3. | `Scope_dir
    (*

    The directory of the scope where the entity is defined.

    *)
  4. | `Unit_dir
    (*

    The unit's build directory.

    *)
  5. | `In of [ `Cwd | `Unit_dir | `Root_dir | `Scope_dir ] * B0_std.Fpath.t
  6. | `Fun of string * (B0_env.t -> b0_unit -> (B0_std.Fpath.t, string) B0_std.Result.t)
    (*

    Doc string and function.

    *)
]

The type for action execution working directories.

cwd specifies the current working directory for executing a unit. If unspecified this is `Cwd.

Sourceval get_cwd : B0_env.t -> b0_unit -> (B0_std.Fpath.t, string) result

get_cwd env u performs the logic to get the cwd cwd for unit u in environment env.

Action

Warning. Actions may be executed in parallel, either at the OS or OCaml level. Keep that in mind if you make funny things.

Sourcetype func = B0_env.t -> b0_unit -> args:B0_std.Cmd.t -> (B0_std.Os.Exit.t, string) result

The type for action functions. See runs.

Sourcetype t = [
  1. | `Unit_exe
    (*

    The unit's exe_file

    *)
  2. | `Fun of string * func
    (*

    A doc string an a function.

    *)
]

The type for specifying actions.

Sourceval func : ?doc:string -> func -> t

func ~doc f is `Fun (doc, f).

scope_exec env cmd executes cmd using the scope directory is used as the default cwd and to resolve the tool of cmd if it is relative. signature is twisted so that you can simply write:

  let myscript =
    B0_unit.of_action' "myscript" @@
    B0_unit.Action.scope_exec (Cmd.tool "scripts/myscript")
Sourceval of_cmdliner_term : ?man_xrefs:Cmdliner.Manpage.xref list -> ?man:Cmdliner.Manpage.block list -> ?envs:Cmdliner.Cmd.Env.info list -> ?exits:Cmdliner.Cmd.Exit.info list -> ?sdocs:string -> ?docs:string -> ?doc:string -> ?version:string -> (B0_env.t -> b0_unit -> B0_std.Os.Exit.t Cmdliner.Term.t) -> func

of_cmliner_term act env cmd t defines an that evaluating the cmdliner term t with arguments cmd. The menagerie of optional parameters define a Cmdliner.Term.info value for the term, see the docs there. By default doc is derived from the unit's doc string and exits is B0_std_cli.Exit.infos.

Metadata

These keys collectively define the behaviour of actions.

FIXME. Except for key do we really need that to be keys ?

key specifies the execution for a unit. If unspecified this is `Unit_exe.

Sourceval units : b0_unit list B0_meta.key

units units that need to be built for the action.

Sourceval dyn_units : (args:B0_std.Cmd.t -> b0_unit list) B0_meta.key

dyn_units is a hack.

Sourceval packs : B0_pack.t list B0_meta.key

packs are packs thatneed to be built for the action.

store are constraints on the build for the action to run.

Running

Note. This will need to be refined when we reintroduce cross compilation and build envrionement.

If the action results an executable to run either via `Unit_exe or Os.Exit.Execv, the process is spawn as follows:

  • The current working directory and environment are determined by get_cwd and get_env. However if Os.Exit.Execv specifies them those values are used instead.
  • If the executable in Os.Exit.Execv is an unresolved tool (has no path separator), it is looked up in the environment with B0_env.get_cmd. This means that if the tool is build by a unit part of the (must ?) build the built tool is picked up for execution (rather than in the environment PATH). To opt out of this behaviour the action should resolve the tool itself.

run env u ~args a runs the action a. If the action is an executable to run it is run with B0_std.Os.Cmd.run_status. env can be used to transform the environment just before execution.

Sourceval exit : ?env:(B0_std.Os.Env.t -> B0_std.Os.Env.t) -> B0_env.t -> b0_unit -> args:B0_std.Cmd.t -> t -> (B0_std.Os.Exit.t, string) result

exit is like run except that instead of using B0_std.Os.Cmd.run_status to run executables it returns them as an Os.Exit.Execv suitable to use with B0_std.Os.Exit.exit.