Module B0_action

Actions.

Actions are user defined custom procedures. They can involve a build or not.

They can be used to run build artefacts, test suites, script or generic software life-cycle procedures.

See the action manual for a short introduction.

type t

The type for actions.

type func = t -> B0_env.t -> args:B0_std.Cmd.t -> B0_std.Os.Exit.t

The type for action implementations.

A function that given the action, execution environment and command line arguments eventually specifies a way to exit.

val make : ?store:B0_store.binding list -> ?packs:B0_pack.t list -> ?units:B0_unit.t list -> ?dyn_units:(args:B0_std.Cmd.t -> B0_unit.t list) -> ?doc:string -> ?meta:B0_meta.t -> string -> func -> t

make name func is an action named name implemented with action function func. units and packs are units and packs that must be built to run the action. store are store bindings that must be enforced in the build.

val make' : ?store:B0_store.binding list -> ?packs:B0_pack.t list -> ?units:B0_unit.t list -> ?dyn_units:(args:B0_std.Cmd.t -> B0_unit.t list) -> ?doc:string -> ?meta:B0_meta.t -> string -> (t -> B0_env.t -> args:B0_std.Cmd.t -> (unit, string) Stdlib.result) -> t

make' is like make but with a function whose result is turned into an error code via exit_of_result.

val func : t -> func

func a is the action function.

val units : t -> B0_unit.t list

units a are the units that must build for running the action.

val dyn_units : t -> args:B0_std.Cmd.t -> B0_unit.t list

dyn_units a args are the dynamic units of the action.

FIXME. This is a temporary hack.

val packs : t -> B0_pack.t list

packs a are the packs that must build for running the action.

val store : t -> B0_store.binding list

store a are the store bindings to enforce on the build.

Shortcuts

val exit_of_result : (unit, string) Stdlib.result -> B0_std.Os.Exit.t

exit_of_result v exits with B0_cli.Exit.ok if v is Ok () and logs the Error and exits with B0_cli.Exit.some_error if v is Error _.

val exit_of_result' : (B0_std.Os.Exit.t, string) Stdlib.result -> B0_std.Os.Exit.t

exit_of_result' v exits with e if v is Ok e and logs the Error and exits with B0_cli.Exit.some_error if v is Error _.

Action functions for script execution

exec_file env file ~args executes file with arguments args. The scope directory is used as the default cwd and to resolve file if it is relative.

val exec_file' : ?env:B0_std.Os.Env.assignments -> ?cwd:B0_std.Fpath.t -> B0_std.Fpath.t -> func

exec_file' is exec_file twisted a bit differently so that if you don't need to tweak arguments or lookup the environment you can simply write:

let myscript =
  B0_action.make "myscript" @@
  B0_action.exec_file' ~/"scripts/myscript"

exec_tool tool e args executes the tool exe with arguments cmd The scope directory is used as the default cwd. exe is looked up using B0_std.Os.Cmd.get_tool, if that fails the error is logged and we exit we and exits with B0_cli.Exit.some_error.

Command line interaction

Use B0_cli to parse actions arguments and B0_cli.Exit for exit codes. Given a suitable Cmdliner term this function can be used to implement the action's command.

TODO Add a quick getopt interface.

val of_cmdliner_cmd : ?store:B0_store.binding list -> ?packs:B0_pack.t list -> ?units:B0_unit.t list -> ?dyn_units:(args:B0_std.Cmd.t -> B0_unit.t list) -> ?doc:string -> ?meta:B0_meta.t -> string -> (t -> B0_env.t -> B0_std.Os.Exit.t Cmdliner.Cmd.t) -> t

of_cli_cmd name cmd is like make is an action from the Cmdliner command cmd. See also eval_cmdliner_term.

Note. The command is under a thunk to avoid toplevel inits. This entails a bit of repetition for name and doc but you can access those of the action in the thunk to define the cmdliner command.

val eval_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 -> t -> B0_env.t -> B0_std.Os.Exit.t Cmdliner.Term.t -> args:B0_std.Cmd.t -> B0_std.Os.Exit.t

eval act env cmd t defines a action command by 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 action's doc string and exits is B0_cli.Exit.infos.

B0 definition API

include B0_def.S with type t := t
val mangle_basename : string -> string
val define : ?doc:string -> ?meta:B0_meta.t -> string -> B0_def.def
val def_kind : string
val def : t -> B0_def.def
val name : t -> string
val basename : t -> string
val doc : t -> string
val equal : t -> t -> bool
val compare : t -> t -> int
val meta : t -> B0_meta.t
val mem_meta : 'a B0_meta.key -> t -> bool
val has_tag : bool B0_meta.key -> t -> bool
val find_meta : 'a B0_meta.key -> t -> 'a option
val find_or_default_meta : 'a B0_meta.key -> t -> 'a
val get_meta : 'a B0_meta.key -> t -> ('a, string) Stdlib.result
val add : t -> unit
val fold : (t -> 'a -> 'a) -> 'a -> 'a
val list : unit -> t list
val find : string -> t option
val get : string -> t
val get_or_suggest : string -> (t, t list) Stdlib.result
val get_or_hint : string -> (t, string) Stdlib.result
val get_list_or_hint : all_if_empty:bool -> string list -> (t list, string) Stdlib.result
val scope_path : t -> string list
val in_root_scope : t -> bool
val in_current_scope : t -> bool
val scope_dir : t -> B0_std.Fpath.t option
val scope_dir' : t -> (B0_std.Fpath.t, string) Stdlib.result
val in_scope_dir : t -> B0_std.Fpath.t -> B0_std.Fpath.t option
val in_scope_dir' : t -> B0_std.Fpath.t -> (B0_std.Fpath.t, string) Stdlib.result
val pp_name_str : string B0_std.Fmt.t
val pp_name : t B0_std.Fmt.t
val pp_doc : t B0_std.Fmt.t
val pp_synopsis : t B0_std.Fmt.t
val pp : t B0_std.Fmt.t
module Set : sig ... end
module Map : sig ... end