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[str, Path]]) – 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, version_regex, mpi=False, compile_flag=None, output_flag=None, openmp_flag=None, version_argument=None, availability_option=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.
version_regex (str) – A regular expression that allows extraction of the version number from the version output of the compiler.
mpi (bool) – whether the compiler or linker support MPI. (default: False)
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)
openmp_flag (Optional[str]) – the flag to use to enable OpenMP (default: None)

class fab.tools.Compiler(name, exec_name, suite, version_regex, category, mpi=False, compile_flag=None, output_flag=None, openmp_flag=None, version_argument=None, availability_option=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.
version_regex (str) – A regular expression that allows extraction of the version number from the version output of the compiler. The version is taken from the first group of a match.
category (Category) – the Category (C_COMPILER or FORTRAN_COMPILER).
mpi (bool) – whether the compiler or linker support MPI. (default: False)
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)
openmp_flag (Optional[str]) – the flag to use to enable OpenMP. If no flag is specified, it is assumed that the compiler does not support OpenMP. (default: None)
availability_option (Union[str, List[str], None]) – a command line option for the tool to test if the tool is available on the current system. Defaults to –version. (default: None)

property mpi: bool#

Returns:: whether this compiler supports MPI or not.

property openmp: bool#

Returns:: compiler’s OpenMP support.

property openmp_flag: str#

Returns:: compiler argument to enable OpenMP.

property compile_flag: str#

Returns:: the flag to indicate compilation only (not linking).

property output_flag: str#

Returns:: compiler argument for output file.

get_hash(profile=None)#

Return type:: int
Returns:: hash of compiler name and version.

get_flags(profile=None)#

Determines the flags to be used.

Return type:: List[str]
Returns:: the flags to be used with this tool.

get_all_commandline_options(config, input_file, output_file, add_flags=None)#

This function returns all command line options for a compiler (but not the executable name). It is used by a compiler wrapper to pass the right flags to the wrapper. This base implementation adds the input and output filename (including the -o flag), the flag to only compile (and not link), and if required openmp.

Parameters:

input_file (Path) – the name of the input file.
output_file (Path) – the name of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)

Return type:

List[str]

Returns:

all command line options for compilation.

compile_file(input_file, output_file, config, 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.
output_file (Path) – the path of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
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.

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, availability_option=None)#

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.
availability_option (Union[str, List[str], None]) – a command line option for the tool to test if the tool is available on the current system. Defaults to –version. (default: None)

property suite: str#

Returns:: the compiler suite of this tool.

class fab.tools.CompilerWrapper(name, exec_name, compiler, mpi=False)#

A decorator-based compiler wrapper. It basically uses a different executable name when compiling, but otherwise behaves like the wrapped compiler. An example of a compiler wrapper is mpif90 (which can internally call e.g. gfortran, icc, …)

Parameters:

name (str) – name of the wrapper.
exec_name (str) – name of the executable to call.
compiler (Compiler) – the compiler that is decorated.
mpi (bool) – whether MPI is supported by this compiler or not. (default: False)

property compiler: Compiler#

Returns:: the compiler that is wrapped by this CompilerWrapper.

property suite: str#

Returns:: the compiler suite of this tool.

property openmp_flag: str#: Returns the flag to enable OpenMP.

property has_syntax_only: bool#

Returns:: whether this compiler supports a syntax-only feature.
Raises:: RuntimeError – if this function is called for a non-Fortran wrapped compiler.

get_flags(profile=None)#

Return type:: List[str]
Returns:: the ProfileFlags for the given profile, combined from the wrapped compiler and this wrapper.
Parameters:: profile (Optional[str]) – the profile to use. (default: None)

set_module_output_path(path)#

Sets the output path for modules.

Params path:: the path to the output directory.
Raises:: RuntimeError – if this function is called for a non-Fortran wrapped compiler.

get_all_commandline_options(config, input_file, output_file, add_flags=None, syntax_only=False)#

This function returns all command line options for a compiler wrapper. The syntax_only flag is only accepted, if the wrapped compiler is a Fortran compiler. Otherwise, an exception will be raised.

