fab.api#

This module allows any application to import all required functions from fab to be imported independent of the location of the files using from fab.api import ….

class fab.api.AddFlags(match, flags)#

Add command-line flags when our path filter matches. Generally used inside a FlagsConfig.

Parameters:

match (str) – The string to match against each file path.
flags (List[str]) – The command-line flags to add for matching files.

Both the match and flags arguments can make use of templating:

$source for <project workspace>/source
$output for <project workspace>/build_output
$relative for <the source file’s folder>

For example:

# For source in the um folder, add an absolute include path
AddFlags(match="$source/um/*", flags=['-I$source/include']),

# For source in the um folder, add an include path relative to
# each source file.
AddFlags(match="$source/um/*", flags=['-I$relative/include']),

run(fpath, input_flags, config)#

Check if our filter matches a given file. If it does, add our flags.

Parameters:

fpath (Path) – Filepath to check.
input_flags (List[str]) – The list of command-line flags Fab is building for this file.
config – Contains the folders for templating $source and $output.

fab.api.analyse(config, source=None, root_symbol=None, find_programs=False, std='f2008', special_measure_analysis_results=None, unreferenced_deps=None, ignore_dependencies=None)#

Produce one or more build trees by analysing source code dependencies.

The resulting artefact collection is a mapping from root symbol to build tree. The name of this artefact collection is taken from fab.artefacts.ArtefactSet.BUILD_TREES.

If no artefact getter is specified in source, a default is used which provides input files from multiple artefact collections, including the default C and Fortran preprocessor outputs and any source files with a ‘little’ .f90 extension.

A build tree is produced for every root symbol specified in root_symbol, which can be a string or list of. This is how we create executable files. If no root symbol is specified, a single tree of the entire source is produced (with a root symbol of None). This is how we create shared and static libraries.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
source (ArtefactsGetter | None) – An ArtefactsGetter to get the source files. (default: None)
find_programs (bool) – Instructs the analyser to automatically identify program definitions in the source. Alternatively, the required programs can be specified with the root_symbol argument. (default: False)
root_symbol (str | List[str] | None) – When building an executable, provide the Fortran Program name(s), or ‘main’ for C. If None, build tree extraction will not be performed and the entire source will be used as the build tree - for building a shared or static library. (default: None)
std (str) – The fortran standard, passed through to fparser2. Defaults to ‘f2008’. (default: 'f2008')
special_measure_analysis_results (Iterable[FortranParserWorkaround] | None) – When a language parser cannot parse a valid source file, we can manually provide the expected analysis results with this argument. (default: None)
unreferenced_deps (Iterable[str] | None) – A list of symbols which are needed for the build, but which cannot be automatically determined by Fab. For example, functions that are called in a one-line if statement. Assuming the files containing these symbols are present and analysed, those files and all their dependencies will be added to the build tree(s). (default: None)
ignore_dependencies (Iterable[str] | None) – Third party Fortran module names in USE statements, ‘DEPENDS ON’ files and modules to be ignored. (default: None)

fab.api.archive_objects(config, source=None, output_fpath=None, output_collection=ArtefactSet.OBJECT_ARCHIVES)#

Create an object archive for every build target, from their object files.

An object archive is a set of object (.o) files bundled into a single file, typically with a .a extension.

Expects one or more build targets from its artefact getter, of the form Dict[name, object_files]. By default, it finds the build targets and their object files in the artefact collection named by fab.constants.COMPILED_FILES.

This step has three use cases:

The object archive is the end goal of the build.
The object archive is a convenience step before linking a shared object.
One or more object archives as convenience steps before linking executables.

The benefit of creating an object archive before linking is simply to reduce the size of the linker command, which might otherwise include thousands of .o files, making any error output difficult to read. You don’t have to use this step before linking. The linker step has a default artefact getter which will work with or without this preceding step.

Creating a Static or Shared Library:

When building a library there is expected to be a single build target with a None name. This typically happens when configuring the Analyser step without a root symbol. We can assume the list of object files is the entire project source, compiled.

In this case you must specify an output_fpath.

Creating Executables:

When creating executables, there is expected to be one or more build targets, each with a name. This typically happens when configuring the Analyser step with a root symbol(s). We can assume each list of object files is sufficient to build each <root_symbol> executable.

In this case you cannot specify an output_fpath path because they are automatically created from the target name.

Parameters:

