################################################
Nunavut: DSDL transpiler
################################################
+--------------------------------+-----------------------------------+
| tox 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** (generates header-only libraries)
- **C++** (generates header-only libraries; `work-in-progress <https://github.com/OpenCyphal/nunavut/issues/91>`_)
- **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.
.. code-block:: shell
nnvg --target-language c --target-endianness=little --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.
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.
.. code-block:: shell
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/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.
************************************************
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
.. |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_and_release.yml/badge.svg
:alt: Build status
.. _badge_build: https://github.com/OpenCyphal/nunavut/actions/workflows/test_and_release.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
Raw data
{
"_id": null,
"home_page": "https://opencyphal.org",
"name": "nunavut",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "uavcan,dsdl,can,can-bus,codegen,cyphal,opencyphal",
"author": "OpenCyphal Development Team",
"author_email": "maintainers@opencyphal.org",
"download_url": "https://files.pythonhosted.org/packages/b2/01/e0d705e4a50ea1c3b2ee250ba1123a59bf2d961ce958061a5c1e9c0112e5/nunavut-2.3.0.tar.gz",
"platform": null,
"description": "################################################\nNunavut: DSDL transpiler\n################################################\n\n+--------------------------------+-----------------------------------+\n| tox build (main) | |badge_build|_ |\n+--------------------------------+-----------------------------------+\n| static analysis | |badge_analysis|_ |badge_issues|_ |\n+--------------------------------+-----------------------------------+\n| unit test code coverage | |badge_coverage|_ |\n+--------------------------------+-----------------------------------+\n| Python versions supported | |badge_pypi_support|_ |\n+--------------------------------+-----------------------------------+\n| latest released version | |badge_pypi_version|_ |\n+--------------------------------+-----------------------------------+\n| documentation | |badge_docs|_ |\n+--------------------------------+-----------------------------------+\n| license | |badge_github_license|_ |\n+--------------------------------+-----------------------------------+\n| community/support | |badge_forum|_ |\n+--------------------------------+-----------------------------------+\n\nNunavut is a source-to-source compiler (transpiler) that automatically converts `OpenCyphal`_ DSDL definitions\ninto source code in a specified target programming language.\nIt is constructed as a template engine that exposes a `PyDSDL`_ abstract\nsyntax tree to `Jinja2`_ templates allowing authors to generate code, schemas, metadata,\ndocumentation, etc.\n\n.. figure:: /docs/static/images/nunavut_pipeline.svg\n :width: 1000px\n\n Nunavut DSDL transcompilation pipeline.\n\nNunavut ships with built-in support for some programming languages,\nand it can be used to generate code for other languages if custom templates (and some glue logic) are provided.\nCurrently, the following languages are supported out of the box:\n\n- **C11** (generates header-only libraries)\n- **C++** (generates header-only libraries; `work-in-progress <https://github.com/OpenCyphal/nunavut/issues/91>`_)\n- **Python** (generates Python packages)\n- **HTML** (generates documentation pages)\n\nNunavut is named after the `Canadian territory`_. We chose the name because it\nis a beautiful word to say and read.\n\n************************************************\nInstallation\n************************************************\n\nNunavut depends on `PyDSDL`_.\n\nInstall from PIP::\n\n pip install -U nunavut\n\n************************************************\nExamples\n************************************************\n\nThe examples do not replace the documentation, please do endeavor to read it.\n\nGenerate C headers using the command-line tool\n----------------------------------------------\n\nThis example assumes that the public regulated namespace directories ``reg`` and ``uavcan`` reside under\n``public_regulated_data_types/``.\nNunavut is invoked to generate code for the former.\n\n.. code-block:: shell\n\n nnvg --target-language c --target-endianness=little --enable-serialization-asserts public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan\n\nGenerate HTML documentation pages using the command-line tool\n-------------------------------------------------------------\n\nSee above assumptions. The below commands generate documentation\nfor the ``reg`` namespace.\nNote that we have to generate documentation for the ``uavcan`` namespace\nas well, because there are types in ``reg`` that will link to ``uavcan``\ndocumentation sections.\n\n.. code-block:: shell\n\n nnvg --experimental-languages --target-language html public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan\n nnvg --experimental-languages --target-language html public_regulated_data_types/uavcan\n\nGenerate Python packages using the command-line tool\n----------------------------------------------------\n\nThis example assumes that the public regulated namespace directories ``reg`` and ``uavcan`` reside under\n``public_regulated_data_types/``.\nNunavut is invoked to generate code for the former.\n\n.. code-block:: shell\n\n nnvg --target-language py public_regulated_data_types/reg --lookup-dir public_regulated_data_types/uavcan\n\n\nUse custom templates\n--------------------\n\nPartial example: generating a C struct\n\n.. code-block:: jinja\n\n /*\n * Cyphal data structure definition\n *\n * Auto-generated, do not edit.\n *\n * Source file: {{T.source_file_path.as_posix()}}\n */\n\n #ifndef {{T.full_name | ln.c.macrofy}}\n #define {{T.full_name | ln.c.macrofy}}\n\n {%- for constant in T.constants %}\n #define {{ T | ln.c.macrofy }}_{{ constant.name | ln.c.macrofy }} {{ constant | constant_value }}\n {%- endfor %}\n\n typedef struct\n {\n /*\n Note that we're not handling union types properly in this simplified example.\n Unions take a bit more logic to generate correctly.\n */\n {%- for field in T.fields_except_padding %}\n {{ field.data_type | declaration }} {{ field | id }}\n {%- if field.data_type is ArrayType -%}\n [{{ field.data_type.capacity }}]\n {%- endif -%};\n {%- if field is VariableLengthArrayType %}\n {{ typename_unsigned_length }} {{ field | id }}_length;\n {%- endif -%}\n {%- endfor %}\n ...\n\n } {{ T | full_reference_name }};\n\n #endif // {{T.full_name | ln.c.macrofy}}\n\nMore examples\n-------------\n\nWhere to find more examples to get started:\n\n1. See built-in templates under ``nunavut.lang.LANGUAGE.templates``.\n\n2. API usage examples can be found in the `Pycyphal`_ library.\n\n************************************************\nBundled third-party software\n************************************************\n\nNunavut embeds the following third-party software libraries into its source\n(i.e. these are not dependencies and do not need to be installed):\n\n- `Jinja2`_ by Armin Ronacher and contributors, BSD 3-clause license.\n- `markupsafe`_ by Armin Ronacher and contributors, BSD 3-clause license (needed for Jinja).\n\n************************************************\nDocumentation\n************************************************\n\nThe documentation for Nunavut is hosted on readthedocs.io:\n\n- `nunavut`_ - The python library provided by this project.\n- `nnvg`_ \u2013 Command-line script for using `nunavut`_ directly or as part of a build system.\n- `nunavut template guide`_ \u2013 Documentation for authors of nunavut templates.\n- `nunavut contributors guide`_ \u2013 Documentation for contributors to the Nunavut project.\n- `nunavut licenses`_ \u2013 Licenses and copyrights\n\nNunavut is part of the OpenCyphal project:\n\n- `OpenCyphal website`_\n- `OpenCyphal forum`_\n\n\n.. _`OpenCyphal`: http://opencyphal.org\n.. _`OpenCyphal website`: http://opencyphal.org\n.. _`OpenCyphal forum`: https://forum.opencyphal.org\n.. _`nunavut`: https://nunavut.readthedocs.io/en/latest/docs/api/modules.html\n.. _`nnvg`: https://nunavut.readthedocs.io/en/latest/docs/cli.html\n.. _`PyDSDL`: https://github.com/OpenCyphal/pydsdl\n.. _`Pycyphal`: https://github.com/OpenCyphal/pycyphal\n.. _`nunavut template guide`: https://nunavut.readthedocs.io/en/latest/docs/templates.html\n.. _`nunavut contributors guide`: https://nunavut.readthedocs.io/en/latest/docs/dev.html\n.. _`nunavut licenses`: https://nunavut.readthedocs.io/en/latest/docs/appendix.html#licence\n.. _`Jinja2`: https://palletsprojects.com/p/jinja\n.. _`markupsafe`: https://palletsprojects.com/p/markupsafe\n.. _`Canadian territory`: https://en.wikipedia.org/wiki/Nunavut\n\n.. |badge_forum| image:: https://img.shields.io/discourse/https/forum.opencyphal.org/users.svg\n :alt: OpenCyphal forum\n.. _badge_forum: https://forum.opencyphal.org\n\n.. |badge_docs| image:: https://readthedocs.org/projects/nunavut/badge/?version=latest\n :alt: Documentation Status\n.. _badge_docs: https://nunavut.readthedocs.io/en/latest/?badge=latest\n\n.. |badge_build| image:: https://github.com/OpenCyphal/nunavut/actions/workflows/test_and_release.yml/badge.svg\n :alt: Build status\n.. _badge_build: https://github.com/OpenCyphal/nunavut/actions/workflows/test_and_release.yml\n\n.. |badge_pypi_support| image:: https://img.shields.io/pypi/pyversions/nunavut.svg\n :alt: Supported Python Versions\n.. _badge_pypi_support: https://pypi.org/project/nunavut/\n\n.. |badge_pypi_version| image:: https://img.shields.io/pypi/v/nunavut.svg\n :alt: PyPI Release Version\n.. _badge_pypi_version: https://pypi.org/project/nunavut/\n\n.. |badge_github_license| image:: https://img.shields.io/badge/license-MIT-blue.svg\n :alt: MIT license\n.. _badge_github_license: https://github.com/OpenCyphal/nunavut/blob/main/LICENSE.rst\n\n.. |badge_analysis| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=alert_status\n :alt: Sonarcloud Quality Gate\n.. _badge_analysis: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut\n\n.. |badge_coverage| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=coverage\n :alt: Sonarcloud coverage\n.. _badge_coverage: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut\n\n.. |badge_issues| image:: https://sonarcloud.io/api/project_badges/measure?project=OpenCyphal_nunavut&metric=bugs\n :alt: Sonarcloud bugs\n.. _badge_issues: https://sonarcloud.io/dashboard?id=OpenCyphal_nunavut\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate code from DSDL using Jinja2 templates.",
"version": "2.3.0",
"project_urls": {
"Homepage": "https://opencyphal.org"
},
"split_keywords": [
"uavcan",
"dsdl",
"can",
"can-bus",
"codegen",
"cyphal",
"opencyphal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fd65984bc05af8e376f287177c54a20554ca8d33f7d014fcc68ef5471f4d406f",
"md5": "2dc99838d8d3735e98d13d40fe87d62b",
"sha256": "3bb1229f9c2567ec781cf512c7af37f19331739f498afc0eeefa4d45b3e8a210"
},
"downloads": -1,
"filename": "nunavut-2.3.0-6617454609-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2dc99838d8d3735e98d13d40fe87d62b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 369019,
"upload_time": "2023-10-23T18:30:37",
"upload_time_iso_8601": "2023-10-23T18:30:37.405509Z",
"url": "https://files.pythonhosted.org/packages/fd/65/984bc05af8e376f287177c54a20554ca8d33f7d014fcc68ef5471f4d406f/nunavut-2.3.0-6617454609-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b201e0d705e4a50ea1c3b2ee250ba1123a59bf2d961ce958061a5c1e9c0112e5",
"md5": "45a55981e96eb6fc365755720a814f0b",
"sha256": "fb0a90ec9282e1a4a074cf1871894edbcf42469c17e153f156a3654800492745"
},
"downloads": -1,
"filename": "nunavut-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "45a55981e96eb6fc365755720a814f0b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 321016,
"upload_time": "2023-10-23T18:30:40",
"upload_time_iso_8601": "2023-10-23T18:30:40.450745Z",
"url": "https://files.pythonhosted.org/packages/b2/01/e0d705e4a50ea1c3b2ee250ba1123a59bf2d961ce958061a5c1e9c0112e5/nunavut-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-23 18:30:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "nunavut"
}
JSON