Action (b0.B0_unit.Action)

type b0_unit := t

Environment

type env = [

| `Build_env
(*
The build environment.
*)
| `Driver_env
(*
The b0 invocation process environment.
*)
| `Override of [ `Build_env | `Driver_env ] * B0_std.Os.Env.t
(*
Environment overriden by given values.
*)
| `Env of B0_std.Os.Env.t
(*
This exact environment.
*)
| `Fun of string * (B0_env.t -> b0_unit -> (B0_std.Os.Env.t, string) Stdlib.result)
(*
Doc string and function.
*)

]

The type for action execution environments.

val env : env B0_meta.key

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

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

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

Cwd

type cwd = [

| `Cwd
(*
The user's current working directory.
*)
| `Root_dir
(*
The root b0 file directory.
*)
| `Scope_dir
(*
The directory of the scope where the entity is defined.
*)
| `Unit_dir
(*
The unit's build directory.
*)
| `In of [ `Cwd | `Unit_dir | `Root_dir | `Scope_dir ] * B0_std.Fpath.t
| `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.

val cwd : cwd B0_meta.key

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

val get_cwd : B0_env.t -> b0_unit -> (B0_std.Fpath.t, string) Stdlib.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.

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

The type for action functions. See runs.

type t = [

| `Unit_exe
(*
The unit's exe_file
*)
| `Fun of string * func
(*
A doc string an a function.
*)

]

The type for specifying actions.

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

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

val scope_exec : 
  ?env:B0_std.Os.Env.assignments ->
  ?cwd:B0_std.Fpath.t ->
  B0_std.Cmd.t ->
  func

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")

val 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 ?

val key : t B0_meta.key

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

val units : b0_unit list B0_meta.key

units units that need to be built for the action.

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

dyn_units is a hack.

val packs : B0_pack.t list B0_meta.key

packs are packs thatneed to be built for the action.

val store : B0_store.binding list B0_meta.key

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.

val run : 
  ?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.Cmd.status, string) Stdlib.result

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.

val 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) Stdlib.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.