Module OpamProcess

Process and job handling, with logs, termination status, etc.

type command = private {
  1. cmd : string;
  2. args : string list;
  3. cmd_text : string option;
  4. cmd_dir : string option;
  5. cmd_env : string array option;
  6. cmd_stdin : bool option;
  7. cmd_stdout : string option;
  8. cmd_verbose : bool option;
  9. cmd_name : string option;
  10. cmd_metadata : (string * string) list option;
}

The type of shell commands

val command : ?env:string array -> ?verbose:bool -> ?name:string -> ?metadata:(string * string) list -> ?dir:string -> ?allow_stdin:bool -> ?stdout:string -> ?text:string -> string -> string list -> command

Builds a shell command for later execution.

  • parameter env

    environment for the command

  • parameter verbose

    force verbosity

  • parameter name

    title, used to name log files, etc.

  • parameter metadata

    additional info to log

  • parameter dir

    CWD for the command

  • parameter allow_stdin

    whether to forward stdin

  • parameter stdout

    redirect stdout to the given file instead of the logs

  • parameter text

    Short text that may be displayed in the status-line

  • parameter command

    The command itself

  • parameter args

    Command-line arguments

val string_of_command : command -> string
val text_of_command : command -> string option
val is_verbose_command : command -> bool
val make_command_text : ?color:OpamConsole.text_style -> string -> ?args:string list -> string -> string

Returns a label suitable for printing the summary of running commands. First string is the topic (e.g. package), second the action (e.g. command name). Optional command arguments may be used for details (e.g. make action).

type t = {
  1. p_name : string;
    (*

    Command name

    *)
  2. p_args : string list;
    (*

    Command args

    *)
  3. p_pid : int;
    (*

    Process PID

    *)
  4. p_cwd : string;
    (*

    Process initial working directory

    *)
  5. p_time : float;
    (*

    Process start time

    *)
  6. p_stdout : string option;
    (*

    stdout dump file

    *)
  7. p_stderr : string option;
    (*

    stderr dump file

    *)
  8. p_env : string option;
    (*

    dump environment variables

    *)
  9. p_info : string option;
    (*

    dump process info

    *)
  10. p_metadata : (string * string) list;
    (*

    Metadata associated to the process

    *)
  11. p_verbose : bool;
    (*

    whether output of the process should be displayed

    *)
  12. p_tmp_files : string list;
    (*

    temporary files that should be cleaned up upon completion

    *)
}

The type for processes

type result = {
  1. r_code : int;
    (*

    Process exit code, or 256 on error

    *)
  2. r_signal : int option;
    (*

    Signal received if the processed was killed

    *)
  3. r_duration : float;
    (*

    Process duration

    *)
  4. r_info : (string * string) list;
    (*

    Process info

    *)
  5. r_stdout : string list;
    (*

    Content of stdout dump file

    *)
  6. r_stderr : string list;
    (*

    Content of stderr dump file

    *)
  7. r_cleanup : string list;
    (*

    List of files to clean-up

    *)
}

Process results

val run : command -> result

run command synchronously call the command command.cmd with arguments command.args. It waits until the process is finished. The files name.info, name.env, name.out and name.err, with name = command.cmd_name are created, and contain the process main description, the environment variables, the standard output and the standard error. Don't forget to call cleanup result afterwards

val run_background : command -> t

Same as run, but doesn't wait. Use wait_one to wait and collect results; Don't forget to call cleanup result afterwards

val dry_run_background : command -> t

Similar to run_background, except that no process is created, and a dummy process (suitable for dry_wait_one) is returned.

val wait : t -> result

wait p waits for the processus p to end and returns its results. Be careful to handle Sys.Break

val dontwait : t -> result option

Like wait, but returns None immediately if the process hasn't ended

val wait_one : t list -> t * result

Wait for the first of the listed processes to terminate, and return its termination status

val dry_wait_one : t list -> t * result

Similar to wait_one for simulations, to be used with dry_run_background

val interrupt : t -> unit

Send SIGINT to a process (or SIGKILL on Windows)

val is_success : result -> bool

Is the process result a success?

val is_failure : result -> bool

Is the process result a failure?

val cleanup : ?force:bool -> result -> unit

Should be called after process termination, to cleanup temporary files. Leaves artefacts in case OpamGlobals.debug is on and on failure, unless force has been set.

val check_success_and_cleanup : result -> bool

Like is_success, with an added cleanup side-effect (as cleanup ~force:true). Use this when not returning 0 is not an error case: since the default behaviour is to cleanup only when the command returned 0, which is not what is expected in that case.

Misc

val read_lines : string -> string list

Reads a text file and returns a list of lines

val string_of_result : ?color:OpamConsole.text_style -> result -> string

Detailed report on process outcome

val result_summary : result -> string

Short report on process outcome

module Job : sig ... end

Higher-level interface to allow parallelism

type 'a job = 'a Job.Op.job
val default_env : unit -> string array

Current environment. On Windows, Cygwin installation binary path and git location path may be added to PATH. *

val resolve_command : ?env:string array -> ?dir:string -> string -> string option

As OpamStd.Sys.resolve_command, except the default for ~env is default_env.

val create_process_env : string -> string array -> string array -> Unix.file_descr -> Unix.file_descr -> Unix.file_descr -> int

Like Unix.create_process_env, but with correct escaping of arguments when invoking a cygwin executable from a native Windows executable.