Parameters:

input_file (Path) – the name of the input file.
output_file (Path) – the name of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)
syntax_only (Optional[bool]) – if set, the compiler will only do a syntax check (default: False)

Return type:

List[str]

Returns:

command line flags for compiler wrapper.

Raises:

RuntimeError – if syntax_only is requested for a non-Fortran compiler.

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

Compiles a file using the wrapper compiler.

Parameters:

input_file (Path) – the name of the input file.
output_file (Path) – the name of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)
syntax_only (Optional[bool]) – if set, the compiler will only do a syntax check (default: None)

class fab.tools.Cpp#: Class for cpp.

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

class fab.tools.Craycc(name='craycc-cc', exec_name='cc')#

Class for the native Cray C compiler. Since cc is actually a compiler wrapper, follow the naming scheme of a compiler wrapper and call it: craycc-cc.

Cray has two different compilers. Older ones have as version number:: Cray C : Version 8.7.0 Tue Jul 23, 2024 07:39:46
Newer compiler (several lines, the important one):: Cray clang version 15.0.1 (66f7391d6a03cf932f321b9f6b1d8612ef5f362c)

We use the beginning (“cray c”) to identify the compiler, which works for both cray c and cray clang. Then we ignore non-numbers, to reach the version number which is then extracted.

Parameters:

name (str) – name of this compiler. (default: 'craycc-cc')
exec_name (str) – name of the executable. (default: 'cc')

class fab.tools.CrayCcWrapper(compiler)#

Class for the Cray C compiler wrapper. We add ‘wrapper’ to the class name to make this class distinct from the Craycc compiler class

Parameters:: compiler (Compiler) – the compiler that the mpicc wrapper will use.

class fab.tools.Crayftn(name='crayftn-ftn', exec_name='ftn')#

Class for the native Cray Fortran compiler. Since ftn is actually a compiler wrapper, follow the naming scheme of Cray compiler wrapper and call it crayftn-ftn.

Parameters:

name (str) – name of this compiler. (default: 'crayftn-ftn')
exec_name (str) – name of the executable. (default: 'ftn')

class fab.tools.CrayFtnWrapper(compiler)#

Class for the Cray Fortran compiler wrapper. We add ‘wrapper’ to the class name to make this class distinct from the Crayftn compiler class.

Parameters:: compiler (Compiler) – the compiler that the ftn wrapper will use.

class fab.tools.Fcm#

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

Constructor.

This is class is extended by the FCM interface which is why name and executable are mutable.

Parameters:

name – Tool name, defaults to “subversion.”
exec_name – Tool executable, defaults to “svn.”
category – Tool category, defaults to SUBVERSION.

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.

add_flags(new_flags)#

Adds the specified flags to the list of flags.

Parameters:: new_flags (Union[str, List[str]]) – A single string or list of strings which are the flags to be added.

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, version_regex, mpi=False, compile_flag=None, output_flag=None, openmp_flag=None, version_argument=None, module_folder_flag=None, syntax_only_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.
version_regex (str) – A regular expression that allows extraction of the version number from the version output of the compiler.
mpi (bool) – whether MPI is supported by this compiler or not. (default: False)
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)
openmp_flag (Optional[str]) – the flag to use to enable OpenMP (default: None)
module_folder_flag (Optional[str]) – the compiler flag to indicate where to store created module files. (default: None)
syntax_only_flag (Optional[str]) – flag to indicate to only do a syntax check. The side effect is that the module files are created. (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.

get_all_commandline_options(config, input_file, output_file, add_flags=None, syntax_only=False)#

This function returns all command line options for a Fortran compiler (but not the executable name). It is used by a compiler wrapper to pass the right flags to the wrapper. This Fortran-specific implementation adds the module- and syntax-only flags (as required) to the standard compiler flags.

Parameters:

input_file (Path) – the name of the input file.
output_file (Path) – the name of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)
syntax_only (Optional[bool]) – if set, the compiler will only do a syntax check (default: False)