config (BuildConfig) – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
source (ArtefactsGetter | None) – An ArtefactsGetter which give us our lists of objects to archive. The artefacts are expected to be of the form Dict[root_symbol_name, list_of_object_files]. (default: None)
output_fpath (Path | None) –
The file path of the archive file to create. This string can include templating, where “$output” is replaced with the output folder.
- Must be specified when building a library file (no build target name).
- Must not be specified when building linker input (one or more build target names). (default: None)
output_collection – The name of the artefact collection to create. Defaults to the name in fab.artefacts.ArtefactSet.OBJECT_ARCHIVES. (default: <ArtefactSet.OBJECT_ARCHIVES: 11>)

class fab.api.ArtefactSet(*values)#: A simple enum with the artefact types used internally in Fab.

class fab.api.BuildConfig(project_label, tool_box, mpi=False, openmp=False, profile=None, multiprocessing=True, n_procs=None, reuse_artefacts=False, fab_workspace=None, two_stage=False, verbose=False)#

Contains and runs a list of build steps.

The user is not expected to instantiate this class directly, but rather through the build_config() context manager.

Parameters:

project_label (str) – Name of the build project. The project workspace folder is created from this name, with spaces replaced by underscores.
tool_box (AbstractToolBox) – The ToolBox with all tools to use in the build.
mpi (bool) – whether the project uses MPI or not. This is used to pick a default compiler (if none is explicitly set in the ToolBox), and controls PSyclone parameters. (default: False)
openmp (bool) – as with mpi, this controls whether the project is using OpenMP or not. This is used to pick a default compiler (if none is explicitly set in the ToolBox). The compiler-specific flag to enable OpenMP will automatically be added when compiling and linking. (default: False)
profile (str | None) – the name of a compiler profile to use. (default: None)
multiprocessing (bool) – An option to disable multiprocessing to aid debugging. (default: True)
n_procs (int | None) – The number of cores to use for multiprocessing operations. Defaults to the number of available cores. (default: None)
reuse_artefacts (bool) – A flag to avoid reprocessing certain files on subsequent runs. WARNING: Currently unsophisticated, this flag should only be used by Fab developers. The logic behind flag will soon be improved, in a work package called “incremental build”. (default: False)
fab_workspace (Path | None) – Overrides the FAB_WORKSPACE environment variable. If not set, and FAB_WORKSPACE is not set, the fab workspace defaults to ~/fab-workspace. (default: None)
two_stage (bool) – Compile .mod files first in a separate pass. Theoretically faster in some projects. (default: False)
verbose (bool) – DEBUG level logging. (default: False)

add_current_prebuilds(artefacts)#: Mark the given file paths as being current prebuilds, not to be cleaned during housekeeping.

property artefact_store: ArtefactStore#

Returns:: the Artefact instance for this configuration.

property build_output: Path#

Returns:: the build output path.

property mpi: bool#

Returns:: whether MPI is requested or not in this config.

property openmp: bool#

Returns:: whether OpenMP is requested or not in this config.

property profile: str#

Returns:: the name of the compiler profile to use.

property project_workspace: Path#

Returns:: the project workspace path.

property tool_box: AbstractToolBox#

Returns:: the tool box to use.

class fab.api.Category(*values)#

This class defines the allowed tool categories.

property is_compiler#: Returns if the category is either a C or a Fortran compiler.

fab.api.cleanup_prebuilds(config, older_than=None, n_versions=0, all_unused=None)#

A step to delete old files from the local incremental/prebuild folder.

Assumes prebuild filenames follow the pattern: <stem>.<hash>.<suffix>.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
older_than (timedelta | None) – Delete prebuild artefacts which are n seconds older than the last prebuild access time. (default: None)
n_versions (int) – Only keep the most recent n versions of each artefact <stem>.*.<suffix> (default: 0)
all_unused (bool | None) – Delete everything which was not part of the current build. (default: None)

If no parameters are specified then all_unused will default to True.

class fab.api.CollectionGetter(collection_name)#

A simple artefact getter which returns one Artefact Collection from the artefact_store.

Example:

`CollectionGetter('preprocessed_fortran')`

Parameters:: collection_name (str | ArtefactSet) – The name of the artefact collection to retrieve.

fab.api.common_arg_parser()#

A helper function returning an argument parser with common, useful arguments controlling command line tools.

More arguments can be added. The caller must call parse_args on the returned parser.

Return type:: ArgumentParser

