package b0

  1. Overview
  2. Docs
package b0
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module B0_unitSource

Build units.

A unit is a named build procedure and an optional action to perform once the unit has built. Units are the smallest unit of build in b0 files.

Either of the build procedure or the action can be a nop. Actions can also require a bit more than the unit itself from the build in order to run.

Build procedures

Sourcetype build_proc = B0_build.t -> unit B0_std.Fut.t

The type for unit build procedures. Note that when the future determines the build may not be finished.

Sourceval build_nop : build_proc

build_nop does nothing.

Units

Sourcetype t

The type for build units.

Sourceval make : ?doc:string -> ?meta:B0_meta.t -> string -> build_proc -> t

make n proc ~doc ~meta ~action is a build unit named n with build procedure proc, synopsis doc and metada meta.

Sourceval build_proc : t -> build_proc

proc u are the unit's build procedure.

Built executables

Sourceval tool_name : string B0_meta.key

tool_name is an executable name without the platform specific executable extension.

exe_file is an absolute file path to an executable build by the unit.

outcomes is the set of public file outcomes.

Sourceval copy_outcomes_to_dir : B0_memo.t -> t -> dst_dir:B0_std.Fpath.t -> unit

copy_outcomes m u ~dst_dir copies the outcome of u to destination directory dst_dir.

Sourceval is_public : t -> bool

is_public u is true iff u's meta has B0_meta.public set to true.

Sourceval get_or_suggest_tool : keep:(t -> bool) -> string -> (t list, t list) result

get_or_suggest_tool tool_name are tools names whose tool_name match tool_name and are filtered by keep

Sourceval tool_is_user_accessible : t -> bool

tool_is_user_accessible u assumes u has a tool name. This then returns true iff u is_public or in_root_scope.

Actions

Sourcemodule Action : sig ... end

Actions.

Sourceval is_actionable : t -> bool

