fab.tools.flags#

This file contains the flag classes used to manage command line flags for tools, especially path-specific flags for compiler.

AbstractFlags:

The base class for a set of flags.

AlwaysFlags(AbstractFlags):

Flags that will always apply, independent of the path of the file to be compiled. It provides Python Template functionality:

$source for <project workspace>/source

$output for <project workspace>/build_output

$relative for <the source file’s folder>

MatchFlags(AlwaysFlags)

Flags that are only applied if a wildcard search matches the source file. This will likely require to make sure that the full path is specified (or the pattern starts with *).

ContainFlags(AlwaysFlags)

Flags that are only applied if the file path contains the specified string. The difference to MatchFlags is that ContainFlags do not need the full path to be specified.

FlagList:

Manages a list of flags, each of which is an instance of an AbstractFlag.

ProfileFlags:

Manages a set of flags for specific profiles, including inheritance.

Each tool uses a ProfileFlags instance. At runtime, the compilation steps will use the selected profile to get the Flags instance to use. The function get_flags will resolve the list of AbstractFlags by converting them from left to right into a list of strings. For example, [AlwaysFlag(“-g”), ContainFlags(“-O3”, pattern=”special_file”)] will be convert to [“-g”, “-O3”] if the file contains the string special_file, and otherwise it will be [“-g”].

Classes

`AbstractFlags`()	An abstract class to act as base class for all flag classes.
`AlwaysFlags`([flags])	This class represents a list of flags that is always to be used, independent of the path of the source file.
`ContainFlags`(pattern, flags)	This class implements path-specific flags using a simple substring search.
`FlagList`([list_of_flags, add_flags])	This class represents a list of parameters for a tool.
`MatchFlags`(pattern, flags)	This class implements path-specific flags using a file system wild card expressions (e.g. supporting * and ?).
`ProfileFlags`([flags, profile])	A list of flags that support a 'profile' to be used.

class fab.tools.flags.AbstractFlags#

An abstract class to act as base class for all flag classes.

Dummy constructor.

abstractmethod get_flags(config=None, file_path=None)#

This function returns the list of flags to be used for the given filename.

Parameters:

config (BuildConfig | None) – the config object (required for paths in templated strings) (default: None)
file_path (Path | None) – the file path of the file. This might not be used in all implementations. (default: None)

Return type:

list[str]

Returns:

the list of flags to use.

abstractmethod remove_flag(remove_flag, has_parameter=False)#

Removes all occurrences of remove_flag in flags. If has_parameter is defined, the next entry in flags will also be removed, and if this object contains this flag+parameter without space (e.g. -J/tmp), it will be correctly removed. Note that only the flag itself must be specified, you cannot remove a flag only if a specific parameter is given (i.e. remove_flag=”-J/tmp” will not work if this object contains […,”-J”, “/tmp”]).

Parameters:

remove_flag (str) – the flag to remove
has_parameter (bool) – if the flag to remove takes a parameter (default: False)

class fab.tools.flags.AlwaysFlags(flags=None)#

This class represents a list of flags that is always to be used, independent of the path of the source file. It also provides template functionality. This class also acts as convenient base class for all applications that add path-independent flags.

Parameters:: flags (str | list[str] | None) – a string or list of strings with command line flags. (default: None)

Dummy constructor.

static replace_template(string_list, config=None, file_path=None)#

This function replaces all $relative, $source, and $output in the string or list of string with the values taken from the config object and the file path. It is implemented as an abstract method (instead of acting on self._flags) since templating is also supported in patterns, to the same code here can be re-used).

Parameters:

string_list (list[str]) – list of strings, which will get all template arguments replaced.
config (BuildConfig | None) – the build configuration object from which paths are taken. (default: None)
file_path (Path | None) – the file path of an argument, used for $source. (default: None)

Return type:

list[str]

Returns:

a new list with strings where all the template parameters have been removed.

get_flags(config=None, file_path=None)#

This function returns the list of flags to be used for the given filename. This class will not take the file path into account, but it does support templated expressions $relative, $source, and $output.

Parameters:

config (BuildConfig | None) – the config object (used for paths in templates) (default: None)
file_path (Path | None) – the file path of the file, not used in this class. (default: None)

Return type:

list[str]

Returns:

the list of flags to use.

remove_flag(remove_flag, has_parameter=False)#

Parameters:

remove_flag (str) – the flag to remove
has_parameter (bool) – if the flag to remove takes a parameter (default: False)

class fab.tools.flags.MatchFlags(pattern, flags)#

This class implements path-specific flags using a file system wild card expressions (e.g. supporting * and ?). It does support templated expressions $relative, $source, and $output in the pattern as well.

