Generator Script Configuration and Command-Line Interface#

There are several ways to affect the behavior and output of a generator script. For one, the SourceFileGenerator itself may be configured from the combination of three different configuration sources:

  • Inline Configuration: The generator script may set up an SfgConfig object, which is passed to the SourceFileGenerator at its creation; see Inline Configuration

  • Command-Line Options: The SourceFileGenerator parses the command line arguments of the generator script to set some of its configuration options; see Command-Line Options

  • Project Configuration: When embedded into a larger project, using a build system such as CMake, generator scripts may be configured globally within that project by the use of a configuration module. Settings specified inside that configuration module are always overridden by the two other configuration sources listed above. For details on configuration modules, refer to the guide on Project and Build System Integration.

Inline Configuration#

To configure the source file generator within your generator script, import the SfgConfig from pystencilssfg. You may then set up the configuration object before passing it to the SourceFileGenerator constructor. To illustrate, the following snippet alters the code indentation width and changes the output directory of the generator script to gen_src:

from pystencilssfg import SourceFileGenerator, SfgConfig

cfg = SfgConfig()
cfg.output_directory = "gen_src"
cfg.codestyle.indent_width = 4

with SourceFileGenerator(cfg) as sfg:
    ...

For a selection of common configuration options, see below. The inline configuration will override any values set by the project configuration and must not conflict with any command line arguments.

Configuration Options#

Here is a selection of common configuration options to be set in the inline configuration or project configuration.

Output Options#

The file extensions of the generated files can be modified through cfg.extensions.header and cfg.extensions.impl; and the output directory of the code generator can be set through cfg.output_directory. The header-only mode can be enabled using cfg.header_only.

Danger

When running generator scripts through CMake, the file extensions, output directory, and header-only mode settings will be managed fully by the pystencils-sfg CMake module and the (optional) project configuration module. They should therefore not be set in the inline configuration, as this will likely lead to errors being raised during code generation.

Outer Namespace#

To specify the outer namespace to which all generated code should be emitted, set cfg.outer_namespace.

Code Style and Formatting#

Pystencils-sfg gives you some options to affect its output code style. These are controlled by the options in the cfg.code_style category.

Furthermore, pystencils-sfg uses clang-format to beautify generated code. The behaviour of the clang-format integration is managed by the the cfg.clang_format category, where you can set options to skip or enforce formatting, or change the formatter binary. To set the code style used by clang-format either create a .clang-format file in any of the parent folders of your generator script, or modify the cfg.clang_format.code_style option.

Clang-format will, by default, sort #include statements alphabetically and separate local and system header includes. To override this, you can set a custom sorting key for #include sorting via cfg.code_style.includes_sorting_key.

Command-Line Options#

The SourceFileGenerator consumes a number of command-line parameters that may be passed to the script on invocation. These include:

  • --sfg-output-dir <path>: Set the output directory of the generator script. This corresponds to SfgConfig.output_directory.

  • --sfg-file-extensions <exts>: Set the file extensions used for the generated files; exts must be a comma-separated list not containing any spaces. Corresponds to SfgConfig.extensions.

  • [--no]--sfg-header-only: Enable or disable header-only code generation. Corresponds to SfgConfig.header_only.

If any configuration option is set to conflicting values on the command line and in the inline configuration, the generator script will terminate with an error.

You may examine the full set of possible command line parameters by invoking a generator script with the --help flag:

$ python kernels.py --help

Header-Only Mode#

When the header-only output mode is enabled, the code generator will emit only a header file and no separate implementation file. In this case, the composer will automatically place all function, method, and kernel definitions in the header file.

Header-only code generation can be enabled by setting the --header-only command-line flag or the SfgConfig.header_only configuration option.

Adding Custom Command-Line Options#

Sometimes, you might want to add your own command-line options to a generator script in order to affect its behavior from the shell, for instance by using argparse to set up an argument parser. If you parse your options directly from sys.argv, as parse_args does by default, your parser will also receive any options meant for the SourceFileGenerator. To filter these out of the argument list, pass the additional option keep_unknown_argv=True to your SourceFileGenerator. This will instruct it to store any unknown command line arguments into sfg.context.argv, where you can then retrieve them from and pass on to your custom parser:

from pystencilssfg import SourceFileGenerator
from argparse import ArgumentParser

parser = ArgumentParser()
# set up parser ...

with SourceFileGenerator(keep_unknown_argv=True) as sfg:
    args = parser.parse_args(sfg.context.argv)
    ...

Any SFG-specific arguments will already have been filtered out of this argument list. As a consequence of the above, if the generator script is invoked with a typo in some SFG-specific argument, which the SourceFileGenerator therefore does not recognize, that argument will be passed on to your downstream parser instead.

Important

If you do not pass on sfg.context.argv to a downstream parser, make sure that keep_unknown_argv is set to False (which is the default), such that typos or illegal arguments will not be ignored.