README.rst

February 28, 2026 · View on GitHub

################################################ Nunavut: DSDL transpiler ################################################

+--------------------------------+-----------------------------------+ | nox build (main) | |badge_build|_ | +--------------------------------+-----------------------------------+ | static analysis | |badge_analysis|_ |badge_issues|_ | +--------------------------------+-----------------------------------+ | unit test code coverage | |badge_coverage|_ | +--------------------------------+-----------------------------------+ | Python versions supported | |badge_pypi_support|_ | +--------------------------------+-----------------------------------+ | latest released version | |badge_pypi_version|_ | +--------------------------------+-----------------------------------+ | documentation | |badge_docs|_ | +--------------------------------+-----------------------------------+ | license | |badge_github_license|_ | +--------------------------------+-----------------------------------+ | community/support | |badge_forum|_ | +--------------------------------+-----------------------------------+

Nunavut is a source-to-source compiler (transpiler) that automatically converts OpenCyphal_ DSDL definitions into source code in a specified target programming language. It is constructed as a template engine that exposes a PyDSDL_ abstract syntax tree to Jinja2_ templates allowing authors to generate code, schemas, metadata, documentation, etc.

.. figure:: /docs/static/images/nunavut_pipeline.svg :width: 1000px

Nunavut DSDL transcompilation pipeline.

Nunavut ships with built-in support for some programming languages, and it can be used to generate code for other languages if custom templates (and some glue logic) are provided. Currently, the following languages are supported out of the box:

  • C11,c17,c23 (generates header-only libraries)
  • C++ (generates header-only libraries; the C++ support is currently experimental and may be removed or redesigned in the future)
  • Python (generates Python packages)
  • HTML (generates documentation pages)

Nunavut is named after the Canadian territory_. We chose the name because it is a beautiful word to say and read.

Installation

Nunavut depends on PyDSDL_.

Install from PIP::

pip install -U nunavut

Examples

The examples do not replace the documentation, please do endeavor to read it.

Generate C headers using the command-line tool

This example assumes that the public regulated namespace directories uavcan reside under public_regulated_data_types/. Nunavut is invoked to generate code for the former.

.. code-block:: shell

nnvg --target-language c --enable-serialization-asserts public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan

Generate HTML documentation pages using the command-line tool

See above assumptions. The below commands generate documentation for the reg namespace.

as well, because there are types in reg that will link to uavcan documentation sections.

.. code-block:: shell

nnvg --experimental-languages --target-language html public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan

Note that using the --lookup-dir option will only generate types under uavcan that are referenced by types in reg. To generate all types in both directories simply target each namespace.

.. code-block:: shell

nnvg --experimental-languages --target-language html public_regulated_data_types/reg public_regulated_data_types/uavcan

Generate Python packages using the command-line tool

This example assumes that the public regulated namespace directories reg and uavcan reside under public_regulated_data_types/. Nunavut is invoked to generate code for the former.

.. code-block:: shell

nnvg --target-language py public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan

Use custom templates

Partial example: generating a C struct

.. code-block:: jinja

   /*
    * Cyphal data structure definition
    *
    * Auto-generated, do not edit.
    *
    * Source file: {{T.source_file_path.as_posix()}}
    */

    #ifndef {{T.full_name | ln.c.macrofy}}
    #define {{T.full_name | ln.c.macrofy}}

    {%- for constant in T.constants %}
    #define {{ T | ln.c.macrofy }}_{{ constant.name | ln.c.macrofy }} {{ constant | constant_value }}
    {%- endfor %}

    typedef struct
    {
        /*
            Note that we're not handling union types properly in this simplified example.
            Unions take a bit more logic to generate correctly.
        */
        {%- for field in T.fields_except_padding %}
            {{ field.data_type | declaration }} {{ field | id }}
            {%- if field.data_type is ArrayType -%}
                [{{ field.data_type.capacity }}]
            {%- endif -%};
        {%- if field is VariableLengthArrayType %}
            {{ typename_unsigned_length }} {{ field | id }}_length;
        {%- endif -%}
        {%- endfor %}
...

    } {{ T | full_reference_name }};

    #endif // {{T.full_name | ln.c.macrofy}}

