fab.tools package#

A simple init file to make it shorter to import tools.

class fab.tools.Ar#

Bases: Tool

This is the base class for ar.

create(output_fpath, members)#

Create the archive with the specified name, containing the listed members.

Parameters:

  • output_fpath (Path) – the output path.

  • members (List[Union[Path, str]]) – the list of objects to be added to the archive.

class fab.tools.Category(value)#

Bases: Enum

This class defines the allowed tool categories.

C_COMPILER = 1#
C_PREPROCESSOR = 2#
FORTRAN_COMPILER = 3#
FORTRAN_PREPROCESSOR = 4#
LINKER = 5#
PSYCLONE = 6#
FCM = 7#
GIT = 8#
SUBVERSION = 9#
AR = 10#
RSYNC = 11#
MISC = 12#
property is_compiler#

Returns if the category is either a C or a Fortran compiler.

class fab.tools.CCompiler(name, exec_name, suite, compile_flag=None, output_flag=None, omp_flag=None)#

Bases: Compiler

This is the base class for a C compiler. It just sets the category of the compiler as convenience.

Parameters:

  • name (str) – name of the compiler.

  • exec_name (str) – name of the executable to start.

  • suite (str) – name of the compiler suite.

  • compile_flag – the compilation flag to use when only requesting compilation (not linking). (default: None)

  • output_flag – the compilation flag to use to indicate the name of the output file (default: None)

  • omp_flag – the flag to use to enable OpenMP (default: None)

class fab.tools.Compiler(name, exec_name, suite, category, compile_flag=None, output_flag=None, omp_flag=None)#

Bases: CompilerSuiteTool

This is the base class for any compiler. It provides flags for

  • compilation only (-c),

  • naming the output file (-o),

  • OpenMP

Parameters:

  • name (str) – name of the compiler.

  • exec_name (Union[str, Path]) – name of the executable to start.

  • suite (str) – name of the compiler suite this tool belongs to.

  • category (Category) – the Category (C_COMPILER or FORTRAN_COMPILER).

  • compile_flag (Optional[str]) – the compilation flag to use when only requesting compilation (not linking). (default: None)

  • output_flag (Optional[str]) – the compilation flag to use to indicate the name of the output file (default: None)

  • omp_flag (Optional[str]) – the flag to use to enable OpenMP (default: None)

get_hash()#
Return type:

int

Returns:

a hash based on the compiler name and version.

compile_file(input_file, output_file, add_flags=None)#

Compiles a file. It will add the flag for compilation-only automatically, as well as the output directives. The current working directory for the command is set to the folder where the source file lives when compile_file is called. This is done to stop the compiler inserting folder information into the mod files, which would cause them to have different checksums depending on where they live.

Parameters:

  • input_file (Path) – the path of the input file.

  • outpout_file – the path of the output file.

  • add_flags (Optional[List[str]]) – additional compiler flags. (default: None)

check_available()#

Checks if the compiler is available. While the method in the Tools base class would be sufficient (when using –version), in case of a compiler we also want to store the compiler version. So, re-implement check_available in a way that will automatically store the compiler version for later usage.

Return type:

bool

Returns:

whether the compiler is available or not. We do this by requesting the compiler version.

get_version()#

Try to get the version of the given compiler.

Expects a version in a certain part of the –version output, which must adhere to the n.n.n format, with at least 2 parts.

Return type:

Tuple[int, ...]

Returns:

a tuple of at least 2 integers, representing the version e.g. (6, 10, 1) for version ‘6.10.1’.

Raises:

RuntimeError – if the compiler was not found, or if it returned an unrecognised output from the version command.

run_version_command(version_command='--version')#

Run the compiler’s command to get its version.

Parameters:

version_command (Optional[str]) – The compiler argument used to get version info. (default: '--version')

Return type:

str

Returns:

The output from the version command.

Raises:

RuntimeError – if the compiler was not found, or raised an error.

parse_version_output(category, version_output)#

Extract the numerical part from the version output. Implemented in specific compilers.

Return type:

str

get_version_string()#

Get a string representing the version of the given compiler.

Return type:

str

Returns:

a string of at least 2 numeric version components, i.e. major.minor[.patch, …]

Raises:

RuntimeError – if the compiler was not found, or if it returned an unrecognised output from the version command.

class fab.tools.CompilerSuiteTool(name, exec_name, suite, category)#

Bases: Tool

A tool that is part of a compiler suite (typically compiler and linker).

Parameters:

  • name (str) – name of the tool.

  • exec_name (Union[str, Path]) – name of the executable to start.

  • suite (str) – name of the compiler suite.

  • category (Category) – the Category to which this tool belongs.