Return type:

List[str]

Returns:

all command line options for Fortran compilation.

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

Compiles a file. This basically re-implements compile_file of the base class, but passes the syntax_only flag in

Parameters:

input_file (Path) – the name of the input file.
output_file (Path) – the name of the output file.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
add_flags (Optional[List[str]]) – additional flags for the compiler. (default: None)
syntax_only (Optional[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', mpi=False)#

Class for GNU’s gcc compiler.

Parameters:

name (str) – name of this compiler. (default: 'gcc')
exec_name (str) – name of the executable. (default: 'gcc')
mpi (bool) – whether the compiler supports MPI. (default: False)

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')
mpi – whether the compiler supports MPI.

class fab.tools.Git#

Interface to Git version control system.

Constructor.

Parameters:

name – Display name of this tool.
exec_name – Executable for this tool.
category – Tool belongs to this category.

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')
mpi – whether the compiler supports MPI.

class fab.tools.Icx(name='icx', exec_name='icx')#

Class for the Intel’s new llvm based icx compiler.

Parameters:

name (str) – name of this compiler. (default: 'icx')
exec_name (str) – name of the executable. (default: 'icx')

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')
mpi – whether the compiler supports MPI.

class fab.tools.Ifx(name='ifx', exec_name='ifx')#

Class for Intel’s new ifx compiler.

Parameters:

name (str) – name of this compiler. (default: 'ifx')
exec_name (str) – name of the executable. (default: 'ifx')

class fab.tools.Linker(compiler, linker=None, name=None)#

This is the base class for any Linker. It takes an existing compiler instance as parameter, and optional another linker. The latter is used to get linker settings - for example, linker-mpif90-gfortran will use mpif90-gfortran as compiler (i.e. to test if it is available and get compilation flags), and linker-gfortran as linker. This way a user only has to specify linker flags in the most basic class (gfortran), all other linker wrapper will inherit the settings.

Parameters:

compiler (Compiler) – a compiler instance
linker (Optional[Linker]) – an optional linker instance (default: None)
name (Optional[str]) – name of the linker (default: None)

Raises:

RuntimeError – if both compiler and linker are specified.
RuntimeError – if neither compiler nor linker is specified.

check_available()#

Return type:: bool
Returns:: whether this linker is available by asking the wrapped linker or compiler.

property suite: str#

Returns:: the suite this linker belongs to by getting it from the wrapped compiler.

property mpi: bool#

Returns:: whether this linker supports MPI or not by checking with the wrapped compiler.

property openmp: bool#

Returns:: whether this linker supports OpenMP or not by checking with the wrapped compiler.

property output_flag: str#

Returns:: the flag that is used to specify the output name.

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.

Parameters:

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

get_profile_flags(profile)#

Return type:: List[str]
Returns:: the ProfileFlags for the given profile, combined from the wrapped compiler and this wrapper.
Parameters:: profile (str) – the profile to use.

get_lib_flags(lib)#

Gets the standard flags for a standard library

Parameters:: lib (str) – the library name
Return type:: List[str]
Returns:: a list of flags
Raises:: RuntimeError – if lib is not recognised

add_lib_flags(lib, flags, silent_replace=False)#

Add a set of flags for a standard library

Parameters:

lib (str) – the library name
flags (List[str]) – the flags to use with the library
silent_replace (bool) – if set, no warning will be printed when an existing lib is overwritten. (default: False)

add_pre_lib_flags(flags, profile=None)#

Add a set of flags to use before any library-specific flags

Parameters:: flags (List[str]) – the flags to include

add_post_lib_flags(flags, profile=None)#

Add a set of flags to use after any library-specific flags

Parameters:: flags (List[str]) – the flags to include

get_pre_link_flags(config)#

Returns the list of pre-link flags. It will concatenate the flags for this instance with all potentially wrapped linkers. This wrapper’s flag will come first - the assumption is that the pre-link flags are likely paths, so we need a wrapper to be able to put a search path before the paths from a wrapped linker.

Return type:: List[str]
Returns:: List of pre-link flags of this linker and all wrapped linkers

get_post_link_flags(config)#

Returns the list of post-link flags. It will concatenate the flags for this instance with all potentially wrapped linkers. This wrapper’s flag will be added to the end.

Return type:: List[str]
Returns:: List of post-link flags of this linker and all wrapped linkers

link(input_files, output_file, config, libs=None, add_flags=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.
config (BuildConfig) – The BuildConfig, from which compiler profile and OpenMP status are taken.
libs (Optional[List[str]]) – additional libraries to link with. (default: None)

Return type:

str

Returns:

the stdout of the link command

class fab.tools.Mpif90(compiler)#

Class for a simple wrapper for using a compiler driver (like mpif90) It will be using the name “mpif90-COMPILER_NAME” and calls mpif90. All flags from the original compiler will be used when using the wrapper as compiler.

Parameters:: compiler (Compiler) – the compiler that the mpif90 wrapper will use.

class fab.tools.Mpicc(compiler)#

Class for a simple wrapper for using a compiler driver (like mpicc) It will be using the name “mpicc-COMPILER_NAME” and calls mpicc. All flags from the original compiler will be used when using the wrapper as compiler.

Parameters:: compiler (Compiler) – the compiler that the mpicc wrapper will use.

class fab.tools.Nvc(name='nvc', exec_name='nvc')#

Class for Nvidia’s nvc compiler. Note that the ‘-’ in the Nvidia version number is ignored, e.g. 23.5-0 would return ‘23.5’.

Parameters:

name (str) – name of this compiler. (default: 'nvc')
exec_name (str) – name of the executable. (default: 'nvc')

class fab.tools.Nvfortran(name='nvfortran', exec_name='nvfortran')#

Class for Nvidia’s nvfortran compiler. Note that the ‘-’ in the Nvidia version number is ignored, e.g. 23.5-0 would return ‘23.5’.

Parameters:

name (str) – name of this compiler. (default: 'nvfortran')
exec_name (str) – name of the executable. (default: 'nvfortran')

class fab.tools.Preprocessor(name, exec_name, category, availability_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[str, Path]]]) – List with additional flags to be used. (default: None)

class fab.tools.ProfileFlags#

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.

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 (Optional[str]) – 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 (Union[str, List[str]]) – A single string or list of strings which are the flags to be added.

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(profile=None)#

Return type:: str
Returns:: a checksum of the flags.

class fab.tools.Psyclone#

This is the base class for PSyclone.

check_available()#

This function determines if PSyclone is available. Additionally, it established the version, since command line option changes significantly from python 2.5.0 to the next release.

Return type:: bool

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

Run PSyclone with the specified parameters. If PSyclone is used to transform existing Fortran files, api must be None, and the output file name is transformed_file. If PSyclone is using its DSL features, api must be a valid PSyclone API, and the two output filenames are psy_file and alg_file.

Parameters:

api (Optional[str]) – the PSyclone API. (default: None)
x90_file (Path) – the input file for PSyclone
psy_file (Optional[Path]) – the output PSy-layer file. (default: None)
alg_file (Union[Path, str, None]) – the output modified algorithm file. (default: None)
transformed_file (Optional[Path]) – the output filename if PSyclone is called as transformation tool. (default: None)
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[str, Path]]]) – 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.Shell(name)#

A simple wrapper that runs a shell script. There seems to be no consistent way to simply check if a shell is working - not only support a version command (e.g. sh and dash don’t). Instead, availability is tested by running a simple ‘echo’ command.

Name:: the path to the script to run.

exec(command)#

Executes the specified command.

Parameters:: command (Union[str, List[Union[str, Path]]]) – the command and potential parameters to execute.
Return type:: str
Returns:: stdout of the result.

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

Interface to the Subversion version control system.

Constructor.

This is class is extended by the FCM interface which is why name and executable are mutable.

Parameters:

name (Optional[str]) – Tool name, defaults to “subversion.” (default: None)
exec_name (Union[Path, str, None]) – Tool executable, defaults to “svn.” (default: None)
category (Category) – Tool category, defaults to SUBVERSION. (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, availability_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: 13>)
availability_option (Union[str, List[str], None]) – a command line option for the tool to test if the tool is available on the current system. Defaults to –version. (default: None)

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.

set_full_path(full_path)#

This function adds the full path to a tool. This allows tools to be used that are not in the user’s PATH. The ToolRepository will automatically update the path for a tool if the user specified a full path.

Parameters:: full_path (Path) – the full path to the executable.

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_path: Path#

Returns:: the path of the executable.

property exec_name: str#

Returns:: the name of the executable.