More examples

Where to find more examples to get started:

  1. See built-in templates under nunavut.lang.LANGUAGE.templates.

  2. API usage examples can be found in the Pycyphal_ library.

Extras

Support for shell autocomplete (see argcomplete docs_ for full details)

.. code-block:: bash

pip install "nunavut[shell]"

# if you haven't setup argcomplete ever...
activate-global-python-argcomplete
source ~/.my_shell_rc_thingy_see_argcomplete_docs

# now register nnvg with argcomplete
eval "$(register-python-argcomplete nnvg)"

Bundled third-party software

Nunavut embeds the following third-party software libraries into its source (i.e. these are not dependencies and do not need to be installed):

  • Jinja2_ by Armin Ronacher and contributors, BSD 3-clause license.
  • markupsafe_ by Armin Ronacher and contributors, BSD 3-clause license (needed for Jinja).

Documentation

The documentation for Nunavut is hosted on readthedocs.io:

  • nunavut_ - The python library provided by this project.
  • nnvg_ – Command-line script for using nunavut_ directly or as part of a build system.
  • nunavut template guide_ – Documentation for authors of nunavut templates.
  • nunavut contributors guide_ – Documentation for contributors to the Nunavut project.
  • nunavut licenses_ – Licenses and copyrights

Nunavut is part of the OpenCyphal project:

  • OpenCyphal website_
  • OpenCyphal forum_

.. _OpenCyphal: http://opencyphal.org .. _OpenCyphal website: http://opencyphal.org .. _OpenCyphal forum: https://forum.opencyphal.org .. _nunavut: https://nunavut.readthedocs.io/en/latest/docs/api/modules.html .. _nnvg: https://nunavut.readthedocs.io/en/latest/docs/cli.html .. _PyDSDL: https://github.com/OpenCyphal/pydsdl .. _Pycyphal: https://github.com/OpenCyphal/pycyphal .. _nunavut template guide: https://nunavut.readthedocs.io/en/latest/docs/templates.html .. _nunavut contributors guide: https://nunavut.readthedocs.io/en/latest/docs/dev.html .. _nunavut licenses: https://nunavut.readthedocs.io/en/latest/docs/appendix.html#licence .. _Jinja2: https://palletsprojects.com/p/jinja .. _markupsafe: https://palletsprojects.com/p/markupsafe .. _Canadian territory: https://en.wikipedia.org/wiki/Nunavut .. _argcomplete docs: https://kislyuk.github.io/argcomplete/

.. |badge_forum| image:: https://img.shields.io/discourse/https/forum.opencyphal.org/users.svg :alt: OpenCyphal forum .. _badge_forum: https://forum.opencyphal.org

.. |badge_docs| image:: https://readthedocs.org/projects/nunavut/badge/?version=latest :alt: Documentation Status .. _badge_docs: https://nunavut.readthedocs.io/en/latest/?badge=latest

.. |badge_build| image:: https://github.com/OpenCyphal/nunavut/actions/workflows/test.yml/badge.svg :alt: Build status .. _badge_build: https://github.com/OpenCyphal/nunavut/actions/workflows/test.yml

.. |badge_pypi_support| image:: https://img.shields.io/pypi/pyversions/nunavut.svg :alt: Supported Python Versions .. _badge_pypi_support: https://pypi.org/project/nunavut/

.. |badge_pypi_version| image:: https://img.shields.io/pypi/v/nunavut.svg :alt: PyPI Release Version .. _badge_pypi_version: https://pypi.org/project/nunavut/

.. |badge_github_license| image:: https://img.shields.io/badge/license-MIT-blue.svg :alt: MIT license .. _badge_github_license: https://github.com/OpenCyphal/nunavut/blob/main/LICENSE.rst

.. |badge_analysis| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=alert_status :alt: Sonarcloud Quality Gate .. _badge_analysis: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut

.. |badge_coverage| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=coverage :alt: Sonarcloud coverage .. _badge_coverage: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut

.. |badge_issues| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=bugs :alt: Sonarcloud bugs .. _badge_issues: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut