B00.Memo
Build memoizer.
A memoizer ties together and environment, an operation cache, a guard and an executor.
The type for memoizers. This ties together an environment, a guard, an operation cache and an executor.
type tool_lookup = t -> B00_std.Cmd.tool -> (B00_std.Fpath.t, string) result B00_std.Fut.t
The type for tool lookups. Given a command line tool specification returns a file path to the tool executable or an error message mentioning the tool if it cannot be found.
val tool_lookup_of_os_env : ?sep:string -> ?var:string -> B00_std.Os.Env.t -> tool_lookup
env_tool_lookup ~sep ~var env
is a tool lookup that gets the value of the var
variable in env
treats it as a sep
separated search path and uses the result to lookup with B00_std.Os.Cmd.get
with the memo's win_exe
. var
defaults to PATH
and sep
to B00_std.Fpath.search_path_sep
.
The type for memoizer feedback. FIXME remove `Miss_tool now that we have notify operations.
val create : ?clock:B00_std.Time.counter -> ?cpu_clock:B00_std.Time.cpu_counter -> feedback:(feedback -> unit) -> cwd:B00_std.Fpath.t -> ?win_exe:bool ->
?tool_lookup:tool_lookup -> Env.t -> B000.Guard.t -> B000.Reviver.t -> B000.Exec.t -> t
val memo : ?hash_fun:(module B00_std.Hash.T) -> ?win_exe:bool -> ?tool_lookup:tool_lookup -> ?env:B00_std.Os.Env.t -> ?cwd:B00_std.Fpath.t ->
?cache_dir:B00_std.Fpath.t -> ?trash_dir:B00_std.Fpath.t -> ?jobs:int -> ?feedback:([ feedback | B000.Exec.feedback ] -> unit) ->
unit -> (t, string) result
memo
is a simpler create
hash_fun
defaults to B00_std.Hash.Xxh_64
.jobs
defaults to B00_std.Os.Cpu.logical_count
.env
defaults to B00_std.Os.Env.current
cwd
defaults to B00_std.Os.Dir.cwd
cache_dir
defaults to Fpath.(cwd / "_b0" / ".cache")
trash_dir
defaults to Fpath.(cwd / "_b0" / ".trash")
feedback
defaults to a nop.val clock : t -> B00_std.Time.counter
clock m
is m
's clock.
val cpu_clock : t -> B00_std.Time.cpu_counter
cpu_clock m
is m
's cpu clock.
val win_exe : t -> bool
win_exe m
is true
if we spawn windows executables. This affects tool lookups. Defaults to Sys
.win32.
val tool_lookup : t -> tool_lookup
tool_lookup m
is m
's tool lookup function.
val reviver : t -> B000.Reviver.t
reviver m
is m
's reviver.
val guard : t -> B000.Guard.t
guard m
is m
's guard.
val exec : t -> B000.Exec.t
exec m
is m
's executors.
val trash : t -> B000.Trash.t
trash m
is m
's trash.
val has_failures : t -> bool
has_failures m
is true
iff at least one operation has failed.
val hash_string : t -> string -> B00_std.Hash.t
hash_string m s
is B000.Reviver.hash_string
(reviver m) s
.
val hash_file : t -> B00_std.Fpath.t -> (B00_std.Hash.t, string) result
hash_file m f
is B000.Reviver.hash_file
(reviver m) f
. Note that these file hashes operations are memoized.
val stir : block:bool -> t -> unit
stir ~block m
runs the memoizer a bit. If block
is true
blocks until the memoizer is stuck with no operation to execute.
val status : t -> (unit, B000.Op.aggregate_error) result
status m
looks for aggregate errors in m
in ops m
, see B000.Op.aggregate_error
for details.
Usually called after a blocking stir
to check everything executed as expected. The function itself has no effect more operations can be on m
afterwards. If you are only interested in checking if a failure occured in the memo has_failures
is faster.
delete_trash ~block m
is B000.Trash.delete
~block (trash m)
.
Activity marks are just identifiers used for UI purposes to watermark the activity – notably build operations – occuring in the memo.
val mark : t -> string
mark m
is m
's mark.
val run_proc : t -> (unit -> unit B00_std.Fut.t) -> unit
run m proc
calls proc ()
and handles any fail
ure. This also catches non-asynchronous uncaught exceptions and turns them into `Fail
notification operations.
val fail : t -> ('a, Format.formatter, unit, 'b) format4 -> 'a
fail m fmt ...
fails the procedure via a notify
operation.
fail_if_error m r
is v
if r
is Ok v
and fail m "%s" e
if r
is Error _
.
XXX This needs a bit of reviewing.
val notify : ?k:(unit -> unit) ->
t -> [ `Fail | `Warn | `Start | `End | `Info ] -> ('a, Format.formatter, unit, unit) format4 -> 'a
notify m kind msg
is a notification msg
of kind kind
. Note that a `Fail
notification will entail a finish_error
, see also fail
and fail_if_error
.
val notify_if_error : t -> [ `Fail | `Warn | `Start | `End | `Info ] -> use:'a ->
('a, string) result -> 'a
notify_if_error m kind ~use r
is v
if r
is Ok v
. If r
is Error e
, a notification of kind kind
is added to m
and use
is returned. Note that a `Fail
notification will entail a finish_error
, see also fail
and fail_if_error
.
val file_ready : t -> B00_std.Fpath.t -> unit
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).
val read : t -> B00_std.Fpath.t -> string B00_std.Fut.t
read m file k
is a future that determines with the contents s
of file file
when it becomes ready in m
.
val write : t -> ?stamp:string -> ?reads:B00_std.Fpath.t list -> ?mode:int ->
B00_std.Fpath.t -> (unit -> (string, string) result) -> unit
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 stamp
(defaults to ""
).
val copy : t -> ?mode:int -> ?linenum:int -> src:B00_std.Fpath.t -> B00_std.Fpath.t -> unit
copy m ~mode ?linenum ~src dst
copies file src
to dst
with mode mode
(defaults to 0o644
) when src
is ready. If linenum
is specified, the following line number directive is prependend in dst
to the contents of src
:
#line $(linenum) "$(src)"
val mkdir : t -> ?mode:int -> B00_std.Fpath.t -> unit B00_std.Fut.t
mkdir m dir p
is a future that determines with ()
when the directory path p
has been created with mode mode
(defaults to 0o755
). The behaviour with respect to file permission of intermediate path segments matches Os
.Dir.create.
val delete : t -> B00_std.Fpath.t -> unit B00_std.Fut.t
delete m p
is a future that determines with ()
when path p
is deleted (trashed in fact) and free to reuse.
val wait_files : t -> B00_std.Fpath.t list -> unit B00_std.Fut.t
wait_files m files
is a future that deterines with ()
when all files
are ready in m
. FIXME Unclear whether we really want this.
TODO. Can't we simplify the cmd/tool/tool_lookup dance ?.
val tool : t -> Tool.t -> B00_std.Cmd.t -> cmd
tool m t
is tool t
memoized. Use the resulting function to spawn the tool with the given arguments.
TODO explain better how this all works. If the path given to Tool.t
is not made of a single path segment it is not search in the environmet and it is the duty of the client to ensure it gets ready at some point. Either by a direct call to file_ready
or by another file write.
val tool_opt : t -> Tool.t -> (B00_std.Cmd.t -> cmd) option B00_std.Fut.t
tool_opt m t
is like tool
, except None
is returned if the tool cannot be found. y
val spawn : t -> ?stamp:string -> ?reads:B00_std.Fpath.t list -> ?writes:B00_std.Fpath.t list -> ?env:B00_std.Os.Env.t -> ?cwd:B00_std.Fpath.t ->
?stdin:B00_std.Fpath.t -> ?stdout:B000.Op.Spawn.stdo -> ?stderr:B000.Op.Spawn.stdo -> ?success_exits:B000.Op.Spawn.success_exits -> ?post_exec:(B000.Op.t -> unit) ->
?k:(int -> unit) -> cmd -> unit
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 B00_std
.Os.File.null.stdout
and stderr
, the redirections for the standard outputs of the command, see stdo
. Path to files are created if needed. Warning. File redirections are not automatically added to writes
; this allows for example to use B00_std
.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
.post_exec
, if specified is called with the build operation after it has been executed or revived. If it was executed this is called before the operation gets recorded. It can be used to define the reads
and writes
of the operation if they are difficult to find out before hand. Do not access m
in that function.k
, if specified a function invoked once the spawn has succesfully executed with the exit code.stamp
is used for caching if two spawns diff only in their stamp they will cache to different keys. This can be used to memoize tool whose outputs may not entirely depend on the environment, the cli stamp and the the content of read files.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.
val spawn' : t -> ?stamp:string -> ?reads:B00_std.Fpath.t list -> writes_root:B00_std.Fpath.t -> ?writes:(B000.Op.t -> B00_std.Fpath.t list) ->
?env:B00_std.Os.Env.t -> ?cwd:B00_std.Fpath.t -> ?stdin:B00_std.Fpath.t -> ?stdout:B000.Op.Spawn.stdo -> ?stderr:B000.Op.Spawn.stdo -> ?success_exits:B000.Op.Spawn.success_exits -> ?k:(int -> unit) ->
cmd -> unit
spawn'
is like spawn
except the actual file paths written by the spawn need not be determined before the spawn. Only the root directory of writes need to be specified via writes_root
. After the spawn executes the writes can be determined via the writes
function, the returned paths must be absolute and be prefixed by writes_root
(defaults to recursively list all the files rootet in writes_root
).