This module is all you need to define your own build functions.
It allows to access directories and files, consult
the build configuration, submit build operations
and read and write file path metadata.
('a -> unit) -> unit
val build_dir :
B0.build -> B0.Fpath.t
build_dir bis the path to
b's current, unit-specific, build directory. This is where you should produce your build artefacts.
val build_file :
B0.build -> string -> B0.Fpath.t
build_file b fis
Fpath.(build_dir b / f).
val src_dir :
B0.build -> B0.Fpath.t
src_dir bis the path to
b's current source root, where non-built (source) files are expected too be looked up. If you are using
b0's description files this is the directory of the
B0.mlfile in which the unit is described.
val unit_build_dir :
B0.build -> B0.Unit.t -> B0.Fpath.t
unit_build_dir b uis the build directory of unit
u. This should only be used to lookup files in other build units.
FIXME. Do the build unit request API.
val conf :
B0.build -> 'a B0.Conf.key -> 'a
conf b kis
k's effective value for the build.
val tool :
B0.build -> B0.Tool.t -> B0.Cmd.t -> run
tool b t argsis
t's tool for the build is a run for the tool
Warning. The resulting run must only be used to
val conf_tool :
B0.build -> B0.Tool.t B0.Conf.key -> B0.Cmd.t -> run
conf_tool b kis tool b (conf b k).
TODO Explain that basically build operations read and write
files. For an operation to be executed all the files it reads need to be
ready. A file becomes ready either if it has been declared
as such or if it has been written by a build operation.
Build roots are non-built files, typically sources or external
libraries. In order to read them in a build operation
(i.e. introduce a dependency on them) you need to declare them
B0.Build.ready, otherwise the operation waits for it to be
produced and fails if that doesn't eventually happen.
val ready :
B0.build -> B0.Fpath.t -> unit
ready b pdeclares path
pto be ready in
b. This is typically used with sources files and files external to the build (e.g. intalled libraries). See also
val src :
B0.build -> B0.Fpath.t -> B0.Fpath.t
src b srcis:
let src = Fpath.(src_dir b // src) in ready b src; src
Tool spawns are asynchronous and can be issued in any order.
Actual execution occurs once the all files the files that are
declared to be read by the spawn are ready. Produce spawn
operations as soon as possible to maximize parallelism.
[ `File of B0.Fpath.t | `Tee of B0.Fpath.t | `Ui ]
`Uiredirects the output to the user interface of the build system (usually only actually shown in case of failure). Outputs are always first redirected to a file and read back by the program running the build on completion, this means that in the spawned program isatty will be
falseon the fds.
`File predirect from/to file path
`Tee p, for outputs perform both
val spawn :
?reads:B0.Fpath.t list ->
?writes:B0.Fpath.t list ->
?success:int list ->
?stdout:stdo -> ?stderr:stdo -> run -> unit
spawn b ~reads ~writes ~success ~env ~cwd ~stdin ~stdout ~stderr runspawns
readsfiles are ready and makes files
writesready if the spawn succeeds and the file exists. The rest of the arguments are:
stdinreads input from the given file. If unspecified reads from the standard input of the program running the build. Warning. The file is not automatically added to
reads, this allows for example to use
stderr, the redirections for the standard outputs of the command, see
B0.Build.stdo. Warning. File redirections are not automatically added to
writes; this allows for example to use
successthe exit codes that determine if the build operation is successful (defaults to
to always succeed)
env, environment variables added to the build environment. This overrides environment variables read by the tool in the build environment except forced one. It also allows to specify environment that may not be mentioned by running tool's environment specification.
cwdthe current working directory. Default is
B0.Build.dir. In general it's better to avoid using relative file paths and tweaking the
cwd. Construct your paths using the absolute directory functions and make your invocations independent from the
TODO This is already quite complete, however the following could be added (maybe through another primitive):
val read :
B0.build -> B0.Fpath.t -> string fiber
read b file kreads the contents of
filewhen it becomes ready and invokes
val write :
B0.build -> ?reads:B0.Fpath.t list -> B0.Fpath.t -> (unit -> string) -> unit
write b ~reads f genonce
readsare ready writes
fassuming the result depends only on
reads. This means that if
readsdo not change and
fwas already computed
kis not invoked. If
readsis empty (default)
genis invoked on every run.
FIXME Not implemented.
val copy_file :
?linenum:int -> B0.build -> B0.Fpath.t -> B0.Fpath.t -> unit
copy_file ?linenum src dst, copies
linenumis specified the following line number directive is prepended to the contents of
#line $(linenum) "$(src)"
$(src)substituted with the values of
val mkdir :
B0.build -> B0.Fpath.t -> unit fiber
mkdir b d kcreates
dirand proceeds with
k. Note. No file is being made ready.
val await_units :
B0.build -> B0.Unit.t list -> unit fiber
await_units b us kwaits for the build of
usto be finished before proceeding with
val fail :
((('a, Format.formatter, unit, unit) Pervasives.format4 -> 'a) -> unit) -> 'b
fail (fun m -> m fmt ...)fails the current build unit with the formatted message
val fail_on_error_msg :
'a B0.result -> 'a
fail (fun m -> m "%s" e), if
Error (`Msg e).
val find_path_meta :
B0.build -> B0.Fpath.t -> 'a B0.Fpath.Meta.key -> 'a option
find_path_meta b f kis
f's meta binding for
val add_path_meta :
?force:bool -> B0.build -> B0.Fpath.t -> 'a B0.Fpath.Meta.key -> 'a -> unit
add_path_meta ~force b f k vsets
f's meta binding for
false) the built unit fails if
kis already bound for
val unit :
B0.build -> B0.Unit.t
unit bis the unit being built.
val units :
B0.build -> B0.Unit.t list
units bare the unit that are being built.
Note. Unless you are using B0 as a library or creating your
own driver you need not be concered by this. TODO maybe
move that to a private sub-module.
val ctrl :
?tty_cap:B0.Tty.cap -> ?max_spawn:int -> unit -> ctrl
ctrl ~max_spawncontrols a build as follows:
max_spawnis the maximal number of commands that are spawned concurrently. Defaults to
tty_capis the capabilities of the output terminal. Defaults to
val create :
universe:B0.Unit.t list -> B0.Unit.t list -> B0.build B0.result
init cache ctrl ~dirinitializes a new build using
diras the build directory.
WARNING. Anything can happen in that directory do not use
dir that contains data you might want to keep.
val dir :
B0.build -> B0.Fpath.t
dir bis the absolute path to
b's build directory. It is unlikely you will have to use this.
val cache :
B0.build -> B0.Cache.t
val stored_conf :
B0.build -> B0.Conf.t
val outcome :
B0.build -> B0.Outcome.t
bis not finished.
val start :
B0.build -> unit
start bstarts the build.
val finish :
B0.build -> unit B0.result
finish bfinishes the build