property suite: str#
Returns:

the compiler suite of this tool.

class fab.tools.Cpp#

Bases: Preprocessor

Class for cpp.

class fab.tools.CppFortran#

Bases: Preprocessor

Class for cpp when used as a Fortran preprocessor

class fab.tools.Fcm#

Bases: Subversion

This is the base class for FCM. All commands will be mapped back to the corresponding subversion commands.

class fab.tools.Flags(list_of_flags=None)#

Bases: list

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

TODO #22: This class and build_config.FlagsConfig should be combined.

Parameters:

list_of_flags (Optional[List[str]]) – List of parameters to initialise this object with. (default: None)

checksum()#
Return type:

str

Returns:

a checksum of the flags.

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.FortranCompiler(name, exec_name, suite, module_folder_flag, syntax_only_flag=None, compile_flag=None, output_flag=None, omp_flag=None)#

Bases: Compiler

This is the base class for a Fortran compiler. It is a compiler that needs to support a module output path and support for syntax-only compilation (which will only generate the .mod files).

Parameters:

  • name (str) – name of the compiler.

  • exec_name (str) – name of the executable to start.

  • suite (str) – name of the compiler suite.

  • module_folder_flag (str) – the compiler flag to indicate where to store created module files.

  • syntax_only_flag – flag to indicate to only do a syntax check. The side effect is that the module files are created. (default: None)

  • compile_flag – the compilation flag to use when only requesting compilation (not linking). (default: None)

  • output_flag – the compilation flag to use to indicate the name of the output file (default: None)

  • omp_flag – the flag to use to enable OpenMP (default: None)

property has_syntax_only: bool#
Returns:

whether this compiler supports a syntax-only feature.

set_module_output_path(path)#

Sets the output path for modules.

Params path:

the path to the output directory.

compile_file(input_file, output_file, add_flags=None, syntax_only=False)#

Compiles a file.

Parameters:

  • input_file (Path) – the name of the input file.

  • output_file (Path) – the name of the output file.

  • add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)

  • syntax_only (bool) – if set, the compiler will only do a syntax check (default: False)

class fab.tools.Fpp#

Bases: Preprocessor

Class for Intel’s Fortran-specific preprocessor.

class fab.tools.Gcc(name='gcc', exec_name='gcc')#

Bases: GnuVersionHandling, CCompiler

Class for GNU’s gcc compiler.

Parameters:

  • name (str) – name of this compiler. (default: 'gcc')

  • exec_name (str) – name of the executable. (default: 'gcc')

class fab.tools.Gfortran(name='gfortran', exec_name='gfortran')#

Bases: GnuVersionHandling, FortranCompiler

Class for GNU’s gfortran compiler.

Parameters:

  • name (str) – name of this compiler. (default: 'gfortran')

  • exec_name (str) – name of the executable. (default: 'gfortran')

class fab.tools.Git#

Bases: Versioning

This is the base class for git.

current_commit(folder=None)#
Return type:

str

Returns:

the hash of the current commit.

Parameters:

folder (Union[Path, str, None]) – the folder for which to determine the current commitf (defaults to .). (default: None)

init(folder)#

Initialises a directory.

Parameters:

folder (Union[Path, str]) – the directory to initialise.

clean(folder)#

Removes all non versioned files in a directory.

Parameters:

folder (Union[Path, str]) – the directory to clean.

fetch(src, dst, revision)#

Runs git fetch in the specified directory

Parameters:

  • src (Union[str, Path]) – the source directory from which to fetch

  • revision (Optional[str]) – the revision to fetch (can be “” for latest revision)

  • dst (Union[str, Path]) – the directory in which to run fetch.

checkout(src, dst='', revision=None)#

Checkout or update a Git repo.

Parameters:

  • src (str) – the source directory from which to checkout.

  • dst (str) – the directory in which to run checkout. (default: '')

  • revision (Optional[str]) – the revision to check out (can be “” for latest revision). (default: None)

merge(dst, revision=None)#

Merge a git repo into a local working copy. If the merge fails, it will run git merge –abort to clean the directory.

Parameters:

  • dst (Union[str, Path]) – the directory to merge in.

  • revision (Optional[str]) – the revision number (only used for error message, it relies on git fetch running previously). (default: None)

class fab.tools.GnuVersionHandling#

Bases: object

Mixin to handle version information from GNU compilers

parse_version_output(category, version_output)#

Extract the numerical part from a GNU compiler’s version output

Parameters:

  • name – the compiler’s name

  • category (Category) – the compiler’s Category

  • version_output (str) – the full version output from the compiler

Return type:

str

Returns:

the actual version as a string

Raises:

RuntimeError – if the output is not in an expected format.

