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示例。