package b0
Install
dune-project
Dependency
Authors
Maintainers
Sources
sha512=e9aa779e66c08fc763019f16d4706f465d16c05d6400b58fbd0313317ef33ddea51952e2b058db28e65f7ddb7012f328c8bf02d8f1da17bb543348541a2587f0
doc/b0.file/B0_unit/index.html
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
The type for unit build procedures. Note that when the future determines the build may not be finished.
build_nop does nothing.
Units
The type for build units.
make n proc ~doc ~meta ~action is a build unit named n with build procedure proc, synopsis doc and metada meta.
proc u are the unit's build procedure.
Built executables
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.
copy_outcomes m u ~dst_dir copies the outcome of u to destination directory dst_dir.
is_public u is true iff u's meta has B0_meta.public set to true.
get_or_suggest_tool tool_name are tools names whose tool_name match tool_name and are filtered by keep
tool_is_user_accessible u assumes u has a tool name. This then returns true iff u is_public or in_root_scope.
Actions
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.
val 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 ->
tof_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.
val 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) ->
tof_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.
val 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) ->
tof_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
mangle_basename s is a basename that can be used with define.
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.
def_kind is the kind of defined value.
def v is the definition of value v.
name v is v's name. Note that this name changes depending on how the definition is scoped.
Metadata
mem_meta k v is B0_meta.mem k (B0_def.meta v).
has_tag k v is B0_meta.has_tag k (B0_def.meta v).
find_meta k v is B0_meta.find k (B0_def.meta v).
find_or_default_meta k u is B0_meta.find_or_default k (B0_unit.meta u).
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
get name looks up the value named name and errors the b0 file if there no such name.
get_or_suggest name is the value named name or a (possibly empty) list of suggested values whose name could match name.
get_or_hint name is the value named name or an error message that indicates that name could not be found with suggested names.
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
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]
scope_dir v is the scope directory in which v is defined.
scope_dir' v is like scope_dir but errors with an end-user message if None.
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).
in_scope_dir' is like in_scope_dir but errors with an end-user message if None.
Formatters
pp_name_str v pretty prints value names.
pp_name v formats v's name.
pp_doc formats v's doc string.
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
Tool name map
tool_name_map units are the user accessible tools defined by the set of units units.