Generated CLib Headers#

Caution

The YAML configuration for the sourcegen utility is an experimental part of Cantera and may be changed without notice.

The folder interfaces/sourcegen/src/sourcegen/headers holds YAML configuration files for code generation. Code generation uses output of the Doxygen code documentation tool for information on function declarations as well as C++ docstrings. The collected information represents annotated CLib functions that form the basis for specific APIs generated by sourcegen.

Header Specification Files#

Each YAML file contains information for CLib headers that implement functions and methods built around a specific Cantera class. The following fields are supported:

  • docstring: Used as part of the docstring of the generated API file.

  • prefix: Prefix used for CLib functions.

  • base: Base class of the CLib library; examples: Solution, ThermoPhase. Stand-alone functions defined in the Cantera namespace use "" as a base.

  • parents: List of class parents; used to locate C++ methods (default: []).

  • derived: Dictionary of derived classes and alternative prefixes. Used to locate C++ methods and to better differentiate CLib method names (default: {}).

  • recipes: List of CLib recipes (see below).

CLib Function Types#

The sourcegen utility implements logic to automatically detect CLib functions types based on a recipe, which is subsequently used to scaffold API functions using dedicated Jinja templates. The following recipe/CLib function types are differentiated:

  • function: Regular function defined in the Cantera namespace.

  • constructor: A CLib constructor adds new C++ objects to CLib storage. Constructor names should start with new. As all objects are handled via smart shared_ptr<>, CLib constructors require C++ utility functions that return a pointer to a new object. Constructors with the name new will use the C++ default constructor.

  • accessor: A CLib accessor adds existing or spawned C++ objects to CLib storage.

  • destructor: A CLib destructor removes a C++ object from CLib. Destructor names should start with del.

  • getter: Implements a getter method of a C++ class.

  • setter: Implements a setter method of a C++ class.

  • method: Generic method of a C++ class.

  • variable-getter: Implements a getter for a C++ class member variable or a variable defined in the Cantera namespace. Functionality is inferred automatically.

  • variable-setter: Implements a getter for a C++ class member variable or a variable defined in the Cantera namespace. Field disambiguates from a variable-getter.

  • noop: No operation.

  • reserved: Reserved (hard-coded) CLib functions which include service functions for CLib storage (examples: cabinetSize, parentHandle) or functions that do not have a C++ equivalent (example: getCanteraError).

Function Recipes#

Recipes include all information required for the auto-generation of a corresponding CLib function. Each YAML recipe uses the following fields:

  • name: Name of the CLib function to be generated (without prefix).

  • brief: Optional override for brief description from Doxygen documentation.

  • what: Optional override for auto-detected recipe/CLib function type.

  • wraps: Optional name or signature of the implemented C++ function/method or variable. If left empty, sourcegen searches for Doxygen tags matching the name field. A name is sufficient if C++ functions/methods are unique, for example Func1::type. A signature is required whenever shortened signatures with default arguments are used and/or multiple C++ function/method variants exist, for example Phase::moleFraction(size_t). The scope (part preceding ::) may be omitted, as it can be inferred based on the fields base, parents or derived.

  • uses: Optional list of auxiliary C++ class methods used by the CLib function. The exact usage depends on the type of the implemented CLib function.

For custom code, additional fields are required to replace generated information:

  • declaration: Full CLib declaration.

  • parameters: Mapping of parameter doc-strings.

  • returns: Return doc-string.

  • code: Custom code to be executed.

CLib Header Generator#

The CLib header generator is located in the interfaces/sourcegen/src/sourcegen/headers folder.

Configuration#

The YAML file config.yaml within the headers folder contains configuration options specific to the CLib interface. Configuration options are static unless new CLib modules need to be implemented (see section Extending the CLib API).

  • Generic Options: As the CLib interface follows directly from Header Specification Files, override options defined by ignore_files and ignore_funcs are not needed. While the options are available, they should only be used for testing purposes and otherwise be left at their default values (empty).

  • Type Crosswalks: These fields map C++ types to their CLib equivalents.

    • ret_type_crosswalk: Specifies the types returned by C++ functions and methods.

    • par_type_crosswalk: Specifies the types passed as parameters in C++ functions and methods.

Implementation Details#

  • Header Specification Files: Definitions used for the CLib API.

  • Templates for Scaffolding: Templates, powered by Jinja, are used to scaffold elements of the CLib API. The following files define these templates:

    • templates.yaml: Defines code blocks within the header files.

  • Source Code: The implementation of the CLib header generator is contained in generator.py.

Extending the CLib Header API#

See Extending the CLib API.

On this page
Show Source