nnvg
Usage
Generate code from Cyphal DSDL using pydsdl and jinja2
usage: nnvg [-h] [--lookup-dir LOOKUP_DIR] [--verbose] [--version]
[--outdir OUTDIR] [--templates TEMPLATES]
[--support-templates SUPPORT_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] [--embed-auditing-info]
[--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 {c11,c++14,cetl++14-17,c++17,c++17-pmr,c++20}]
[--configuration [CONFIGURATION ...]] [--list-configuration]
[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 an environment variable DSDL_INCLUDE_PATH where the path entries are separated by colons “:” on posix systems and “;” on Windows.
- --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.
- --support-templates
Paths to a directory containing templates to use when generating support code.
Templates found under these paths will override the built-in support templates for a given language.
- --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 Cyphal specification.
Default: False
- --embed-auditing-info
If set, generators are instructed to add additional information in the form of language-specific comments or meta-data to use when auditing source code generated by Nunavut. This data may change based on the environment in use which may interfere with the reproducibility of your builds. For example, paths to input files used to generate a type may be included with this option where these paths will be different depending on the server used to run nnvg.
Default: False
post-processing options
Options that enable various post-generation steps because Pavel Kirienko doesn’t like writing jinja templates.
- --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 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
Possible choices: c11, c++14, cetl++14-17, c++17, c++17-pmr, c++20
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).
- --configuration, -c
There is a set of built-in configuration for Nunavut that provides default values for known languages as documented in the template guide. This argument lets you specify override configuration yamls.
- --list-configuration, -lc
Lists all configuration values resolved for the given arguments.
Default: False
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