Nunavut: DSDL transpiler

tox build (main) Build status
static analysis Sonarcloud Quality Gate Sonarcloud bugs
unit test code coverage Sonarcloud coverage
Python versions supported Supported Python Versions
latest released version PyPI Release Version
documentation Documentation Status
license MIT license
community/support UAVCAN forum

Nunavut is a source-to-source compiler (transpiler) that automatically converts UAVCAN 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.

_images/nunavut_pipeline.svg

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 (generates header-only libraries)

The following languages are currently on the roadmap:

Nunavut is named after the Canadian territory. We chose the name because it is a beautiful word to say and read. Also, the name fits with a theme of “places in Canada” started with the Yukon project.

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 reg and uavcan reside under public_regulated_data_types/. Nunavut is invoked to generate code for the former.

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

Use custom templates

Partial example: generating a C struct

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

    #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 %}
        {%- if field is not 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 -%}
        {%- 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 PyUAVCAN library.

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 is part of the UAVCAN project: