yangdump-pro Introduction

The yangdump-pro program is used to validate YANG files, and convert them to other formats. It is normally used by authors while developing new YANG data models. The compiler and validation engine portion of yangdump-pro (libyumapro_ncx.so) is used in all YumaPro programs.

Note

Any place the program name “yangdump-pro” is mentioned, it also applies to the name “yangdump-sdk”, except where explicitly mentioned.

yangdump-pro Features

The yangdump-pro compiler has the following features:

full support for all YANG language constructs.
full support for YANG submodules.
full support for YANG revisions and deviations across an arbitrary set of YANG files.
validates the entire YANG source file, even statements within unused objects.
builds a complete internal representation of the 'cooked' object tree, including deviations, to validate or output the exact data structures that result from a set of YANG files.
Over 100 separate validation checks, errors, and warnings, covering every type of programming mistake that can be made in a YANG file.
Some warnings are fully configurable, and any warning can be suppressed.
Can process any number specific modules and directory trees containing modules at once.
Any number of modules containing deviations can be specified, and any target nodes in all modules affected will be properly patched.
Ignores CVS and subversion directories, if encountered in directory searches.
Attempts to find all errors and warnings possible in the file, instead of stopping on the first error.
Verifies that all YANG statement syntax is correct, according to the specification.
Verifies that all YANG typedef statements are correct:
- The entire typedef chain is checked, until a built-in data type is reached.
- Checks valid combined refinements to named types and built-in types
- Check for valid range statements.
- Check for valid pattern statements.
- Verify the path statement is correct for leafref type statements.
- Verify the default statement is valid.
Compile time loop detection:
- import statement loops.
- include statement loops.
- belongs-to statement references self.
- typedef type statement references self.
- derived type statement loops.
- path statement loops for leafref objects.
- base statement loops for identity statements.
- feature name reference loops for if-feature statements.
- uses statement loop in groupings.
Compile-time duplicate detection:
- import statements
- include statements
- must statements
- if-feature statements
- unique statements
- local typedef of grouping name collision
- verifies that the correct number of instances appear for every YANG sub-statement.
- duplicate sibling node names due to uses or augment statement expansion
- checks multiple refine statements within a uses statement for duplicate refinements to the same target node.
- checks multiple deviate statements within a deviation statement for duplicate alterations to the same target node.
- checks deep within all choice statements to make sure that no accessible object names conflict with sibling nodes that will appear in the value nodes, within a NETCONF database.
Verifies that all default statements are correct for the declared type.
- Only the static properties of the leafref and instance-identifier built-in data types can be validated at compile time.
Verifies that all XPath expressions in must and when statements, even those in groupings, contain only valid XPath and reference valid data nodes.
Verifies all when statements for a given cooked object, even those inherited from uses and augment statements.
Detects namespace statement conflicts across a set of modules.
Detects prefix statement conflicts across a set of modules.
Detects augment statement conflicts.
Checks if any key leafs are more conditional than their parent node. This can occur if any 'when' or 'if-feature' statements apply to the key leaf, but not to the parent.
Detects unused typedefs and groupings.
Checks line length and identifier length.
Checks revision statements present and in correct order.
Detects any top-level mandatory configuration objects:
- leaf with mandatory statement set to true.
- choice with mandatory statement set to true.
- non-presence container with any mandatory descendants.
Checks all refine statements for proper usage, and checks that the resulting set of objects remains valid. Multiple refine statements for the same target will be combined and checked as if there was only one refine statement for each target node.
Checks all deviation statements for proper usage, and checks that the resulting set of objects remains valid. Multiple deviation statements for the same target will be combined and checked as if there was only one deviation statement for each target node.
Generates doxygen headers for all the functions in the SIL or SIL-SA source code
- format must be set to one of the C file variants
- doxygen-headers must be set to true (default)

The yangdump-pro translator has the following features:

Full support for YANG string specification syntax:
- All double quoted string formatting rules.
- Preservation of single-quoted string content.
- All forms of string concatenation.
- Unquoted string without any whitespace.
Generates YIN syntax from the YANG token sequence
- YIN format is the standard XML version of a YANG module
Generates hyper-linked HTML for a set of YANG modules.
- Rich set of configuration parameters to control HTML generation.
- Uses configurable and customizable Cascading Style Sheets (CSS).
- Can generate full WEB page or single <div> for embedding in a WEB page.
- Can combine all sub-modules into a single conceptual module.
- Objects tagged as ncx:hidden will be ignored in the HTML output.
Generates canonical YANG (all statements in the same order, etc.):
- Combines refine and deviation statements for the same target.
- Combines range statement components into canonical form.
- Generates consistent (configurable) indentation for all statements.
- Objects tagged as ncx:hidden will be ignored in the YANG output.
Generates SQL statements for populating the netconf-central database with quick lookup information about a set of YANG modules.
Generates C source code stubs for netconfd-pro server instrumentation libraries, for dynamic loading of a YANG module.
Generates informational reports on the contents of a YANG file:
- Imported modules (dependencies).
- Exported symbols (exports).
- Object name tree (identifiers or tree-identifiers)
- Module revision date (modversion)
- YANG module metrics reports (stats and totals)

Starting yangdump-pro

The current working directory in use when yangdump-pro is invoked is important. It is most convenient to run yangdump-pro from a work directory, rather than the installation directory or within the module library.

