Module: Bwrap::Execution

Includes:
Path, Output
Included in:
Args::Bind, Args::Environment, Bwrap, Config::Features::Ruby, Resolvers::Library, Resolvers::Library::Base, Resolvers::Mime
Defined in:
lib/bwrap/execution.rb,
lib/bwrap/execution/labels.rb,
lib/bwrap/execution/execution.rb,
lib/bwrap/execution/exceptions.rb

Overview

Provides methods to execute commands and handle its output.

Output can be controlled by using log levels of Output module.

Examples:

Executing a command

class MyClass
  include Bwrap::Execution

  def my_method
    execute %w{ ls /dev/null }

Defined Under Namespace

Modules: Labels, Path Classes: CommandError, CommandNotFound, Exec, Execute, ExecutionFailed, Logging, Popen2e

Class Method Summary collapse

Methods included from Output

debug?, debug_output, error_output, handle_output_options, info_output, quiet?, trace?, trace_output, verb_output, verbose?, warn_output

Class Method Details

.do_execute(command, **kwargs) ⇒ Object

Note:

When an array is given as a command, empty strings are passed as empty arguments.

This means that ‘[ “foo”, “bar” ]` passes one argument to “foo” command, when `[ “foo”, “”, “bar” ]` passes two arguments.

This may or may not be what is assumed, so it can’t be fixed here. It is up to the command to decide how to handle empty arguments.

Actual implementation of execution command. Can be used when static method is needed.

Returns pid of executed command if wait is false. Returns command output if wait is true.

fail == If true, an error is raised in case the command returns failure code.

TODO: log kwarg could take log level as argument. Like :trace.

Parameters:

  • kwargs (Hash) —

    a customizable set of options

Options Hash (**kwargs):

  • clear_env (Boolean) — default: false —

    If true, executed command will run with no environment variables

  • config (Bwrap::Config|nil) — default: nil —

    Configuration used to launch the command inside bubblewrap

  • direct_output (Boolean) — default: false —

    Instead of buffering output, it will be directly outputted to ‘$stdout`

  • env (Hash<String, String>) — default: {} —

    Environment variables to add to the command. Also see ‘clear_env` option

  • error (:show|nil) — default: nil —

    if :show and execution failed, prints output of the command with Output#warn

  • fail (Boolean) — default: true —

    If true, ExecutionFailed is raised if process did not finish successfully

  • log (Boolean) — default: true —

    If true, prints output if verbose flag has been set. And if a log file has been configured, also logs to that file

  • log_callback (Integer) — default: 1 —

    Semi-internal variable used to tailor caller in debug messages

  • rootcmd (Array|Symbol|nil) — default: nil —

    Flags used to construct bubblewrap environment

  • wait (Boolean) — default: true —

    If true, this method blocks until the command has finished. Otherwise returns immediately. It is possible for user to call ‘Process.wait` to wait for result at suitable place

See Also:

  • #execute


78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/bwrap/execution/execution.rb', line 78

def self.do_execute command, **kwargs
  executor = Exec.new command
  executor.dry_run = @dry_run

  executor.clear_env      = kwargs.key?(:clear_env)     ? kwargs.delete(:clear_env)     : false
  executor.config         = kwargs.key?(:config)        ? kwargs.delete(:config)        : nil
  executor.direct_output  = kwargs.key?(:direct_output) ? kwargs.delete(:direct_output) : false
  executor.env            = kwargs.key?(:env)           ? kwargs.delete(:env)           : {}
  executor.error          = kwargs.key?(:error)         ? kwargs.delete(:error)         : nil
  executor.fail           = kwargs.key?(:fail)          ? kwargs.delete(:fail)          : true
  executor.log            = kwargs.key?(:log)           ? kwargs.delete(:log)           : true
  executor.log_callback   = kwargs.key?(:log_callback)  ? kwargs.delete(:log_callback)  : 1
  executor.rootcmd        = kwargs.key?(:rootcmd)       ? kwargs.delete(:rootcmd)       : nil
  executor.wait           = kwargs.key?(:wait)          ? kwargs.delete(:wait)          : true

  unless kwargs.empty?
    raise ArgumentError, %{unknown keywords: #{kwargs.keys.join ","}}
  end

  executor.execute
ensure
  @last_status = executor.last_status if executor&.last_status
end

.last_status ⇒ Object

Note:

This only is able to return the status if wait is true, as otherwise caller is assumed to

Returns Process::Status instance of last execution.

handle execution flow.



130
131
132
 
# File 'lib/bwrap/execution/execution.rb', line 130

def self.last_status
  @last_status
end

.popen2e(*cmd, rootcmd: nil, config: nil, log_callback: 2, log: true, &block) ⇒ Object

Works similarly to Ruby’s official ‘Open3.popen2e`.

A block is accepted, as does ‘Open3.popen2e`. For now, at least.

TODO: Verify default log_callback is correct

Parameters:

  • config (Bwrap::Config) (defaults to: nil) —

    Configuration used to launch the executable inside bubblewrap

  • rootcmd (Array|Symbol|nil) (defaults to: nil) —

    A strange way to use bwrap. Probably no sense to use this

  • log (Boolean) (defaults to: true) —

    If true, prints output if verbose flag has been set. And if a log file has been configured, also logs to that file

  • log_callback (Hash) (defaults to: 2) —

    a customizable set of options

Options Hash (log_callback:):

  • Semi-internal (Integer) —

    variable used to tailor caller in debug messages



117
118
119
120
121
122
123
 
# File 'lib/bwrap/execution/execution.rb', line 117

def popen2e *cmd, rootcmd: nil, config: nil, log_callback: 2, log: true, &block
  popen = Bwrap::Execution::Popen2e.new rootcmd: rootcmd, config: config
  popen.dry_run = @dry_run # TODO: Add a test that tests that this works as it works with execute().
  popen.popen2e(*cmd, log_callback: log_callback, log: log, &block)
ensure
  @last_status = popen&.child_status
end