Module B00.Memo

The type for memoizer feedback.

pp_feedback ppf formats feedback.

The type for memoizers. This ties together an environment, a aguard, an operation cache and an executor.

memo is a simpler create

• hash_fun defaults to Op_cache.create's default.
• max_spawn defaults to Exec.create's default.
• env defaults to Os.Env.current
• cwd defaults to Os.Dir.cwd
• cachedir defaults to Fpath.(cwd / "_b0" / "cache")
• feedback defaults formats feedback on stdout.

clock m is m's clock.

cpu_clock m is m's cpu clock.

env m is m's environment.

op_cache m is m's operation cache.

guard m is m's guard.

exec m is m's executors.

hash_fun m is m's hash function.

stir ~block m runs the memoizer a bit. If block is true blocks until the memoizer is stuck with no operation to perform.

finish m finishes the memoizer. This blocks until there are no operation to execute like stir does. If no operations are left waiting this returns Ok (). If there are remaining wiating operations it aborts them and returns Error fs with fs the files that never became ready and where not supposed to be written by the waiting operations.

ops m is the list of operations that were submitted to the memoizer

The type for memoizer operation fibers.

fail fmt ... fails the fiber with the given error message.

fail_error fails the fiber with the given error.

ready m p declares path p to be ready, that is exists and is up-to-date in b. This is typically used with source files and files external to the build (e.g. installed libraries).

wait_files m files k continues with k () when files become ready. FIXME Unclear whether we really want this though this is kind of a reads constraint for a pure OCaml operation, but then we got read.

read m file k reads the contents of file file as s when it becomes ready and continues with k s.

write m ~reads file w writes file with data w () and mode mode (defaults to 0o644) when reads are ready. w's result must only depend on reads and salt (defaults to "").

mkdir m dir k creates directory dir and continues with k () at which point file dir is ready.

The type for memoized tools.

The type for memoized tool invocations.

tool m t is tool t memoized. Use the resulting function to spawn the tool with the given arguments.

spawn m ~reads ~writes ~env ~cwd ~stdin ~stdout ~stderr ~success_exits cmd spawns cmd once reads files are ready and makes files writes ready if the spawn succeeds and the file exists. The rest of the arguments are:

• stdin reads 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 Os.File.null.
• stdout and stderr, the redirections for the standard outputs of the command, see stdo. Warning. File redirections are not automatically added to writes; this allows for example to use Os.File.null.
• success_exits the exit codes that determine if the build operation is successful (defaults to 0, use [] to always succeed)
• env, environment variables added to the build environment. This overrides environment variables read by the tool in the build environment except for forced one. It also allows to specify environment that may not be mentioned by the running tool's environment specification.
• cwd the current working directory. Default is cwd. 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 cwd.
• k, if specified a fiber invoked once the spawn has succesfully executed with the exit code.

TODO. More expressive power could by added by:

1. Support to refine the read and write set after the operation returns.

Note. If the tool spawn acts on a sort of "main" file (e.g. a source file) it should be specified as the first element of reads, this is interpreted specially by certain build tracer.

Future values.