class fab.api.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 (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 (str | None) – the compilation flag to use when only requesting compilation (not linking). (default: None)
output_flag (str | None) – the compilation flag to use to indicate the name of the output file (default: None)
openmp_flag (str | None) – 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 (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()#

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.

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 (None | List[str]) – additional compiler flags. (default: None)

property compile_flag: str#

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

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 (None | List[str]) – additional flags for the compiler. (default: None)

Return type:

List[str]

Returns:

all command line options for compilation.

get_flags(profile=None)#

Determines the flags to be used.

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

get_hash(profile=None)#

Return type:: int
Returns:: hash of compiler name and 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.

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.

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 output_flag: str#

Returns:: compiler argument for output file.

run_version_command(version_command='--version')#

Run the compiler’s command to get its version.

Parameters:: version_command (str | None) – 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.

class fab.api.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)

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 (None | List[str]) – additional flags for the compiler. (default: None)
syntax_only (bool | None) – if set, the compiler will only do a syntax check (default: None)

property compiler: Compiler#

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

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 (None | List[str]) – additional flags for the compiler. (default: None)
syntax_only (bool | None) – 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.

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 (str | None) – the profile to use. (default: None)

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.

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

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.

property suite: str#

Returns:: the compiler suite of this tool.

fab.api.compile_c(config, common_flags=None, path_flags=None, source=None)#

Compiles all C files in all build trees, creating or extending a set of compiled files for each target.

This step uses multiprocessing. All C files are compiled in a single pass.

Uses multiprocessing, unless disabled in the config.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
common_flags (List[str] | None) – A list of strings to be included in the command line call, for all files. (default: None)
path_flags (List | None) – A list of AddFlags, defining flags to be included in the command line call for selected files. (default: None)
source (ArtefactsGetter | None) – An ArtefactsGetter which give us our c files to process. (default: None)

fab.api.compile_fortran(config, common_flags=None, path_flags=None, source=None)#

Compiles all Fortran files in all build trees, creating/extending a set of compiled files for each build target.

Files are compiled in multiple passes, with each pass enabling further files to be compiled in the next pass.

Uses multiprocessing, unless disabled in the config.

Parameters:

config (BuildConfig) – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
common_flags (List[str] | None) – A list of strings to be included in the command line call, for all files. (default: None)
path_flags (List | None) – A list of AddFlags, defining flags to be included in the command line call for selected files. (default: None)
source (ArtefactsGetter | None) – An ArtefactsGetter which gives us our Fortran files to process. (default: None)

fab.api.c_pragma_injector(config, source=None, output_name=None)#

A build step to inject custom pragmas to mark blocks of user and system include statements.

By default, reads .c files from the INITIAL_SOURCE_FILES artefact and creates the pragmad_c artefact.

This step does not write to the build output folder, it creates the pragmad c in the same folder as the c file. This is because a subsequent preprocessing step needs to look in the source folder for header files, including in paths relative to the c file.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
source (ArtefactsGetter | None) – An ArtefactsGetter which give us our c files to process. (default: None)
output_name – The name of the artefact collection to create in the artefact store, with a sensible default (default: None)

class fab.api.Exclude(*filter_strings)#

A path filter which excludes matching paths, this convenience class improves config readability.

Parameters:: filter_strings – One or more strings to be used as pattern matches.

fab.api.fcm_export(config, src, dst_label=None, revision=None)#: Params as per svn_export().

fab.api.file_checksum(fpath)#

Return a checksum of the given file.

This function is deterministic, returning the same result across Python invocations.

We use crc32 for now because it’s deterministic, unlike out-the-box hash. We could seed hash with a non-random or look into hashlib, if/when we want to improve this.

fab.api.get_fab_workspace()#

Read the Fab workspace from the FAB_WORKSPACE environment variable, defaulting to ./fab-workspace.

Return type:: Path

fab.api.git_checkout(config, src, dst_label='', revision=None)#: Checkout or update a Git repo.

fab.api.grab_folder(config, src, dst_label='')#

Copy a source folder to the project workspace.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
src (Path | str) – The source location to grab. The nature of this parameter is depends on the subclass.
dst_label (str) – The name of a sub folder, in the project workspace, in which to put the source. If not specified, the code is copied into the root of the source folder. (default: '')

fab.api.grab_pre_build(config, path, allow_fail=False)#: Copy the contents of another project’s prebuild folder into our local prebuild folder.

fab.api.find_source_files(config, source_root=None, output_collection=ArtefactSet.INITIAL_SOURCE_FILES, path_filters=None)#

Find the files in the source folder, with filtering.

Files can be included or excluded with simple pattern matching. Every file is included by default, unless the filters say otherwise.

Path filters are expected to be provided by the user in an ordered collection. The two convenience subclasses, Include and Exclude, improve readability.

Order matters. For example:

path_filters = [
    Exclude('my_folder'),
    Include('my_folder/my_file.F90'),
]

In the above example, swapping the order would stop the file being included in the build.

A path matches a filter string simply if it contains it, so the path my_folder/my_file.F90 would match filters “my_folder”, “my_file” and “er/my”.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
source_root – Optional path to source folder, with a sensible default. (default: None)
output_collection – Name of artefact collection to create, with a sensible default. (default: <ArtefactSet.INITIAL_SOURCE_FILES: 1>)
path_filters (Iterable[_PathFilter] | None) – Iterable of Include and/or Exclude objects, to be processed in order. (default: None)
name – Human friendly name for logger output, with sensible default.

class fab.api.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.api.Include(*filter_strings)#

A path filter which includes matching paths, this convenience class improves config readability.

Parameters:: filter_strings – One or more strings to be used as pattern matches.

fab.api.input_to_output_fpath(config, input_path)#

Convert a path in the project’s source folder to the equivalent path in the output folder.

Allows the given path to already be in the output folder.

Parameters:

config – The config object, which defines the source and output folders.
input_path (Path) – The path to transform from input to output folders.

Note: This function can also handle paths which are not in the project workspace at all. This can happen when pointing the FindFiles step elsewhere, for example. In that case, the entire path will be made relative to the source folder instead of its anchor.

class fab.api.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 (Linker | None) – an optional linker instance (default: None)
name (str | None) – name of the linker (default: None)

Raises:

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

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_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

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

check_available()#

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

property compiler: Compiler#

Returns:: the wrapped compiler.

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 (str | None) – Optional name of a profile to inherit settings from. (default: None)

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

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

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

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 (List[str] | None) – additional libraries to link with. (default: None)

Return type:

str

Returns:

the stdout of the link command

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.

property suite: str#

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

fab.api.link_exe(config, libs=None, flags=None, source=None)#

Link object files into an executable for every build target.

Expects one or more build targets from its artefact getter, of the form Dict[name, object_files].

The default artefact getter, DefaultLinkerSource, looks for any output from an ArchiveObjects step, and falls back to using output from compiler steps.

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
libs (List[str] | None) – A list of required library names to pass to the linker. (default: None)
flags (List[str] | None) – A list of additional flags to pass to the linker. (default: None)
source (ArtefactsGetter | None) – An optional ArtefactsGetter. It defaults to the output from compiler steps, which typically is the expected behaviour. (default: None)

Return type:

None

fab.api.link_shared_object(config, output_fpath, flags=None, source=None)#

Produce a shared object (.so) file from the given build target.

Expects a single build target from its artefact getter, of the form Dict[None, object_files]. We can assume the list of object files is the entire project source, compiled.

Params are as for LinkerBase, with the addition of:

Parameters:

config – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
output_fpath (str) – File path of the shared object to create.
flags (List[str] | None) – A list of flags to pass to the linker. (default: None)
source (ArtefactsGetter | None) – An optional ArtefactsGetter. Typically not required, as there is a sensible default. (default: None)

fab.api.log_or_dot(logger, msg)#: Util function which prints a fullstop without a newline, except in debug logging where it logs a message.

fab.api.preprocess_c(config, source=None, **kwargs)#

Wrapper to pre_processor for C files.

Params as per _pre_processor(). If source is not provided, it defaults to DefaultCPreprocessorSource.

fab.api.preprocess_fortran(config, source=None, **kwargs)#

Wrapper to pre_processor for Fortran files.

Ensures all preprocessed files are in the build output. This means copying already preprocessed files from source to build output.

Params as per _pre_processor().

If source is not provided, it defaults to SuffixFilter(ArtefactStore.FORTRAN_BUILD_FILES, ‘.F90’).

fab.api.psyclone(config, kernel_roots=None, transformation_script=None, cli_args=None, source_getter=None, overrides_folder=None, api=None, ignore_dependencies=None)#

PSyclone runner step.

Note

This step produces Fortran, so it must be run before the Analyse step.

This step stores prebuilt results to speed up subsequent builds. To generate the prebuild hashes, it analyses the X90 and kernel files, storing prebuilt results for these also.

Kernel files are just normal Fortran, and the standard Fortran analyser is used to analyse them

Parameters:

config (BuildConfig) – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
kernel_roots (List[Path] | None) – Folders containing kernel files. Must be part of the analysed source code. (default: None)
transformation_script (Callable[[Path, BuildConfig], Path] | None) – The function to get Python transformation script. It takes in a file path and the config object, and returns the path of the transformation script or None. If no function is given or the function returns None, no script will be applied and PSyclone still runs. (default: None)
cli_args (List[str] | None) – Passed through to the psyclone cli tool. (default: None)
source_getter (ArtefactsGetter | None) – Optional override for getting input files from the artefact store. (default: None)
overrides_folder (Path | None) – Optional folder containing hand-crafted override files. Must be part of the subsequently analysed source code. Any file produced by psyclone will be deleted if there is a corresponding file in this folder. (default: None)
ignore_dependencies (Iterable[str] | None) – Third party Fortran module names in USE statements, ‘DEPENDS ON’ files and modules to be ignored. (default: None)

fab.api.root_inc_files(config, suffix_list=None)#

Copy include files with a specific suffix into the workspace output root.

Checks for name clash. This step does not create any artefacts, nor does it add a search path. It is up to the user to configure other tools to find these files.

Parameters:

config (BuildConfig) – The fab.build_config.BuildConfig object where we can read settings such as the project workspace folder or the multiprocessing flag.
suffix_list (str | List[str] | None) – List of all suffixes to be copied (or a single suffix as string). Note that the . MUST be included (e.g. .h90). Defaults to .inc (default: None)

fab.api.run_mp(config, items, func, no_multiprocessing=False)#

Called from Step.run() to process multiple items in parallel.

For example, a compile step would, in its run() method, find a list of source files in the artefact store. It could then pass those paths to this method, along with a function to compile a single file. The whole set of results are returned in a list-like, with undefined order.

Parameters:

items – An iterable of items to process in parallel.
func – A function to process a single item. Must accept a single argument.
no_multiprocessing (bool) – Overrides the config’s multiprocessing flag, disabling multiprocessing for this call. (default: False)

fab.api.step(func)#: Function decorator for steps.

class fab.api.SuffixFilter(collection_name, suffix)#

Returns the file paths in a Artefact Collection (expected to be an iterable), filtered by suffix.

Example:

# The default source getter for the FortranPreProcessor step.
DEFAULT_SOURCE = SuffixFilter(ArtefactSet.INITIAL_SOURCE_FILES, '.F90')

Parameters:

collection_name (str | ArtefactSet) – The name of the artefact collection.
suffix (str | List[str]) – A suffix string including the dot, or iterable of.

class fab.api.TimerLogger(label, res=0.001)#: A labelled timing context manager which logs the label and the time taken.

class fab.api.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 (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 (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)

add_flags(new_flags, profile=None)#

Adds the specified flags to the list of flags.

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

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.

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.

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 (str | None) – Optional name of a profile to inherit settings from. (default: None)

property exec_name: str#

Returns:: the name of the executable.

property exec_path: Path#

Returns:: the path of the executable.

get_flags(profile=None)#

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

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 logger: Logger#

Returns:: a logger object for convenience.

property name: str#

Returns:: the name of the tool.

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

Run the binary as a subprocess.

Parameters:

additional_parameters (str | Sequence[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 (Dict[str, str] | None) – 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

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.

class fab.api.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, enforce_fortran_linker=None)#

Returns the tool for the specified category.

Parameters:

category (Category) – the name of the category in which to look for the tool.
mpi (bool | None) – 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.
enforce_fortran_linker (bool | None) – if a linker is request, this flag is used to specify if a Fortran-based linker is required. Otherwise, a C-based linker will be returned. (default: None)

Raises:

KeyError – if the category is not known.

Return type:

Tool

has(category)#

Return type:: bool
Returns:: whether this tool box has a tool of the specified category or not.

class fab.api.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_default(category, mpi=None, openmp=None, enforce_fortran_linker=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 (bool | None) – if a compiler or linker is required that supports MPI. (default: None)
openmp (bool | None) – if a compiler or linker is required that supports OpenMP. (default: None)
enforce_fortran_linker (bool | None) – if a linker is request, this flag is used to specify if a Fortran-based linker is required. Otherwise, a C-based linker will be returned. (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).

Return type:

Tool

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.

fab.api#

This Page