Module B0.OS.Cmd

module Cmd: sig .. end
Executing commands.

IMPORTANT. Do not execute commands with these functions in your build system: they will not be searched in the build environment and will not be cached. Running commands in builds must occur via B0.Build.spawn.



Tool existence and search

Tool search procedure. Given a list of directories, the tool of a command line is searched, in list order, for the first matching executable file. If the tool name is already a file path (i.e. contains a B0.Fpath.dir_sep_char) it is neither searched nor tested for existence and executability. In the functions below if the list of directories search is unspecified the result of parsing the PATH environment variable with B0.OS.Cmd.search_path_dirs is used.

Portability. In order to maximize portability no .exe suffix should be added to executable names on Windows, the tool search procedure will add the suffix during the tool search procedure if absent.

val find_tool : ?search:B0.Fpath.t list -> B0.Cmd.t -> B0.Fpath.t option B0.result
find_tool ~search cmd is the path to the tool of cmd as found by the tool search procedure in search.
val get_tool : ?search:B0.Fpath.t list -> B0.Cmd.t -> B0.Fpath.t B0.result
get_tool cmd is like B0.OS.Cmd.find_tool except it errors if the tool path cannot be found.
val exists : ?search:B0.Fpath.t list -> B0.Cmd.t -> bool B0.result
exists ~search cmd is Ok true if B0.OS.Cmd.find_tool finds a path and Ok false if it does not.
val must_exist : ?search:B0.Fpath.t list -> B0.Cmd.t -> B0.Cmd.t B0.result
must_exist ~search cmd is Ok cmd if B0.OS.Cmd.get_tool succeeds.
val resolve : ?search:B0.Fpath.t list -> B0.Cmd.t -> B0.Cmd.t B0.result
resolve ~search cmd is like B0.OS.Cmd.must_exist except the tool of the resulting command value has the path to the tool of cmd as determined by B0.OS.Cmd.get_tool.
val search_path_dirs : ?sep:string -> string -> B0.Fpath.t list B0.result
search_path_dirs ~sep s parses sep seperated file paths from s. sep is not allowed to appear in the file paths, it defaults to ";" if Sys.win32 is true and ":" otherwise.

Process completion statuses


type status = [ `Exited of int | `Signaled of int ] 
The type for process exit statuses.
val pp_status : status B0.Fmt.t
pp_status is a formatter for process exit statuses.
val pp_cmd_status : (B0.Cmd.t * status) B0.Fmt.t
pp_cmd_status is a formatter for command process exit statuses.

Process standard inputs and outputs


type stdi 
The type for representing the standard input of a process.
type stdo 
The type for representing the standard output of a process.
val in_string : string -> stdi
in_string s is a standard input that reads the string s.
val in_file : B0.Fpath.t -> stdi
in_file f is a standard input that reads from file f.
val in_fd : close:bool -> Unix.file_descr -> stdi
in_fd ~close fd is a standard input that reads from file descriptor fd. If close is true, fd is closed after the process spawn.
val in_stdin : stdi
in_stdin is in_fd ~close:false Unix.stdin, a standard input that reads from the current process standard input.
val in_null : stdi
in_null is in_file File.null.
val out_file : B0.Fpath.t -> stdo
out_file f is a standard output that writes to file f.
val out_fd : close:bool -> Unix.file_descr -> stdo
out_fd ~close fd is a standard output that writes to file descriptor fd. If close is true, fd is closed after the process spawn.
val out_stdout : stdo
out_stdout is out_fd ~close:false Unix.stdout
val out_stderr : stdo
out_stderr is out_fd ~close:false Unix.stderr
val out_null : stdo
out_null is out_file File.null

Blocking command execution


val run_status : ?env:string list ->
?cwd:B0.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo -> B0.Cmd.t -> status B0.result
run_status ~env ~cwd ~stdin ~stdout ~stderr cmd runs and wait for the completion of cmd in environment env with current directory cwd and standard IO connections stdin, stdout and stderr. env defaults to B0.OS.Env.assignments (), cwd to B0.OS.Dir.current (), stdin to B0.OS.Cmd.in_stdin, stdout to B0.OS.Cmd.out_stdout and stderr to B0.OS.Cmd.out_stderr.
val run_status_out : ?trim:bool ->
?env:string list ->
?cwd:B0.Fpath.t ->
?stdin:stdi ->
?stderr:[ `Out | `Stdo of stdo ] ->
B0.Cmd.t -> (status * string) B0.result
run_status_out is like B0.OS.Cmd.run_status except stdout is read from the process as a string. The string is String.trimed if trim is true (default). If stderr is `Out the process' stderr is redirected to stdout and thus read back aswell in the string.
val run : ?env:string list ->
?cwd:B0.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo -> B0.Cmd.t -> unit B0.result
run is B0.OS.Cmd.run_status with non-`Exited 0 statuses turned into errors via B0.OS.Cmd.pp_cmd_status.
val run_out : ?trim:bool ->
?env:string list ->
?cwd:B0.Fpath.t ->
?stdin:stdi ->
?stderr:[ `Out | `Stdo of stdo ] -> B0.Cmd.t -> string B0.result
run is B0.OS.Cmd.run_status_out with non-`Exited 0 statuses turned into errors via B0.OS.Cmd.pp_cmd_status.

Non-blocking command execution

Note. In contrast to waitpid(2) the following API doesn't allow to collect any child process completion. There are two reasons: first this is not supported on Windows, second doing so could collect processes that need to be collected by the build system API implementation.

type pid 
The type for process identifiers.
val pid_to_int : pid -> int
pid_to_int pid is the system identifier for process identifier pid.
val spawn : ?env:string list ->
?cwd:B0.Fpath.t ->
?stdin:stdi ->
?stdout:stdo ->
?stderr:stdo -> B0.Cmd.t -> pid B0.result
spawn ~env ~cwd ~stdin ~stdout ~stderr cmd spawns command cmd in environment env with current directory cwd and standard IO connections stdin, stdout and stderr. env defaults to B0.OS.Env.assignments (), cwd to B0.OS.Dir.current (), stdin to B0.OS.Cmd.in_stdin, stdout to B0.OS.Cmd.out_stdout and stderr to B0.OS.Cmd.out_stderr.
val collect : ?block:bool -> pid -> status option B0.result
collect ~block pid tries to collect the exit status of spawn pid. If block is false (default), Ok None is returned if pid has not exited yet. If block is true the call will return with Ok (Some st) once pid has exited.

Executing files

Windows. On Windows a program executing an execv* function yields back control to the terminal as soon as the child starts (vs. ends on POSIX). This entails all sorts of unwanted behaviours. To workaround this, the following function executes, on Windows, the file as a spawned child process which is waited on for completion via waitpid(2). Once the child process has terminated the calling process is immediately exited with the status of the child.

val execv : ?env:string list ->
?cwd:B0.Fpath.t -> B0.Fpath.t -> B0.Cmd.t -> unit B0.result
execv ~env ~cwd f argv executes file f as a new process in environment env with args as the Sys.argv of this process (in particular Sys.argv.(0) is the name of the program not the first argument to the program). The function only returns in case of error. env defaults to B0.OS.Env.assignments (), cwd to B0.OS.Dir.current ().