fab.tools#

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

class fab.tools.Ar#

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

This class defines the allowed tool categories.

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

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.
category – the Category (C_COMPILER or FORTRAN_COMPILER).
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)#

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. # TODO: why return “” when an error happened? # TODO: we need to properly create integers for compiler versions # to (later) allow less and greater than comparisons.

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.

Returns:: a version string, e.g ‘6.10.1’, or empty string if a different error happened when trying to get the compiler version.
Raises:: RuntimeError – if the compiler was not found.

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

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#: Class for cpp.

class fab.tools.CppFortran#: Class for cpp when used as a Fortran preprocessor

class fab.tools.Fcm#: 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)#

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

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#: Class for Intel’s Fortran-specific preprocessor.

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

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')#

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#

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.Icc(name='icc', exec_name='icc')#

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')#

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.Linker(name=None, exec_name=None, suite=None, compiler=None, output_flag='-o')#

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.

link(input_files, output_file, add_libs=None)#

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

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#

This is the base class for PSyclone.

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

Run PSyclone with the specified parameters.

Parameters:

api (str) – the PSyclone API.
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#

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

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:

src (Union[str, Path]) – from where to export.
dst (Union[str, Path]) – destination path.
revision (Optional[str]) – revision to export. (default: None)

checkout(src, dst, revision=None)#

Runs svn checkout.

Parameters:

src (Union[str, Path]) – from where to check out.
dst (Union[str, Path]) – destination path.
revision (Optional[str]) – revision to check out. (default: None)

update(dst, revision=None)#

Runs svn checkout.

Parameters:

dst (Union[str, Path]) – destination path.
revision (Optional[str]) – revision to check out. (default: None)

merge(src, dst, revision=None)#

Runs svn merge.

Parameters:

src (Union[str, Path]) – the src URI.
dst (Union[str, Path]) – destination path.
revision (Optional[str]) – revision to check out. (default: None)

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

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 to be sent to subprocess.run() as the command. (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:

RuntimeError – if the code is not available.
RuntimeError – if the return code of the executable is not 0.

Return type:

str

class fab.tools.ToolBox#

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#

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

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

Modules

`ar`	This file contains the Ar class for archiving files.
`category`	This simple module defines an Enum for all allowed categories.
`compiler`	This file contains the base class for any compiler, and derived classes for gcc, gfortran, icc, ifort
`flags`	This file contains a simple Flag class to manage tool flags.
`linker`	This file contains the base class for any Linker.
`preprocessor`	This file contains the base class for any preprocessor, and two derived classes for cpp and fpp.
`psyclone`	This file contains the tool class for PSyclone.
`rsync`	This file contains the Rsync class for synchronising file trees.
`tool`	This file contains the base class for all tools, i.e. compiler, preprocessor, linker, archiver, Psyclone, rsync, versioning tools.
`tool_box`	This file contains the ToolBox class.
`tool_repository`	This file contains the ToolRepository class.
`versioning`	This file contains the base class for versioning tools like git and subversion.