libyang

利比亚

Libyang是Yang数据建模语言解析器和工具包编写（并提供API）。在LibnetConf2，Netopeer2或Sysrepo项目中使用了库。

分支

该项目使用2个主要分支master devel 。其他分支不应克隆。在master中，有上次官方版本的文件。至少在devel中找到了至少对其进行简短测试的任何最新改进和更改。在每个新版本中， devel都合并为主master 。

这意味着，当仅使用稳定的官方发行版时，可以使用master或下载特定的版本。如果应该应用所有最新的错误文件， devel分支是要使用的分支。请注意，每当创建新问题并且发生在master分支上时，第一个响应可能是在提供进一步提供的支持之前使用devel 。

从利比亚版本1或以上迁移

查看文档和部分Transition Manual 。这应该有助于基本迁移和编译项目的能力。但是要实际利用新功能，需要阅读整个文档和API。

提供了功能

• 以杨格式解析（和验证）模式。
• 以yin格式解析（和验证）模式。
• 以XML格式解析，验证和打印实例数据。
• 以JSON格式解析，验证和打印实例数据（RFC 7951）。
• 用实例数据进行操作。
• 支持实例数据中默认值（RFC 6243）。
• 支持杨扩展。
• 支持杨元数据（RFC 7952）。
• 支持Yang Schema Mount（RFC 8528）。
• 对杨结构的支持（RFC 8791）。
• yanglint-功能丰富的杨工具。

当前实施涵盖Yang 1.0（RF​​C 6020）以及Yang 1.1（RFC 7950）。

软件包

最新版本的二进制rpm或DEB软件包可以使用apkg在本地构建，请查看distro目录中的README 。

要求

UNIX构建要求

• C编译器
• cmake> = 2.8.12
• libpcre2> = 10.21（包括Devel软件包）

选修的

• doxygen（用于生成文档）
• cmocka> = 1.0.1（用于测试）
• Valgrind（用于增强测试）
• GCOV（代码覆盖）
• LCOV（代码覆盖）
• genhtml（用于代码覆盖范围）

UNIX运行时要求

• libpcre2> = 10.21

Windows构建要求

• Visual Studio 17（2022）
• cmake> = 3.22.0
• libpcre2（与POSIX相同的考虑）
• pthreads-win32
• dirent
• dlfcn-win32
• getopt-win32

Windows版本不支持插件， yanglint仅在非相互作用模式下工作。在Windows上，所有Yang的日期和时间值首先转换为UTC（如果指定了TZ偏移量），然后用“未指定的时区”返回。

建筑

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

有用的CMAKE选项

更改编译器

设置CC变量：

 $ CC=/usr/bin/clang cmake ..

更改安装路径

要更改库，标题和任何其他文件的前缀，请设置CMAKE_INSTALL_PREFIX变量：

 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..

默认前缀为/usr/local 。

建立模式

有两种构建模式：

• 发布。这将生成用于生产使用的库，而无需任何调试信息。
• 调试。这将生成带有调试信息的库，并禁用代码的优化。

当前， Debug模式用作默认模式。要切换到Release模式，请在命令行中输入：

 $ cmake -D CMAKE_BUILD_TYPE:String="Release" ..

更改扩展插件目录

至于杨扩展，利比亚允许加载扩展插件。默认情况下，存储插件的目录是libdir/libyang。要更改它，请使用以下CMAKE选项，并指定所需目录的值：

 $ cmake -DPLUGINS_DIR:PATH=`pwd`"/src/extensions/" ..

目录路径也可以通过环境变量更改运行时，例如：

 $ LIBYANG_EXTENSIONS_PLUGINS_DIR=`pwd`/my/relative/path yanglint

请注意，插件在Windows上不可用。

优化

每当应该加载架构的最新修订（无特定修订）时，它是第一次以标准方式执行。默认情况下，每隔一次需要对同一模式进行最新修订时，最初加载的架构就会重复使用。如果您知道这可能会引起问题，这意味着在操作过程中最新可用的架构修订可能会发生变化，则可以强迫利比亚始终通过以下方式重新搜索模式。

 $ cmake -DENABLE_LATEST_REVISIONS=OFF ..

Cmake注意

请注意，使用CMake，如果您想在运行CMake后更改编译器或其选项，则需要先清除其缓存 - 最简单的方法是从“构建”目录中删除所有内容。

用法

所有利比亚功能都可以通过主标头获得：

 #include <libyang/libyang.h>

要使用Libyang编译您的程序，有必要使用以下链接器参数将其链接到Libyang：

 -lyang

请注意，可能有必要在库安装后调用ldconfig(8) ，如果将库安装到非标准路径中，则必须将通往利比亚的路径指定给链接器。为了帮助设置所有编译器的选项，有libyang.pc文件for pkg-config(1)在源树中可用。该文件与库一起安装。

如果您在项目中使用cmake ，也可以使用提供的FindLibYANG.cmake文件来检测系统中利比亚库的存在。

绑定

该项目中直接没有针对其他语言的绑定，但它们可单独使用。

• Python
• C ++
• 锈

yanglint

Libyang项目包括一个名为yanglint(1)的功能丰富的工具，用于验证和转换模式和Yang建模的数据。源代码位于/tools/lint位置，可用于探索应用程序应该如何使用Libyang库。 yanglint(1)二进制及其人页与库本身一起安装。

还有读书我描述了使用yanglint的一些示例。

测试

利比亚包括使用CMOCKA制造的几项测试。可以在tests子目录中找到测试，并且它们旨在在代码更改后检查库功能。使用先前造成崩溃的模糊输入的语料库进行的其他回归测试已完成。这些可在tests/fuzz中可用，并通过CMOCKA单元测试自动构建。

默认情况下，测试是通过运行在Debug构建模式中内置的

 $ make

在Release模式的情况下，默认情况下不是构建测试（它需要额外的依赖项），但是可以通过CMAKE选项启用它们：

 $ cmake -DENABLE_TESTS=ON ..

请注意，如果系统中不存在必要的CMOCKA标头，则包括构建模式或CMAKE的选项，无法进行测试。

测试可以由Make的test目标进行：

 $ make test

perf

包括一个性能测量工具，它打印有关执行使用Yang实例数据的常见用例所需的时间的信息。

要启用此测试，请使用选项并获得代表性结果，启用版本构建类型：

 $ cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_PERF_TESTS=ON ..

并通过查看其输出运行来运行测试：

 $ make
$ ctest -V -R ly_perf

代码覆盖范围

根据运行测试，可以生成代码覆盖范围报告。但是必须启用它，需要这些命令来生成报告：

 $ cmake -DENABLE_COVERAGE=ON ..
$ make
$ make coverage

模糊

tests/fuzz目录中提供了多个Yang模糊目标和模糊说明。

所有目标都可以与LLVM的Libfuzzer和AFL融为一体，并且可以轻松添加新目标。描述AFL（https://asciinema.org/a/311060）和libfuzzer（https://asciinema.org/a/311035）的ASCIINEMA示例。