property name: str#

Returns:: the name of the tool.

property availability_option: str | List[str]#

Returns:: the option to use to check if the tool is available.

property category: Category#

Returns:: the category of this tool.

get_flags(profile=None)#

Returns:: the flags to be used with this tool.

add_flags(new_flags, profile=None)#

Adds the specified flags to the list of flags.

Parameters:: new_flags (Union[str, List[str]]) – A single string or list of strings which are the flags to be added.

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.

Parameters:

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

property logger: Logger#

Returns:: a logger object for convenience.

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

Run the binary as a subprocess.

Parameters:

additional_parameters (Union[str, Sequence[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:

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, mpi=None, openmp=None)#

Returns the tool for the specified category.

Parameters:

category (Category) – the name of the category in which to look for the tool.
mpi (Optional[bool]) – if no compiler or linker is explicitly specified in this tool box, use the MPI and OpenMP setting to find an appropriate default from the tool repository. (default: None)
mpi – if no compiler or linker is explicitly specified in this tool box, use the MPI and OpenMP setting to find an appropriate default from the tool repository.

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

Creates an instance of the specified class and adds it to the tool repository. If the tool is a compiler, it automatically adds the compiler as a linker as well (named “linker-{tool.name}”).

Parameters:: tool (Tool) – the tool to add.

get_tool(category, name)#

This functions returns a tool with a given name. The name can either be a Fab compiler name (including wrapper naming), e.g. mpif90-gfortran, or linker-mpif90-ifort, or just the name of the executable (mpif90). If a Fab name is specified, the corresponding tool will be returned, even if it should not be available (allowing default site scripts to setup any compiler, even if they are not available everywhere). If an exec name is specified, the tool must be available. This is required to make sure the user gets the right tool: by specifying just mpif90, it is not clear if the user wants mpif90-ifort, mpif90-gfortran, … . But only one of these tools will actually be available (the wrapper checks the version number to detect the compiler-vendor).

The name can also be specified using an absolute path, in which case only the stem will be used to look up the name, but the returned tool will be updated to use the full path to the tool. This allows the usage of e.g. compilers that are not in $PATH of the user.

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. A full path can be used, in which case only the stem of the path is used, and the tool will be updated to use the absolute path specified.

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, mpi=None, openmp=None)#

Returns the default tool for a given category that is available. For most tools that will be the first entry in the list of tools. The exception are compilers and linker: in this case it must be specified if MPI support is required or not. And the default return will be the first tool that either supports MPI or not.

Parameters:

category (Category) – the category for which to return the default tool.
mpi (Optional[bool]) – if a compiler or linker is required that supports MPI. (default: None)
openmp (Optional[bool]) – if a compiler or linker is required that supports OpenMP. (default: None)

Raises:

KeyError – if the category does not exist.
RuntimeError – if no tool in the requested category is available on the system.
RuntimeError – if no compiler/linker is found with the requested level of MPI support (yes or no).

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

Base class for versioning tools like Git and Subversion.

Constructor.

Parameters:

name (str) – Display name of this tool.
exec_name (Union[str, Path]) – Executable for this tool.
category (Category) – Tool belongs to this category.

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
`compiler_wrapper`	This file contains the base class for any compiler-wrapper, including the derived classes for mpif90, mpicc, and CrayFtnWrapper and CrayCcWrapper.
`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.
`shell`	This file contains a base class for shells.
`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`	Versioning tools such as Subversion and Git.

fab.tools#

This Page