The yangdump-pro program can be invoked several ways:

To get the current version and exit:
```
> yangdump-pro --version
```

To get program help and exit:

> yangdump-pro --help
> yangdump-pro --help --brief
> yangdump-pro --help --full

The default parameter for the yangdump-pro CLI is the --module parameter. If an unknown parameter is given and it could be a valid module parameter, then it will be treated as an instance of this parameter.

To validate a single YANG module named 'foo', the following command lines are equivalent:
```
> yangdump-pro foo

> yangdump-pro --module=foo
```
To validate the './test1' and './test2' directory subtrees as an entire set of modules, and save the output to 'mylogfile':
```
> yangdump-pro --subtree=test1 --subtree=test2 --logfile=mylogfile
```
To get all the configuration parameters from a text file named '~/yangdump-pro-project1.conf':
```
> yangdump-pro --config=~/yangdump-pro-project1.conf
```
To generate YANG HTML documentation files in the '~/work' directory (with the default naming scheme) for all the YANG modules in the './test1' directory subtree:
```
> yangdump-pro --subtree=test1 --output=~/work --format=html --defnames=true
```

Stopping yangdump-pro

There is no interactive mode for yangdump-pro, so there is no need for a command to exit the program.

The Control C character sequence can be used to cancel the yangdump-pro processing in progress. However, this will leave any partially completed output files in place.

Configuration Parameter List

The following configuration parameters are used by yangdump-pro. Refer to the CLI Reference for more details.

yangdump-pro CLI Parameters

Parameter	Description
--config	Specifies the configuration file to use for parameters.
--defnames	Specifies if the default naming scheme is used for any output files.
--dependencies	Generate the module dependencies report.
--deviation	Species one or more YANG modules to load as deviations.
--doxygen-headers	Specifies if doxygen comment headers should be used when generating source code
--exports	Generate the module exports report.
--feature-code-default	Specifies if a feature should use static or dynamic code by default
--feature-disable	Leaf list of features to disable
--feature-dynamic	Specifies a feature that uses dynamic code
--feature-enable	Specifies a feature that should be enabled
--feature-enable-default	Specifies if a feature should be enabled or disabled by default
--feature-static	Specifies a feature that uses static code
--format	Specifies the type of translation format that should be used for the output.
--force-prefix	Specifies the prefix to use for short name generation
--help	Get context-sensitive help, then exit.
--help-mode	Adjust the help output (--brief, or --full).
--home	Override the $HOME environment variable
--html-div	For HTML translation, controls whether to generate a <div> element instead of a complete HTML document.
--html-toc	For HTML translation, controls the table of contents that is generated.
--identifiers	Generate the module object identifiers report.
--indent	Specifies the indent count to use when writing data.
--lang-errors	Generate the default error messages for language translation
--log	Specifies the log file to use instead of STDOUT.
--log-append	Controls whether a log file will be reused or overwritten.
--log-level	Specifies verbosity level of log message output
--modpath	Sets the module search path.
--module	Specifies one or more YANG modules to load upon startup.
--modversion	Generate the module version report.
--no-config	Ignore the default config file if it is present.
--objview	Specifies whether raw or cooked objects will be generated during HTML and YANG translation.
--output	Specifies where output files should be generated.
--quiet-mode	Do not generate module summary reports unless errors or warnings found
--short-names	Specifies if short name code generation will be used
--show-errors	Print all the error and warning messages, then exit.
--sil-bundle	Generate a SIL or SIL-SA bundle instead of a library for 1 module
--sil-edit1	Generate a first generation edit function callback instead of 2nd generation
--sil-edit2	Generate a 2nd generation edit function callback instead of first generation
--sil-edit3	Generate a 3rd generation edit function callback instead of other generations
--sil-get1	Generate a first generation get function callback instead of 2nd generation
--sil-get2	Generate a 2nd generation get function callback instead of first generation
--sil-include	Generate an 'include' directive in the SIL or SIL-SA C files
--sil-nmda	Generate NMDA related code within SIL or SIL-SA GET2 functions
--sil-sa	Generate SIL-SA (sub-agent) code instead of SIL (master agent) code
--simurls	Controls how URL parameters are generated during HTML file output.
--stats	Control YANG usage statistics reporting for each input module.
--subdirs	Controls whether sub-directories will be searched during file searches.
--subtree	Specifies one or more directory subtrees to search for YANG modules.
--totals	Controls statistics summary reporting for a set of input modules.
--tree-identifiers	Generate the module object identifier local-names report in tree format.
--unified	Controls whether to combine submodules into the main module in the translation output.
--urlstart	Specifies the start of URLs to use during HTML file generation.
--version	Prints the program version and then exit.
--versionnames	Controls whether the revision date is used in YANG module file names.
--warn-error	Treat all warnings as errors
--warn-idlen	Controls how identifier lengths are checked.
--warn-linelen	Controls how line lengths are checked.
--warn-off	Suppresses the specified warning number.
--warn-off-yang	Suppresses all YANG warnings
--warn-up	Elevates the specified warning number to an error
--with-ocpattern	Controls whether OpenConfig pattern syntax will be checked
--xsd-schemaloc	Generate schemaLocation attributes during XSD translation.
--yumapro-home	Specifies the $YUMAPRO_HOME project root to use when searching for files.