Parameters:

pattern (str) – the wildcard pattern which is used when matching.
flags (str | list[str]) – a string or list of strings with command line flags.

Dummy constructor.

get_flags(config=None, file_path=None)#

This function returns the list of flags to be used for the given filename if the specified file path matches the pattern specified.

Parameters:

config (BuildConfig | None) – the config object (used for paths in templates) (default: None)
file_path (Path | None) – the file path of the file that must match the specified wildcard pattern. (default: None)

Return type:

list[str]

Returns:

the list of flags to use.

class fab.tools.flags.ContainFlags(pattern, flags)#

This class implements path-specific flags using a simple substring search.

Parameters:

flags (str | list[str]) – a string or list of strings with command line flags.
pattern (str) – the substring which is used when matching.

Dummy constructor.

get_flags(config=None, file_path=None)#

This function returns the list of flags to be used for the given filename if the specified file path contains the pattern as a substrings (i.e. anywhere in the file path).

Parameters:

config (BuildConfig | None) – the config object (used for paths in templates) (default: None)
file_path (Path | None) – the file path of the file that must match the specified wildcard pattern. (default: None)

Return type:

list[str]

Returns:

the list of flags to use.

class fab.tools.flags.FlagList(list_of_flags=None, add_flags=None)#

This class represents a list of parameters for a tool. It is a list with some additional functionality.

Parameters:

list_of_flags (AbstractFlags | str | list[str] | None) – List of parameters to initialise this object with. (default: None)
add_flags (AddFlags | list[AddFlags] | None) – List of old-style AddFlags, which will be converted to the new MatchFlags. (default: None)

get_flags(config=None, file_path=None)#

Return type:: list[str]
Returns:: the flags to be used for the compilation profile and file path specified.

checksum(config=None, file_path=None)#

Parameters:

config (BuildConfig | None) – the config object (used for templating) (default: None)
file_path (Path | None) – the file path of the source file, used for path-specific flags. (default: None)

Return type:

int

Returns:

a checksum of the flags.

add_flags(new_flags)#

Adds the specified flags to the list of flags.

Parameters:: new_flags (AbstractFlags | str | list[str]) – New flags to be added. Can be either an class derived from AbstractFlags, a single string or list of strings.
Return type:: None

remove_flag(remove_flag, has_parameter=False)#

This function will just call all individual flag objects to remove the flag. Note that a flag and its parameter cannot be split into two Flag instances (i.e. [AlwaysFlag(“-J”), AlwaysFlag(“/tmp”)] will not work).

Parameters:

remove_flag (str) – the flag to remove
has_parameter (bool) – if the flag to remove takes a parameter (default: False)

class fab.tools.flags.ProfileFlags(flags=None, profile='')#

A list of flags that support a ‘profile’ to be used. If no profile is specified, it will use “” (empty string) as ‘profile’. All functions take an optional profile parameter, so this class can also be used for tools that do not need a profile.

Parameters:

flags (AbstractFlags | str | list[str] | None) – optional flags to be added to this profile. (default: None)
profile (str) – optional profile to use if flags are specified, defaults to “”. (default: '')

get_flags(config=None, file_path=None)#

This method returns the flags used for the specified file, i.e. it will support path-specific flags. The BuildConfig is added as parameter to get the profile, but also to allow flags to use templated expressions $relative and $output (the values are taken from the config object).

Parameters:

config (BuildConfig | None) – the build config object. It stores the selected compilation profile, and paths that can be used in templated expressions. (default: None)
file_path (Path | None) – path to the source file to compile. (default: None)

Return type:

list[str]

define_profile(name, inherit_from=None)#

Defines a new profile name, and allows to specify if this new profile inherit settings from an existing profile. If inherit_from is specified, the newly defined profile will inherit from an existing profile (including the default profile “”).

Parameters:

name (str) – Name of the profile to define.
inherit_from (str | None) – Optional name of a profile to inherit settings from. (default: None)

add_flags(new_flags, profile=None)#

Adds the specified flags to the list of flags.

Parameters:: new_flags (AbstractFlags | str | list[str]) – A single string or list of strings which are the flags to be added.
Return type:: None

remove_flag(remove_flag, profile=None, has_parameter=False)#

Parameters:

remove_flag (str) – the flag to remove
has_parameter (bool) – if the flag to remove takes a parameter (default: False)

checksum(config=None, file_path=None)#

Parameters:

config (BuildConfig | None) – the config object (used for templating) (default: None)
file_path (Path | None) – the file path of the source file, used for path-specific flags. (default: None)

Return type:

int

Returns:

a checksum of the flags.