nnvg¶
Usage¶
Generate code from Cyphal 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]
[--configuration [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. 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. |
| --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 | |
| --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 | |
| 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 Nunvut that provides default falues 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