B0 actions manual

Basics

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:

• Can be associated with an empty build procedure and not build anything. For example it can simply run a script or an OCaml function to download and refresh conformance tests or data from the web.
• May explicitely require other units or packs to be build in order to be run.
• May simply be the executable built by the unit.
• May simply be the public tool.
• Has access to what was part of the build. For example the .ocaml library unit is an action that has a few subcommand whose outcomes.
• Can influence how the build is done (B0_unit.Action.store).

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"

Howto

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