B0 actions manual

This manual shows how to deal with B0 actions and how to create your own.

TODO. Not super clear yet.


In B0, building is merely a side effect. Most of the time one is interested in doing something with build artefacts. This can be running them, displaying them, testing them, benchmarking them, deploying them etc.

For these reasons a build unit UNIT has (most of the time) an action associated to it. This action can simply be run with:

b0 -- UNIT ARG…

This builds the unit named UNIT like b0 -u UNIT would do and execute UNIT's action with arguments ARG….

Note that a unit action:

Note that a lot of domain specific build unit will define a default action for you.

b0 list        # Lists the units (and thus actions).
b0 list --all  # Also include library defined units
b0 tool list   # List public tools and private tools in the root scope

Unique outcome, multiple action. Make empty units that need a base unit.

Making your own action

XXX Needs to be rewritten.

Let's make a simple action a script at the root of your project:

Yaddada root vs scope

let mycmd =
  B0_unit.make_action "mycmd" ~doc:"Run mycmd" @@ fun env _ ~args ->
  let cwd = B0_env.scope_dir env in
  let script = B0_env.in_scope_dir env script in
  Os.Exit.execv ~cwd script Cmd.(path script %% args)

Even though you should rewrite all these scripts as OCaml actions a direct short cut for the above boilerplate is provided. Use B0_unit.Action.exec_file:

let mycmd =
  B0_action.make "mycmd" ~doc:"Run mycmd" @@
  B0_action.exec_file ~/"scripts/mycmd"


Run a unit executable in an action

let myunit = …
let action
  let doc = "That's particular" in
  B0_action.make' "my-exec" ~units:[myunit] ~doc @@ fun env _ ~args ->
  let* cmd = B0_env.unit_cmd myunit in
  Os.Cmd.run cmd