# qiBuild documentation

# qisys.command - Launch processes

## Calling process

`qisys.command.``check_is_in_path`(executable, env=None)

  Check that the given executable is to be found in %PATH%

`qisys.command.``find_program`(executable, env=None, raises=False, build_config=None)

  Get the full path of an executable by looking at PATH environment variable (and PATHEXT on windows) Toolchain binaries from build_config are also prepend to path. :return: None if program was not found,

  > the full path to executable otherwise

`qisys.command.``call`(cmd, cwd=None, env=None, ignore_ret_code=False, quiet=False, build_config=None)

  Execute a command line. If ignore_ret_code is False:

  > raise CommandFailedException if returncode is None.

  Else:
    simply returns the returncode of the process

  Note: first arg of the cmd is assumed to be something inside %PATH%. (or in env[PATH] if env is not None) Note: the shell= argument of the subprocess.Popen call will always be False. can raise:

  > - CommandFailedException if ignore_ret_code is False and returncode is non zero
  > - NotInPath if first arg of cmd is not in %PATH%
  > - And a normal exception if cwd is given and is not an existing directory.

`qisys.command.``check_output`(*popenargs, **kwargs)

  Run command with arguments and return its output as a byte string. If the exit code was non-zero it raises a CommandFailedException. The CommandFailedException object will have the return code in the returncode attribute, output in the `stdout` attribute and error in the `stderr` attribute. The arguments are the same as for the Popen constructor. Example: >>> check_output([“ls”, “-l”, “/dev/null”]) ‘crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/nulln’ The `stdout` argument is not allowed as it is used internally. To capture standard error in the result, use `stderr=STDOUT`. >>> check_output([“/bin/sh”, “-c”, ... “ls -l non_existent_file ; exit 0”], ... stderr=STDOUT) ‘ls: non_existent_file: No such file or directoryn’

`qisys.command.``check_output_error`(*popenargs, **kwargs)

  Run command with arguments and return its output and error as a byte string. If the exit code was non-zero it raises a `CalledProcessError`. The `CalledProcessError` object will have the return code in the returncode attribute and error concatenated at the end of output in the output attribute. The arguments are the same as for the `Popen` constructor. Examples: >>> check_output_error([“tar”, “tf”, “foo.tbz2”]) (‘./n./usr/n./usr/bin/n./usr/bin/foon’, ‘nbzip2: (stdin): trailing garbage after EOF ignoredn’) >>> try: ... qisys.command.check_output_error([‘tar’, ‘–bzip2’, ‘-tf’, ‘foo.tar.gz’]) ... except subprocess.CalledProcessError as e: ... print(e) The following command failed [‘tar’, ‘–bzip2’, ‘-tf’, ‘foo.tar.gz’] Return code is 2 Working dir was /tmp Stdout:

  > <nothing>

  Stderr:
    bzip2: (stdin) is not a bzip2 file. tar: Child returned status 2 tar: Error is not recoverable: exiting now

  The `stdout` and `stderr` arguments are not allowed as they are used internally.

### Notes about `call()`

#### Finding the executable to run

When using `call(cmd, ...)`, `check_is_in_path()` is always call with `cmd[0]` as argument, then replaced with the result of `find_program()`.

This way, on Windows:

    qisys.command.call(["cmake", ...])

works as soon as `cmake.exe` is in `PATH`

#### Behavior

subprocess.Popen is always called with `shell=False`, for security reasons.

Unless explicitly told not to, `CommandFailedException` is raised when the return code of the command is not zero.

## Running process in the background

`qisys.command.``call_background`(*args, **kwds)
  To be used in a “with” statement::
    with call_background(...):
      do_stuff()

    do_other_stuff()

  Process is run in the background, then do_stuff() is called. By the time you are executing do_other_stuff(), you know that the process has been killed, better yet, if an exception has occurred during do_stuff, this exception is re-raised after the process has been killed.

class `qisys.command.``Process`(cmd, cwd=None, env=None, capture=True)

  A simple way to run commands. Command will be started by run according to timeout parameter (not specified == no timeout). If it firstly send a SIGTERM signal to the process and wait 5 seconds for it to terminate alone (timeout). If it doesn’t stop by itself, it will kill the group of process (created with subprocess) to exterminate it. Process is then considered to be a zombie. You can then use Process.return_type to know the state of the process: Possible values: * Process.OK (exit code is zero) * Process.FAILED (exit code is > 0) * Process.TIME_OUT (process timed out) * Process.INTERRUPTED (exit code is < 0) * Process.NOT_RUN (could not start the process) * Process.ZOMBIE (could not kill process after it timed out)

## Exceptions

class `qisys.command.``CommandFailedException`

class `qisys.command.``ProcessCrashedError`

class `qisys.command.``NotInPath`

Changelog CMake index Python index Index