Module B00.Tool

Command line tools.

A tool is specified either by name, to be looked up via an unspecified mecanism, or by a file path to an executable file. It also declares the environment variables it accesses in the process environment and whether and how it supports response files.

Declared environment variables are split into relevant and shielded variables. A relevant variable is a variable whose value influences the tool's output. A shielded variable is a variable whose value does not influence the tool's output but is nonetheless essential to its operation. Shielded environment variables do not appear are not part of the stamp used to memoize tool spawns. Variables specifying the location of temporary file directories are good examples of shielded variables.

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

Environment variables

type env_vars = string list

The type for lists of environment variable names.

val tmp_vars : env_vars

tmp_vars is ["TMPDIR"; "TEMP"; "TMP"].

Response files

type response_file

The type for response file specification.

val response_file_of : (B0_std.Cmd.t -> string) -> (B0_std.Fpath.t -> B0_std.Cmd.t) -> response_file

response_file_of to_file cli is a response file specification that uses to_file cmd to convert the command line cmd to a response file content and cli f a command line fragment to be given to the tool so that it treats file f as a response file.

val args0 : response_file

args0 is response file support for tools that reads null byte (0x00) terminated arguments response files via an -args0 FILE command line synopsis.

Tools

type t

The type for tools.

val v : ?⁠response_file:response_file -> ?⁠shielded_vars:env_vars -> ?⁠vars:env_vars -> B0_std.Cmd.tool -> t

v ~response_file ~shielded_vars ~vars cmd is a tool specified by cmd. vars are the relevant variables accessed by the tool (defaults to []). shielded_vars are the shielded variables accessed by the tool (defaults to tmp_vars). response_file defines the reponse file support for the tool (if any).

val by_name : ?⁠response_file:response_file -> ?⁠shielded_vars:env_vars -> ?⁠vars:env_vars -> string -> t

by_name is like v but reference the tool directly via a name.

raises Invalid_argument

if Fpath.is_seg name is false.

val name : t -> B0_std.Cmd.tool

name t is t's tool name. If this is a relative file path with a single segment the tool is meant to be searched via an external mecanism.

val vars : t -> env_vars

vars t are the relevant environment variables accessed by t.

val shielded_vars : t -> env_vars

shieled_vars t are the shielded environment variables accessed by t.

val response_file : t -> response_file option

response_file t is t's response file specification (if any).

val read_env : t -> B0_std.Os.Env.t -> B0_std.Os.Env.t * B0_std.Os.Env.t

read_env t env is (all, relevant) with all the environment with the variables of env that are in vars t and shielded_vars t and relevant those of vars t only.