class fab.tools.Icc(name='icc', exec_name='icc')#

Bases: IntelVersionHandling, CCompiler

Class for the Intel’s icc compiler.

Parameters:

  • name (str) – name of this compiler. (default: 'icc')

  • exec_name (str) – name of the executable. (default: 'icc')

class fab.tools.Ifort(name='ifort', exec_name='ifort')#

Bases: IntelVersionHandling, FortranCompiler

Class for Intel’s ifort compiler.

Parameters:

  • name (str) – name of this compiler. (default: 'ifort')

  • exec_name (str) – name of the executable. (default: 'ifort')

class fab.tools.IntelVersionHandling#

Bases: object

Mixin to handle version information from Intel compilers

parse_version_output(category, version_output)#

Extract the numerical part from an Intel compiler’s version output

Parameters:

  • name – the compiler’s name

  • version_output (str) – the full version output from the compiler

Return type:

str

Returns:

the actual version as a string

Raises:

RuntimeError – if the output is not in an expected format.

class fab.tools.Linker(name=None, exec_name=None, suite=None, compiler=None, output_flag='-o')#

Bases: CompilerSuiteTool

This is the base class for any Linker. If a compiler is specified, its name, executable, and compile suite will be used for the linker (if not explicitly set in the constructor).

Parameters:

  • name (Optional[str]) – the name of the linker. (default: None)

  • exec_name (Optional[str]) – the name of the executable. (default: None)

  • suite (Optional[str]) – optional, the name of the suite. (default: None)

  • compiler (Optional[Compiler]) – optional, a compiler instance (default: None)

  • output_flag (str) – flag to use to specify the output name. (default: '-o')

check_available()#
Return type:

bool

Returns:

whether the linker is available or not. We do this by requesting the linker version.

Executes the linker with the specified input files, creating output_file.

Parameters:

  • input_files (List[Path]) – list of input files to link.

  • output_file (Path) – output file.

  • add_libs (Optional[List[str]]) – additional linker flags. (default: None)

Return type:

str

Returns:

the stdout of the link command

class fab.tools.Preprocessor(name, exec_name, category, availablility_option=None)#

Bases: Tool

This is the base class for any preprocessor.

Parameters:

  • name (str) – the name of the preprocessor.

  • exec_name (Union[str, Path]) – the name of the executable.

  • category (Category) – the category (C_PREPROCESSOR or FORTRAN_PREPROCESSOR)

preprocess(input_file, output_file, add_flags=None)#

Calls the preprocessor to process the specified input file, creating the requested output file.

Parameters:

  • input_file (Path) – input file.

  • output_file (Path) – the output filename.

  • add_flags (Optional[List[Union[Path, str]]]) – List with additional flags to be used. (default: None)

class fab.tools.Psyclone(api=None)#

Bases: Tool

This is the base class for PSyclone.

process(config, x90_file, psy_file, alg_file, transformation_script=None, additional_parameters=None, kernel_roots=None, api=None)#

Run PSyclone with the specified parameters.

Parameters:

  • api (Optional[str]) – the PSyclone API. (default: None)

  • x90_file (Path) – the input file for PSyclone

  • psy_file (Path) – the output PSy-layer file.

  • alg_file (Union[Path, str]) – the output modified algorithm file.

  • transformation_script (Optional[Callable[[Path, BuildConfig], Path]]) – an optional transformation script (default: None)

  • additional_parameters (Optional[List[str]]) – optional additional parameters for PSyclone (default: None)

  • kernel_roots (Optional[List[Union[Path, str]]]) – optional directories with kernels. (default: None)

class fab.tools.Rsync#

Bases: Tool

This is the base class for rsync.

execute(src, dst)#

Execute an rsync command from src to dst. It supports ~ expansion for src, and makes sure that src end with a / so that rsync does not create a sub-directory.

Parameters:

  • src (Path) – the input path.

  • dst (Path) – destination path.

class fab.tools.Subversion(name=None, exec_name=None, category=Category.SUBVERSION)#

Bases: Versioning

This is the base class for subversion. Note that this is also the base class for FCM, so it allows overwriting name, exec_name and category, but will default to use svn.

Parameters:

  • name (Optional[str]) – name of the tool, defaults to subversion. (default: None)

  • exec_name (Union[Path, str, None]) – name of the executable, defaults to “svn”. (default: None)

  • category (Category) – the category, FCM or SUBVERSION (the latter is the default) (default: <Category.SUBVERSION: 9>)

execute(pre_commands=None, revision=None, post_commands=None, env=None, cwd=None, capture_output=True)#

Executes a svn command.

