Classes
class	SubprocessError
	Exception thrown when command execution failed. More...

Functions
def	decode (s)

def	execute (args, quiet=False, stdout=False, allow_fail=False, verbose=0, simulate=False, prefix=None, targets=None, base='.')
	Execute command as subprocess. More...

def	exedir (name=None, prefix=None, targets=None, base='.')
	Get directory of executable file. More...

def	exename (name=None, prefix=None, targets=None, base='.')
	Get name of executable file. More...

def	exepath (name=None, prefix=None, targets=None, base='.')
	Get absolute path of executable file. More...

def	istarget (name, prefix=None, targets=None)
	Determine whether a given build target is known. More...

def	print_contact (contact=CONTACT)
	Print contact information. More...

def	print_version (name, version=None, project=None, copyright=COPYRIGHT, license=LICENSE)
	Print version information including copyright and license notices. More...

def	qsplit (args)
	Split quoted string of arguments. More...

def	targetuid (name, prefix=None, targets=None)
	Get UID of build target. More...

def	tostring (args)
	Convert array of arguments to quoted string. More...

Variables
	binary_type = str

string	CONTACT = """andreas.schuh.84@gmail.com"""
	Default contact to use for help output of executables. More...

string	COPYRIGHT = """2011-12 University of Pennsylvania, 2013-14 Carnegie Mellon University, 2013-16 Andreas Schuh"""
	Default copyright of executables. More...

string	LICENSE = """See https://cmake-basis.github.io/download.html#license or COPYING file."""
	Default license of executables. More...

	text_type = unicode

Function Documentation

§ decode()

def basis.utilities.decode ( s )

Definition at line 69 of file utilities.py.

§ execute()

def basis.utilities.execute	(	args,
		quiet = `False`,
		stdout = `False`,
		allow_fail = `False`,
		verbose = `0`,
		simulate = `False`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Execute command as subprocess.

Parameters

[in]	args	Command with arguments given either as quoted string or array of command name and arguments. In the latter case, the array elements are converted to strings using the built-in str() function. Hence, any type which can be converted to a string is permitted. The first argument must be the name or path of the executable of the command.
[in]	quiet	Turns off output of `stdout` of child process to stdout of parent process.
[in]	stdout	Whether to return the command output.
[in]	allow_fail	If true, does not raise an exception if return value is non-zero. Otherwise, a `SubprocessError` is raised by this function.
[in]	verbose	Verbosity of output messages. Does not affect verbosity of executed command.
[in]	simulate	Whether to simulate command execution only.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns: The exit code of the subprocess if stdout is false (the default). Otherwise, if stdout is true, a tuple consisting of exit code and binary/encoded command output is returned. Note that if allow_fail is false, the returned exit code will always be 0.

Exceptions

SubprocessError If command execution failed. This exception is not raised if the command executed with non-zero exit code but allow_fail set to True.

Definition at line 324 of file utilities.py.

§ exedir()

def basis.utilities.exedir	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get directory of executable file.

Parameters

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns: Absolute path to directory containing executable or None if not found. If name is None, the directory of this executable is returned.

Definition at line 234 of file utilities.py.

§ exename()

def basis.utilities.exename	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get name of executable file.

Parameters

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns: Name of executable file or None if not found. If name is None, the name of this executable is returned.

Definition at line 216 of file utilities.py.

§ exepath()

def basis.utilities.exepath	(	name = `None`,
		prefix = `None`,
		targets = `None`,
		base = `'.'`
	)

Get absolute path of executable file.

This function determines the absolute file path of an executable. If no arguments are given, the absolute path of this executable is returned. If the command names a known executable build target, the absolute path to the corresonding built (and installed) executable file is returned. Otherwise, the named command is searched in the system PATH and its absolute path returned if found. If the executable is not found, None is returned.

Parameters

[in]	name	Name of command or `None`.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.
[in]	base	Base directory for relative paths in `targets`.

Returns: Absolute path of executable or None if not found. If name is None, the path of this executable is returned.

Definition at line 184 of file utilities.py.

§ istarget()

def basis.utilities.istarget	(	name,
		prefix = `None`,
		targets = `None`
	)

Determine whether a given build target is known.

Parameters

[in]	name	Name of build target.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.

Returns: Whether the named target is a known executable target.

Definition at line 160 of file utilities.py.

§ print_contact()

def basis.utilities.print_contact ( contact = CONTACT )

Print contact information.

Parameters

[in] contact Name of contact.

Definition at line 82 of file utilities.py.

§ print_version()

def basis.utilities.print_version	(	name,
		version = `None`,
		project = `None`,
		copyright = `COPYRIGHT`,
		license = `LICENSE`
	)

Print version information including copyright and license notices.

Parameters

[in]	name	Name of executable. Should not be set programmatically to the first argument of the `main` module, but a string literal instead.
[in]	version	Version of executable, e.g., release of project this executable belongs to.
[in]	project	Name of project this executable belongs to. If `None`, or an empty string, no project information is printed.
[in]	copyright	The copyright notice, excluding the common prefix "Copyright (c) " and suffix ". All rights reserved.". If `None`, or an empty string, no copyright notice is printed.
[in]	license	Information regarding licensing. If `None` or an empty string, no license information is printed.

Definition at line 102 of file utilities.py.

§ qsplit()

def basis.utilities.qsplit ( args )

Split quoted string of arguments.

Parameters

[in] args Quoted string of arguments.

Returns: Array of arguments.

See also: to_quoted_string()

Definition at line 289 of file utilities.py.

§ targetuid()

def basis.utilities.targetuid	(	name,
		prefix = `None`,
		targets = `None`
	)

Get UID of build target.

The UID of a build target is its name prepended by a namespace identifier which should be unique for each project.

Parameters

[in]	name	Name of build target.
[in]	prefix	Common prefix of targets belonging to this project.
[in]	targets	Dictionary mapping target UIDs to executable paths.

Returns: UID of named build target.

Definition at line 134 of file utilities.py.

§ tostring()

def basis.utilities.tostring ( args )

Convert array of arguments to quoted string.

Parameters

[in] args Array of arguments, bytes, or non-string type.

Returns: Double quoted string, i.e., string where arguments are separated by a space character and surrounded by double quotes if necessary. Double quotes within an argument are escaped with a backslash.

See also: split_quoted_string()

Definition at line 263 of file utilities.py.

Variable Documentation

§ binary_type

basis.utilities.binary_type = str

Definition at line 45 of file utilities.py.

§ CONTACT

string basis.utilities.CONTACT = """andreas.schuh.84@gmail.com"""

Default contact to use for help output of executables.

Definition at line 59 of file utilities.py.

§ COPYRIGHT

string basis.utilities.COPYRIGHT = """2011-12 University of Pennsylvania, 2013-14 Carnegie Mellon University, 2013-16 Andreas Schuh"""

Default copyright of executables.

Definition at line 55 of file utilities.py.

§ LICENSE

string basis.utilities.LICENSE = """See https://cmake-basis.github.io/download.html#license or COPYING file."""

Default license of executables.

Definition at line 57 of file utilities.py.

§ text_type

basis.utilities.text_type = unicode

Definition at line 44 of file utilities.py.

Classes

Functions

Variables

Function Documentation

§ decode()

§ execute()

§ exedir()

§ exename()

§ exepath()

§ istarget()

§ print_contact()

§ print_version()

§ qsplit()

§ targetuid()

§ tostring()

Variable Documentation

§ binary_type

§ CONTACT

§ COPYRIGHT

§ LICENSE

§ text_type