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 theSourceFileGenerator
at its creation; see Inline ConfigurationCommand-Line Options: The
SourceFileGenerator
parses the command line arguments of the generator script to set some of its configuration options; see Command-Line OptionsProject 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.
See also
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 toSfgConfig.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 toSfgConfig.extensions
.[--no]--sfg-header-only
: Enable or disable header-only code generation. Corresponds toSfgConfig.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.