fab.steps.analyse module#

Fab parses each C and Fortran file into an AnalysedDependent object which contains the symbol definitions and dependencies for that file.

From this set of analysed files, Fab builds a symbol table mapping symbols to their containing files.

Fab uses the symbol table to turn symbol dependencies into file dependencies (stored in the AnalysedDependent objects). This gives us a file dependency tree for the entire project source. The data structure is simple, just a dict of <source path>: <analysed file>, where the analysed files’ dependencies are other dict keys.

If we’re building a library, that’s the end of the analysis process as we’ll compile the entire project source. If we’re building one or more executables, which happens when we use the root_symbol argument, Fab will extract a subtree from the entire dependency tree for each root symbol we specify.

Finally, the resulting artefact collection is a dict of these subtrees (“build trees”), mapping <root symbol>: <build tree>. When building a library, there will be a single tree with a root symbol of None.

Addendum: The language parsers Fab uses are unable to detect some kinds of dependency. For example, fparser can’t currently identify a call statement in a one-line if statement. We can tell Fab that certain symbols should have been included in the build tree using the unreferenced_deps argument. For every symbol we provide, its source file and dependencies will be added to the build trees.

Sometimes a language parser will crash while parsing a valid source file, even though the compiler can compile the file perfectly well. In this case we can give Fab the analysis results it should have made by passing FortranParserWorkaround objects into the special_measure_analysis_results argument. You’ll have to manually read the file to determine which symbol definitions and dependencies it contains.

fab.steps.analyse.analyse(config, source=None, root_symbol=None, find_programs=False, std='f2008', special_measure_analysis_results=None, unreferenced_deps=None, ignore_mod_deps=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 (Optional[ArtefactsGetter]) – 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 (Union[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 (Optional[Iterable[FortranParserWorkaround]]) – 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 (Optional[Iterable[str]]) – 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_mod_deps (Optional[Iterable[str]]) – Third party Fortran module names to be ignored. (default: None)

  • name – Human friendly name for logger output, with sensible default.