Nunavut: DSDL transpiler
tox build (main) |
|
static analysis |
|
unit test code coverage |
|
Python versions supported |
|
latest released version |
|
documentation |
|
license |
|
community/support |
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.
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)
C++ (generates header-only libraries; work-in-progress)
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 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/uavcanGenerate HTML documentation pages using the command-line tool
See above assumptions. The below commands generate documentation for the reg namespace. Note that we have to generate documentation for the uavcan namespace as well, because there are types in reg that will link to uavcan documentation sections.
nnvg --experimental-languages --target-language html public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan
nnvg --experimental-languages --target-language html public_regulated_data_types/uavcanGenerate 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.
nnvg --target-language py public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcanUse custom templates
Partial example: generating a C struct
/*
* 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:
See built-in templates under nunavut.lang.LANGUAGE.templates.
API usage examples can be found in the Pycyphal 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 - 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:
3 maintainers
Metadata
3 maintainers
Release files for nunavut 2.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nunavut-2.3.1.tar.gz | 321.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nunavut-2.3.1-6748279276-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 690.0 kB
