DOCSEARCHbyAlgolia
Submit Docs

libyang Documentation

repository·master·Indexed 19 days ago

https://github.com/cesnet/libyang

A C-based YANG data modeling language parser and toolkit providing APIs for parsing, validating, and manipulating YANG 1.0 and 1.1 schemas and instance data in XML and JSON formats. Includes yanglint, a utility for YANG validation and conversion, and supports integration into C projects via CMake and pkg-config.

Tokens
5.1K
Snippets
18
Records
23
Agent score
65%

What's inside libyang

  1. Quickstart for RPM-based systems (Fedora, CentOS, SUSE, ...)

    master

    To build RPM packages for libyang on RPM-based distributions, you need to install the build dependencies and use the apkg tool. This process requires git, rpm-build, and python3-pip to be present on the system.

    sudo dnf install -y git rpm-build python3-pip
pip3 install apkg
apkg build -i

  2. Use yanglint interactive mode commands

    master

    The yanglint(1) tool provides an interactive mode for managing YANG modules and validating data. You can access the command list by typing help or ?.

    Common commands include:

    • add <file>: Add a new module from a specific file.
    • load <module>: Load a new schema from the search directories.
    • print <module>: Print a module.
    • data [-t <type>] <file>: Load, validate, and optionally print instance data.
    • list: List all currently loaded modules.
    • clear: Clear the context and remove all loaded modules.
    • searchpath [--clear] [<path> ...]: Set/print directories for searching imports and includes.
    • feature: Print all features of module(s) with their state.
    • quit or exit: Exit the program.
    >>> help
Available commands:
  help            Display commands description
  add             Add a new module from a specific file
  load            Load a new schema from the searchdirs
  print           Print a module
  data            Load, validate and optionally print instance data
  ext             Validate extension data
  list            List all the loaded modules
  feature         Print all features of module(s) with their state
  searchpath      Print/set the search path(s) for schemas
  clear           Clear the context - remove all the loaded modules
  verb            Change verbosity
  debug           Display specific debug message groups
  quit            Quit the program
  ?               Display commands description
  exit            Quit the program

  3. Configure libyang build with CMake options

    master

    You can customize the build process using various CMake flags:

    • Change Compiler: Set the CC environment variable.
    • Change Install Path: Use -DCMAKE_INSTALL_PREFIX:PATH=<path> (defaults to /usr/local).
    • Build Mode: Switch to production-ready code using -D CMAKE_BUILD_TYPE:String="Release".
    • Extensions Plugins Directory: Set the directory for loading extension plugins using -DPLUGINS_DIR:PATH=<path>. Alternatively, use the LIBYANG_EXTENSIONS_PLUGINS_DIR environment variable at runtime.
    • Disable Schema Revision Reuse: To force libyang to always search for the latest schema revision instead of reusing the initially loaded one, use -DENABLE_LATEST_REVISIONS=OFF.
    • Enable Tests: In Release mode, tests are disabled by default. Enable them with -DENABLE_TESTS=ON (requires cmocka headers).
    # Example: Build in Release mode with a custom install prefix
$ cmake -DCMAKE_BUILD_TYPE:String="Release" -DCMAKE_INSTALL_PREFIX:PATH=/opt/libyang ..

  4. Run libyang tests and coverage

    master

    Libyang includes unit tests (via cmocka) and fuzzing regression tests.

    • Run tests: Use the make test target.
    • Code Coverage: To generate a coverage report, enable coverage during configuration, build, and then run the coverage target.

    Note: If cmocka headers are not in your system include paths, tests will not be available.

    # Run tests
$ make test

# Generate code coverage
$ cmake -DENABLE_COVERAGE=ON ..
$ make
$ make coverage

  5. Validate instance data with yanglint

    master

    The data command is used to load and validate instance data against loaded YANG schemas. You can specify the data type using the -t option to ensure correct validation for different NETCONF/YANG scenarios.

    Supported data types (via -t) include:

    • config: Configuration data (without status data).
    • rpc: RPC requests.
    • reply: RPC replies (must be nested in the original RPC element).
    • action: Actions (no NETCONF envelopes expected).
    • action-reply: Action replies (requires the original action as a second argument).
    • notif: Notifications.
    • edit-config: Data intended for <edit-config> operations.
    • auto: Automatically recognizes the data type (XML input only).

    Note on RPC/Action replies: When validating an action-reply, you must provide the original action file as an argument so the tool can validate the response against the request context.

    >>> data -t config datastore.xml
>>> data -t rpc rpc.xml
>>> data -t action action-reply.xml action.xml
>>> data -t notif notification.xml

  6. Build libyang from source

    master

    To build libyang, use CMake to generate build files and then use make. By default, the build mode is Debug (includes debug information and disables optimizations).

    $ mkdir build; cd build
$ cmake ..
$ make
# make install

  7. Integrate libyang into a C project

    master

    To use libyang in your C application:

    1. Include the header: All functions are available via #include <libyang/libyang.h>.
    2. Link the library: Use the -lyang linker flag.
    3. Handle paths: If installed in a non-standard path, specify the path to the linker. You may need to run ldconfig(8) after installation.
    4. Use pkg-config: A libyang.pc file is provided to simplify compiler and linker options.
    5. Use CMake: If your project uses CMake, use the provided FindLibYANG.cmake file to detect the library.
    #include <libyang/libyang.h>

// Link with -lyang

  8. Work with YANG modules using the Schema Mount extension

    master

    The Schema Mount extension allows a module to 'mount' parts of another module's data hierarchy. You can use yanglint to print the tree structure of a model that uses Schema Mount or to validate data that includes mounted elements.

    To print the tree output of a model with Schema Mount, use the -f tree format and provide the context files using -Y (main context) and -x (extension context).

    To validate and print mounted data, use the -f json format and the -t config type.

    # Print tree output
yanglint -f tree -p . -Y sm-context-main.xml -x sm-context-extension.xml sm-main.yang

# Validate and print mounted data as JSON
yanglint -f json -t config -p . -Y sm-context-main.xml -x sm-context-extension.xml sm-data.xml

  9. Print YANG module trees and details

    master

    You can use the print command to inspect loaded modules.

    • To print a tree representation (similar to pyang style), use print <module-name>.
    • To print detailed information about a specific part of a model (like a leaf or container), use the -f info flag along with a path to the node.

    Example of printing specific node info: print -f info -P /<module-name>:<path-to-node> <module-name>

    >>> print ietf-netconf-acm
module: ietf-netconf-acm
  +--rw nacm
     +--rw enable-nacm?              boolean
     ...

>>> print -f info -P /ietf-netconf-acm:nacm/ietf-netconf-acm:enable-nacm ietf-netconf-acm
leaf enable-nacm {
  ietf-netconf-acm:default-deny-all;
  type boolean;
  default "true";
  config true;
  status current;
  ...
}

  10. Understand libyang ABI versioning and SONAME

    master

    The project uses the version number to indicate the SO ABI version.

    • ABI Compatibility: Compatibility is determined by the first two numbers of the version. If the first two numbers are equal, the versions are ABI compatible.
    • SONAME Format: The SONAME is formatted as libyang.so.0.16 (rather than the typical libyang.so.0). The third number is incremented for compatible changes.
    • Version Numbers: The project version number corresponds to the SO ABI version. Release point numbers (e.g., 0.16-r3) are not used for Debian packaging.

  12. Build a Debian .dsc package

    master

    To create a Debian source package (.dsc), clone the debian/master branch, download the corresponding original source tarball, and use dpkg-source -b to build the source package. Note that release numbering between the git branch and the original tarball may diverge.

    git clone https://github.com/CESNET/libyang -b debian/master
wget -Olibyang_0.16.105.orig.tar.gz https://github.com/CESNET/libyang/archive/v0.16-r3.tar.gz
cd libyang
dpkg-source -b .