Classes
class	IExecutableTargetInfo
	Provides information about executable build targets. More...
class	SubprocessError
	Exception type thrown by execute(). More...
Functions
int	execute (const std::string &cmd, bool quiet=false, std::ostream out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false, const IExecutableTargetInfo targets=NULL)
	Execute command as subprocess.
int	execute (std::vector< std::string > args, bool quiet=false, std::ostream out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false, const IExecutableTargetInfo targets=NULL)
	Execute command as subprocess.
std::string	exedir (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
	Get directory of executable file.
std::string	exename (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
	Get name of executable file.
std::string	exepath (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
	Get absolute path of executable file.
bool	istarget (const std::string &name, const IExecutableTargetInfo *targets=NULL)
	Determine whether a given build target is known.
void	print_contact (const char *contact)
	Print contact information.
void	print_version (const char name, const char version, const char project=NULL, const char copyright=NULL, const char *license=NULL)
	Print version information including copyright and license notices.
std::vector< std::string >	qsplit (const std::string &args)
	Split quoted string.
std::string	targetuid (const std::string &name, const IExecutableTargetInfo *targets=NULL)
	Get UID of build target.
std::string	tostring (const std::vector< std::string > &args)
	Convert array of arguments to quoted string.

Function Documentation

int basis::util::execute	(	const std::string &	cmd,
		bool	quiet = `false`,
		std::ostream *	out = `NULL`,
		bool	allow_fail = `false`,
		int	verbose = `0`,
		bool	simulate = `false`,
		const IExecutableTargetInfo *	targets = `NULL`
	)

Execute command as subprocess.

This function is a replacement for system() on Unix and is furthermore less platform dependent. The first argument of the given command-line string is mapped to an absolute executable file using exepath() if the given first argument is a know build target name. Otherwise, the command-line is used unmodified.

Parameters:

[in]	cmd	Command-line given as double quoted string. Arguments containing whitespaces have to be quoted using double quotes. Use a backslash (\) to escape double quotes inside an argument as well as to escape a backslash itself (required if backslash at end of double quoted argument, e.g., "this argument \\").
[in]	quiet	Turns off output of stdout of child process to stdout of parent process.
[out]	out	Output stream where command output is written to.
[in]	allow_fail	If true, no exception is thrown if the exit code of the child process is non-zero. Otherwise, a SubprocessException object is thrown in that case.
[in]	verbose	Verbosity of output messages. Does not affect verbosity of executed command.
[in]	simulate	Whether to simulate command execution only.
[in]	targets	Structure providing information about executable targets.

Returns:: Exit code of command or -1 if subprocess creation failed.

Exceptions:

SubprocessError If subprocess creation failed or command returned a non-zero exit code while allow_fail is false.

Definition at line 132 of file utilities.cxx.

int basis::util::execute	(	std::vector< std::string >	args,
		bool	quiet = `false`,
		std::ostream *	out = `NULL`,
		bool	allow_fail = `false`,
		int	verbose = `0`,
		bool	simulate = `false`,
		const IExecutableTargetInfo *	targets = `NULL`
	)

Execute command as subprocess.

This function is a replacement for system() on Unix and is furthermore less platform dependent. The first argument of the given command-line string is mapped to an absolute executable file using exepath() if the given first argument is a know build target name. Otherwise, the command-line is used unmodified.

Parameters:

[in]	args	Command-line given as argument vector. The first argument has to be either a build target name or the name/path of the command to execute. Note that as a side effect, the first argument of the input vector is replaced by the absolute path of the actual executable file if applicable.
[in]	quiet	Turns off output of stdout of child process to stdout of parent process.
[out]	out	Output stream where command output is written to.
[in]	allow_fail	If true, no exception is thrown if the exit code of the child process is non-zero. Otherwise, a SubprocessException object is thrown in that case.
[in]	verbose	Verbosity of output messages. Does not affect verbosity of executed command.
[in]	simulate	Whether to simulate command execution only.
[in]	targets	Structure providing information about executable targets.

Returns:: Exit code of command or -1 if subprocess creation failed.

Exceptions:

SubprocessError If subprocess creation failed or command returned a non-zero exit code while allow_fail is false.

Definition at line 141 of file utilities.cxx.

string basis::util::exedir	(	const std::string &	name = `std::string()`,
		const IExecutableTargetInfo *	targets = `NULL`
	)

Get directory of executable file.

Parameters:

[in]	name	Name of command or `NULL`.
[in]	targets	Structure providing information about executable targets.

Returns:: Absolute path of directory containing executable or an empty string if not found. If name is NULL, the directory of this executable is returned.

See also:: exepath()

Definition at line 109 of file utilities.cxx.

string basis::util::exename	(	const std::string &	name = `std::string()`,
		const IExecutableTargetInfo *	targets = `NULL`
	)

Get name of executable file.

The name of the executable may or may not include the file name extension depending on the executable type and operating system. Hence, this function is neither an equivalent to os::path::basename(exepath()) nor os::path::filename(exepath()). In particular, on Windows, the .exe and .com extension is not included in the returned executable name.

Parameters:

[in]	name	Name of command or `NULL`.
[in]	targets	Structure providing information about executable targets.

Returns:: Name of executable file or an empty string if not found. If name is NULL, the name of this executable is returned.

See also:: exepath()

Definition at line 96 of file utilities.cxx.

string basis::util::exepath	(	const std::string &	name = `std::string()`,
		const IExecutableTargetInfo *	targets = `NULL`
	)

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, an empty string is returned.

Todo:: This function currently makes use of the which command implemented in Python and called as subprocess in order to search a command in the system PATH. This which command is part of BASIS and can also be used on Windows. However, a native C++ implementation would be desireable.

Parameters:

[in]	name	Name of command or `NULL`.
[in]	targets	Structure providing information about executable targets.

Returns:: Absolute path of executable or an empty string if not found. If name is NULL, the path of this executable is returned.

See also:: exename(); exedir()

Definition at line 58 of file utilities.cxx.

bool basis::util::istarget	(	const std::string &	name,
		const IExecutableTargetInfo *	targets = `NULL`
	)

Determine whether a given build target is known.

Parameters:

[in]	name	Name of build target.
[in]	targets	Structure providing information about executable targets.

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

Definition at line 52 of file utilities.cxx.

void basis::util::print_contact ( const char * contact )

Print contact information.

Parameters:

[in] contact Name of contact.

Definition at line 27 of file utilities.cxx.

void basis::util::print_version	(	const char *	name,
		const char *	version,
		const char *	project = `NULL`,
		const char *	copyright = `NULL`,
		const char *	license = `NULL`
	)

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()` function, 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 `NULL` 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 `NULL` or an empty string, no copyright notice is printed.
[in]	license	Information regarding licensing. If `NULL` or an empty string, no license information is printed.

Definition at line 33 of file utilities.cxx.

vector< string > basis::util::qsplit ( const std::string & args )

Split quoted string.

Parameters:

[in] args Quoted string of arguments.

Returns:: Array of arguments.

See also:: tostring()

Definition at line 126 of file utilities.cxx.

string basis::util::targetuid	(	const std::string &	name,
		const IExecutableTargetInfo *	targets = `NULL`
	)

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]	targets	Structure providing information about executable targets.

Returns:: UID of named build target.

Definition at line 46 of file utilities.cxx.

string basis::util::tostring ( const std::vector< std::string > & args )

Convert array of arguments to quoted string.

Parameters:

[in] args Array of arguments.

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()

Definition at line 120 of file utilities.cxx.

Classes

Functions

Function Documentation