actionable u is true if u has an action that can be run. This checks that either u has an exe_file or a `Fun action.

Making unit actions

These helper functions create units with a build_nop build procedure.

Sourceval of_action' : ?store:B0_store.binding list -> ?packs:B0_pack.t list -> ?units:t list -> ?dyn_units:(args:B0_std.Cmd.t -> t list) -> ?doc:string -> ?meta:B0_meta.t -> string -> Action.func -> t

of_action' 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.

Sourceval of_action : ?store:B0_store.binding list -> ?packs:B0_pack.t list -> ?units:t list -> ?dyn_units:(args:B0_std.Cmd.t -> t list) -> ?doc:string -> ?meta:B0_meta.t -> string -> (B0_env.t -> t -> args:B0_std.Cmd.t -> (unit, string) result) -> t

of_action is like of_action' but with a function func that evaluates to unit which are turned into Ok Os.Exit.ok.

Command line interaction

Use B0_std_cli to parse actions arguments and Os.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.

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

of_cmdliner_cmd name cmd is like of_action is an action from the Cmdliner command cmd. See also Action.of_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.

b0 definition API

include B0_def.S with type t := t with type Set.t = B0_defs.b0_unit_set

Named values

Sourceval mangle_basename : string -> string

mangle_basename s is a basename that can be used with define.

Sourceval define : ?doc:string -> ?meta:B0_meta.t -> string -> B0_def.def

define ~doc ~meta n defines name n in the current scope with documentation string doc (defaults to "undocumented")e and metadata meta (defaults to B0_meta.empty). Defining a duplicate value in a scope raises an exception.

Sourceval def_kind : string

def_kind is the kind of defined value.

Sourceval def : t -> B0_def.def

def v is the definition of value v.

Sourceval name : t -> string

name v is v's name. Note that this name changes depending on how the definition is scoped.

Sourceval basename : t -> string

basename v is v's name without the scope.

Sourceval doc : t -> string

doc v is v's documentation string.

Sourceval equal : t -> t -> bool

equal v0 v1 is true iff v0 and v1 have the same name.

Sourceval compare : t -> t -> int

compare v0 v1 sorts v0 and v0 in lexicographical order.

Metadata

Sourceval meta : t -> B0_meta.t

meta v is v's metadata.

Sourceval mem_meta : 'a B0_meta.key -> t -> bool

mem_meta k v is B0_meta.mem k (B0_def.meta v).

Sourceval has_tag : bool B0_meta.key -> t -> bool

has_tag k v is B0_meta.has_tag k (B0_def.meta v).

Sourceval find_meta : 'a B0_meta.key -> t -> 'a option

find_meta k v is B0_meta.find k (B0_def.meta v).

Sourceval find_or_default_meta : 'a B0_meta.key -> t -> 'a

find_or_default_meta k u is B0_meta.find_or_default k (B0_unit.meta u).

Sourceval get_meta : 'a B0_meta.key -> t -> ('a, string) result

get_meta m k u is Ok v if find_meta k u is Some v and a final user friendly error message if None.

Add & Lookup

Sourceval add : t -> unit

add v adds the value v to the list of defined values.

Sourceval fold : (t -> 'a -> 'a) -> 'a -> 'a

fold f acc folds over the list of defined values.

Sourceval list : unit -> t list

list () is the list of defined values.

Sourceval find : string -> t option

find name is the value named name (if any).

Sourceval get : string -> t

get name looks up the value named name and errors the b0 file if there no such name.

Sourceval get_or_suggest : string -> (t, t list) result

get_or_suggest name is the value named name or a (possibly empty) list of suggested values whose name could match name.

Sourceval get_or_hint : string -> (t, string) result

get_or_hint name is the value named name or an error message that indicates that name could not be found with suggested names.

Sourceval get_list_or_hint : all_if_empty:bool -> string list -> (t list, string) result

get_list_or_hint ~all_if_empty names are the value named after names or an error that indicates the names that could not be found with suggested names. If all_if_empty is true an empty ns returns list () sorted by name.

Scope

Sourceval scope_path : t -> string list

scope_path v are the scopes in which v is defined starting from the root. If v is defined in the root scope this is [], if v is defined in a library scope lib this is [[""]; lib]

Sourceval in_root_scope : t -> bool

in_root_scope v is true iff v is in the root scope.

Sourceval in_current_scope : t -> bool

in_current_scope v is true iff v is in the current scope.

Sourceval scope_dir : t -> B0_std.Fpath.t option

scope_dir v is the scope directory in which v is defined.

Sourceval scope_dir' : t -> (B0_std.Fpath.t, string) result

scope_dir' v is like scope_dir but errors with an end-user message if None.

Sourceval in_scope_dir : t -> B0_std.Fpath.t -> B0_std.Fpath.t option

in_scope_dir v path makes the path path absolute with respect to the scope directory in which v is defined. This is None if v's scope has no directory (e.g. on library scopes).

Sourceval in_scope_dir' : t -> B0_std.Fpath.t -> (B0_std.Fpath.t, string) result

in_scope_dir' is like in_scope_dir but errors with an end-user message if None.

Formatters

Sourceval pp_name_str : string B0_std.Fmt.t

pp_name_str v pretty prints value names.

Sourceval pp_name : t B0_std.Fmt.t

pp_name v formats v's name.

Sourceval pp_doc : t B0_std.Fmt.t

pp_doc formats v's doc string.

Sourceval pp_synopsis : t B0_std.Fmt.t

pp_synopsis formats v's name and its doc string.

pp formats v 's name, its doc string and its metadata dictionary.

Value set and maps

Sourcemodule Set : Set.S with type elt = t with type t = B0_defs.b0_unit_set

Value sets.

Sourcemodule Map : Map.S with type key = t

Value maps.

Tool name map

Sourceval tool_name_map : Set.t -> t B0_std.String.Map.t

tool_name_map units are the user accessible tools defined by the set of units units.