libyang

Ливийанг

Libyang - это диапазон языка и инструментария, написанный (и предоставление API) в C. Библиотека используется, например, в проектах LibnetConf2, Netopeer2 или Sysrepo.

Ветви

Проект использует 2 основных филиала master и devel . Другие ветви не должны быть клонированы. В master есть файлы последнего официального релиза . Любые последние улучшения и изменения, которые были протестированы, по крайней мере, кратко, обнаружены в devel . В каждом новом выпуске devel объединяется в master .

Это означает, что при использовании только стабильных официальных выпусков можно использовать либо master , либо конкретные выпуски . Если должны применяться все последние ошибки, то devel Branch - это то, что будет использоваться. Обратите внимание, что всякий раз, когда создается новая проблема , и она возникает в master ветви, первым ответом, вероятно, будет использование devel перед какой -либо дальнейшей предоставленной поддержкой.

Миграция из Ливийанга версии 1 и старше

Посмотрите на документацию и Transition Manual разделе. Это должно помочь с базовой миграцией и способностью компилировать проект. Но чтобы фактически использовать новые функции, необходимо прочитать всю документацию и API.

Предоставлены функции

• Схемы анализа (и проверка) в формате Ян.
• Схемы анализа (и проверка) в формате Инь.
• Расположение, проверка и печать данных экземпляра в формате XML.
• Диаграмма, проверка и печати данных экземпляра в формате JSON (RFC 7951).
• Манипуляция с данными экземпляра.
• Поддержка значений по умолчанию в данных экземпляра (RFC 6243).
• Поддержка расширений Ян.
• Поддержка метаданных ян (RFC 7952).
• Поддержка крепления схемы Ян (RFC 8528).
• Поддержка структуры Ян (RFC 8791).
• Янлинт - богатый функциями инструмент Yang.

Текущая реализация охватывает Yang 1.0 (RFC 6020), а также Yang 1.1 (RFC 7950).

Пакеты

Бинарные RPM или Deb пакеты последнего выпуска могут быть построены локально с помощью apkg , заглянуть в README в каталоге distro .

Требования

Требования к сборке UNIX

• C компилятор
• Cmake> = 2,8,12
• libpcre2> = 10,21 (включая пакет разработки)

Необязательный

• 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 все значения даты и времени ян сначала преобразуются в 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" ..

Справочник по изменению плагинов расширений

Что касается расширений Ян, Libyang позволяет загружать плагины расширения. По умолчанию каталог для хранения плагинов - 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 Notes

Обратите внимание, что с Cmake, если вы хотите изменить компилятор или его параметры после того, как вы уже запустили Cmake, вам нужно сначала очистить его кэш - самый простой способ сделать его для удаления всего контента из каталога «Build».

Использование

Все функции Libyang доступны через основной заголовок:

 #include <libyang/libyang.h>

Чтобы составить вашу программу с Libyang, необходимо связать ее с Libyang, используя следующие параметры линкера:

 -lyang

Обратите внимание, что может потребоваться вызвать ldconfig(8) после установки библиотеки, и если библиотека была установлена ​​в нестандартный путь, путь к Ливиангу должен быть указан на линкер. Чтобы помочь в установке всех вариантов компилятора, есть файл libyang.pc для pkg-config(1) доступный в исходном дереве. Файл установлен с библиотекой.

Если вы используете cmake в вашем проекте, также возможно использовать предоставленный файл FindLibYANG.cmake для обнаружения присутствия библиотеки Ливияна в системе.

Привязки

В этом проекте нет никаких привязков для других языков, но они доступны отдельно.

• Питон
• C ++
• Ржавчина

Янлинт

Project Libyang включает в себя инструмент, богатый функциями, называемый yanglint(1) для проверки и преобразования схем и моделируемых ян. Исходные коды расположены по адресу /tools/lint и могут использоваться для изучения того, как приложение должно использовать библиотеку Libyang. yanglint(1) бинарная, а также его страница человека устанавливается вместе с самой библиотекой.

Есть также Readme, описывающий некоторые примеры использования yanglint .

Тесты

Libyang включает в себя несколько тестов, построенных с CMocka. Тесты можно найти в подкаталоге tests , и они предназначены для проверки функциональности библиотеки после изменений кода. Дополнительные регрессионные тесты, проведенные с помощью корпуса нечетких входов, которые ранее вызвали аварии. Они доступны в tests/fuzz и создаются автоматически с помощью модульных тестов CMocka.

Тесты по умолчанию встроены в режим сборки Debug , работая

 $ make

В случае режима Release , тесты не создаются по умолчанию (это требует дополнительной зависимости), но они могут быть включены с помощью опции Cmake:

 $ cmake -DENABLE_TESTS=ON ..

Обратите внимание, что если необходимые заголовки CMocka не присутствуют в системе, включают пути, тесты недоступны, несмотря на режим сборки или варианты Cmake.

Тесты могут быть проведены с помощью test цели Make:

 $ make test

Перфу

Существует инструмент измерения производительности, который печатает информацию о времени, необходимом для выполнения общих случаев использования работы с данными экземпляров Ян.

Чтобы включить этот тест, используйте опцию и чтобы получить репрезентативные результаты, включите тип сборки выпуска:

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

и запустить тест, увидев его выходной запуск:

 $ make
$ ctest -V -R ly_perf

Покрытие кода

На основании запуска тестов можно сгенерировать отчет о покрытии кода. Но это должно быть включено, и эти команды необходимы для создания отчета:

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

Пузырь

Многочисленные целевые показатели янга и инструкции по пузырьке доступны в каталоге tests/fuzz .

Все цели могут быть разбиты с помощью LLVM Libfuzzer и AFL, и могут быть легко добавлены новые цели. Доступны примеры Asciinema, которые описывают настройку Fuzzing