nnvg

Usage

Generate code from UAVCAN DSDL using pydsdl and jinja2

usage: nnvg [-h] [--lookup-dir LOOKUP_DIR] [--verbose] [--version]
            [--outdir OUTDIR] [--templates TEMPLATES]
            [--target-language TARGET_LANGUAGE] [--experimental-languages]
            --output-extension OUTPUT_EXTENSION [--dry-run] [--list-outputs]
            [--generate-support {always,never,as-needed,only}] [--list-inputs]
            [--generate-namespace-types] [--omit-serialization-support]
            [--namespace-output-stem NAMESPACE_OUTPUT_STEM] [--no-overwrite]
            [--file-mode FILE_MODE] [--trim-blocks] [--lstrip-blocks]
            [--allow-unregulated-fixed-port-id]
            [--pp-max-emptylines PP_MAX_EMPTYLINES]
            [--pp-trim-trailing-whitespace] [-pp-rp PP_RUN_PROGRAM]
            [-pp-rpa PP_RUN_PROGRAM_ARG]
            [--target-endianness {any,big,little}]
            [--omit-float-serialization-support]
            [--enable-serialization-asserts]
            [--enable-override-variable-array-capacity]
            [--language-standard LANGUAGE_STANDARD]
            [root_namespace]

Positional Arguments

root_namespace

A source directory with DSDL definitions.

Default: “.”

Named Arguments

--lookup-dir, -I
 

List of other namespace directories containing data type definitions that are referred to from the target root namespace. For example, if you are reading a vendor-specific namespace, the list of lookup directories should always include a path to the standard root namespace “uavcan”, otherwise the types defined in the vendor-specific namespace won’t be able to use data types from the standard namespace.

Additional directories can also be specified through the environment variable UAVCAN_DSDL_INCLUDE_PATH, where the path entries are separated by colons “:”

Default: []

--verbose, -v verbosity level (-v, -vv)
--version show program’s version number and exit
--outdir, -O

output directory

Default: “nunavut_out”

--templates

Paths to a directory containing templates to use when generating code.

Templates found under these paths will override the built-in templates for a given language. If no target language was provided and no template paths were provided then no source will be generated.

--target-language, -l
 

Language support to install into the templates.

If provided then the output extension (–e) can be inferred otherwise the output extension must be provided.

--experimental-languages, -Xlang
 

Activate languages with unstable, experimental support.

By default, target languages where support is not finalized are not enabled when running nunavut, to make it clear that the code output may change in a non-backwards-compatible way in future versions, or that it might not even work yet.

Default: False

--output-extension, -e
 The extension to use for generated files.
--dry-run, -d

If True then no files will be generated.

Default: False

--list-outputs

Emit a semicolon-separated list of files. (implies –dry-run) Emits files that would be generated if invoked without –dry-run. This command is useful for integrating with CMake and other build systems that need a list of targets to determine if a rebuild is necessary.

Default: False

--generate-support
 

Possible choices: always, never, as-needed, only

Change the criteria used to enable or disable support code generation.

as-needed (default) - generate support code if serialization is enabled. always - always generate support code. never - never generate support code. only - only generate support code.

Default: “as-needed”

--list-inputs

Emit a semicolon-separated list of files. (implies –dry-run) A list of files that are resolved given input arguments like templates. This command is useful for integrating with CMake and other build systems that need a list of inputs to determine if a rebuild is necessary.

Default: False

--generate-namespace-types
 

If enabled this script will generate source for namespaces. All namespaces including and under the root namespace will be treated as a pseudo-type and the appropriate template will be used. The generator will first look for a template with the stem “Namespace” and will then use the “Any” template if that is available. The name of the output file will be the default value for the –namespace-output-stem argument and can be changed using that argument.

Default: False

--omit-serialization-support, -pod
 

If provided then the types generated will be POD datatypes with no additional logic. By default types generated include serialization routines and additional support libraries, headers, or methods.

Default: False

--namespace-output-stem
 The name of the file generated when –generate-namespace-types is provided.
--no-overwrite

By default, generated files will be silently overwritten by subsequent invocations of the generator. If this argument is specified an error will be raised instead preventing overwrites.

Default: False

--file-mode

The file-mode each generated file is set to after it is created. Note that this value is interpreted using python auto base detection. Because of this, to provide an octal value, you’ll need to prefix your literal with ‘0o’ (e.g. –file-mode 0o664).

Default: 292

--trim-blocks

If this is set to True the first newline after a block in a template is removed (block, not variable tag!).

Default: False

--lstrip-blocks
 

If this is set to True leading spaces and tabs are stripped from the start of a line to a block in templates.

Default: False

--allow-unregulated-fixed-port-id
 

Do not reject unregulated fixed port identifiers. This is a dangerous feature that must not be used unless you understand the risks. The background information is provided in the UAVCAN specification.

Default: False

--pp-max-emptylines
 

If provided this will suppress generation of additional consecutive empty lines beyond the limit set by this argument.

Note that this will insert a line post-processor which may reduce performance. Consider using a code formatter on the generated output to enforce whitespace rules instead.

--pp-trim-trailing-whitespace
 

Enables a line post-processor that will elide all whitespace at the end of each line.

Note that this will insert a line post-processor which may reduce performance. Consider using a code formatter on the generated output to enforce whitespace rules instead.

Default: False

-pp-rp, --pp-run-program
 

Runs a program after each file is generated but before the file is set to read-only.

example

# invokes clang-format with the "in-place" argument on each file after it is
# generated.

nnvg --outdir include --templates c_jinja -e .h -pp-rp clang-format -pp-rpa=-i dsdl
-pp-rpa, --pp-run-program-arg
 Additional arguments to provide to the program specified by –pp-run-program. The last argument will always be the path to the generated file.

language options

Options passed through to templates as language_options on the target language.

Note that these arguments are passed though without validation, have no effect on the Nunavut library, and may or may not be appropriate based on the target language and generator templates in use.

--target-endianness
 

Possible choices: any, big, little

Specify the endianness of the target hardware. This allows serialization logic to be optimized for different CPU architectures.

--omit-float-serialization-support
 

Instruct support header generators to omit support for floating point operations in serialization routines. This will result in errors if floating point types are used, however; if you are working on a platform without IEEE754 support and do not use floating point types in your message definitions this option will avoid dead code or compiler errors in generated serialization logic.

Default: False

--enable-serialization-asserts
 

Instruct support header generators to generate language-specific assert statements as part of serialization routines. By default the serialization logic generated may make assumptions based on documented requirements for calling logic that could expose a system to undefined behavior. The alternative, for languages that do not support exception handling, is to use assertions designed to halt a program rather than execute undefined logic.

Default: False

--enable-override-variable-array-capacity
 

Instruct support header generators to add the possibility to override max capacity of a variable length array in serialization routines. This option will disable serialization buffer checks and add conditional compilation statements which violates MISRA.

Default: False

--language-standard, -std
 For language generators that support different standards of their core language this option can be used to optimize the output. For example, C templates may generate slightly different code for the the c99 standard then for c11. For available support in Nunavut see the documentation for built-in templates (https://nunavut.readthedocs.io/en/latest/docs/templates.html#built-in-template-guide).

Example Usage:

# This would include j2 templates for a folder named 'c_jinja'
# and generate .h files into a directory named 'include' using
# dsdl root namespaces found under a folder named 'dsdl'.

nnvg --outdir include --templates c_jinja -e .h dsdl