Parameters:

  • pre_commands (Optional[List[str]]) – List of strings to be sent to subprocess.run() as the command. (default: None)

  • revision (Union[int, str, None]) – optional revision number as argument (default: None)

  • post_commands (Optional[List[str]]) – List of additional strings to be sent to subprocess.run() after the optional revision number. (default: None)

  • env (Optional[Dict[str, str]]) – Optional env for the command. By default it will use the current session’s environment. (default: None)

  • capture_output – If True, capture and return stdout. If False, the command will print its output directly to the console. (default: True)

Return type:

str

export(src, dst, revision=None)#

Runs svn export.

Parameters:
checkout(src, dst, revision=None)#

Runs svn checkout.

Parameters:
update(dst, revision=None)#

Runs svn checkout.

Parameters:
merge(src, dst, revision=None)#

Runs svn merge.

Parameters:
class fab.tools.Tool(name, exec_name, category=Category.MISC, availablility_option=None)#

Bases: object

This is the base class for all tools. It stores the name of the tool, the name of the executable, and provides a run method.

Parameters:

  • name (str) – name of the tool.

  • exec_name (Union[str, Path]) – name or full path of the executable to start.

  • category (Category) – the Category to which this tool belongs. (default: <Category.MISC: 12>)

  • availability_option – a command line option for the tool to test if the tool is available on the current system. Defaults to –version.

check_available()#

Run a ‘test’ command to check if this tool is available in the system. :rtype: bool :returns: whether the tool is working (True) or not.

property is_available: bool#

Checks if the tool is available or not. It will call a tool-specific function check_available to determine this, but will cache the results to avoid testing a tool more than once.

Returns:

whether the tool is available (i.e. installed and working).

property is_compiler: bool#

Returns whether this tool is a (Fortran or C) compiler or not.

property exec_name: str#
Returns:

the name of the executable.

property name: str#
Returns:

the name of the tool.

property category: Category#
Returns:

the category of this tool.

property flags: Flags#
Returns:

the flags to be used with this tool.

property logger: Logger#
Returns:

a logger object for convenience.

run(additional_parameters=None, env=None, cwd=None, capture_output=True)#

Run the binary as a subprocess.

Parameters:

  • additional_parameters (Union[str, List[Union[Path, str]], None]) – List of strings or paths to be sent to subprocess.run() as additional parameters for the command. Any path will be converted to a normal string. (default: None)

  • env (Optional[Dict[str, str]]) – Optional env for the command. By default it will use the current session’s environment. (default: None)

  • capture_output – If True, capture and return stdout. If False, the command will print its output directly to the console. (default: True)

Raises:
Return type:

str

class fab.tools.ToolBox#

Bases: object

This class implements the tool box. It stores one tool for each category to be used in a FAB build.

add_tool(tool, silent_replace=False)#

Adds a tool for a given category.

Parameters:

  • tool (Tool) – the tool to add.

  • silent_replace (bool) – if set, no warning will be printed if an existing tool is replaced. (default: False)

Raises:

RuntimeError – if the tool to be added is not available.

Return type:

None

get_tool(category)#

Returns the tool for the specified category.

Parameters:

category (Category) – the name of the category in which to look for the tool.

Raises:

KeyError – if the category is not known.

Return type:

Tool

class fab.tools.ToolRepository#

Bases: dict

This class implements the tool repository. It stores a list of tools for various categories. For each compiler, it will automatically create a tool called “linker-{compiler-name}” which can be used for linking with the specified compiler.

Singleton access. Changes the value of _singleton so that the constructor can verify that it is indeed called from here.

add_tool(cls)#

Creates an instance of the specified class and adds it to the tool repository.

Parameters:

cls (Type[Any]) – the tool to instantiate.

get_tool(category, name)#
Return type:

Tool

Returns:

the tool with a given name in the specified category.

Parameters:

  • category (Category) – the name of the category in which to look for the tool.

  • name (str) – the name of the tool to find.

Raises:

  • KeyError – if there is no tool in this category.

  • KeyError – if no tool in the given category has the requested name.

set_default_compiler_suite(suite)#

Sets the default for linker and compilers to be of the given compiler suite.

Parameters:

suite (str) – the name of the compiler suite to make the default.

get_default(category)#

Returns the default tool for a given category, which is just the first tool in the category.

Parameters:

category (Category) – the category for which to return the default tool.

Raises:

KeyError – if the category does not exist.

class fab.tools.Versioning(name, exec_name, category)#

Bases: Tool

This is the base class for versioning tools like git and svn.

Parameters:

  • name (str) – the name of the tool.

  • exec_name (Union[str, Path]) – the name of the executable of this tool.

  • category (Category) – the category to which this tool belongs).

Submodules#

On this page
Show Source