.. _gendata:

Generator Customization
=======================

Because semiwrap's code generation is intended to be a semi-automated
process (except for simple C++ code), a rich set of per-{class/function/parameter}
configuration options can be specified in per-file YAML configurations.

Additionally, some headers are too complex for the autogenerator to
completely process, so when this occurs you must manually specify required
information in the YAML file.

Most files generated by semiwrap are customizable.

.. note:: semiwrap is designed for the RobotPy project and may contain
          defaults that aren't appropriate for all projects. If you find that
          you need more customization, file an issue on github and let's talk
          about it!

Location of customization file
------------------------------

By default customization files are located in the ``semiwrap`` directory. The name
of the YAML file is the ``key`` in the extension module headers table:

.. code-block:: toml

   [tool.semiwrap.extension_modules."PACKAGE.NAME".headers]
   # yaml file is `semiwrap/demo.yml`
   demo = "include/demo.h"


Autogeneration
--------------

The default values for these YAML files should be generated via the semiwrap command
line tool:

.. code-block:: sh

   semiwrap update-yaml --write

This can be a good way to get the boilerplate out of the way when you need to
provide customizations.

Manual pybind11 APIs
--------------------

You can write your own custom .cpp files and add them to the python extensions
generated by semiwrap. In your ``meson.build`` after you include the generated
``semiwrap`` subdir, add files to ``NAME_sources``.

.. code-block:: meson

   subdir('semiwrap')

   my_module_sources += files(
      'src/my_module/main.cpp',
   )


Reference
---------

The following strctures describe the dictionaries that are read from the YAML
files. The toplevel structure is :class:`.AutowrapConfigYaml`.

.. automodule:: semiwrap.config.autowrap_yml
   :members: