libyang

Libyang

Libyang adalah Parser Bahasa Pemodelan Data yang dan Toolkit yang ditulis (dan menyediakan API) di C. Perpustakaan digunakan misalnya proyek LibnetConf2, NetOpeer2 atau Sysrepo.

Cabang

Proyek ini menggunakan 2 cabang utama master dan devel . Cabang lain tidak boleh dikloning. Di master ada file rilis resmi terakhir. Setiap perbaikan dan perubahan terbaru, yang diuji setidaknya secara singkat ditemukan dalam devel . Pada setiap rilis baru, devel digabungkan menjadi master .

Ini berarti bahwa ketika hanya rilis resmi yang stabil untuk digunakan, baik master dapat digunakan atau rilis spesifik yang diunduh. Jika semua perbaikan bug terbaru harus diterapkan, devel Branch adalah yang akan digunakan. Perhatikan bahwa setiap kali masalah baru dibuat dan itu terjadi pada cabang master , respons pertama kemungkinan akan menggunakan devel sebelum dukungan lebih lanjut.

Migrasi dari Libyang versi 1 atau lebih

Lihat ke dalam dokumentasi dan Transition Manual bagian. Itu seharusnya membantu migrasi dasar dan kemampuan untuk menyusun proyek. Tetapi untuk benar -benar memanfaatkan fitur -fitur baru, diperlukan untuk membaca seluruh dokumentasi dan API.

Fitur yang disediakan

• Skema parsing (dan validasi) dalam format Yang.
• Skema parsing (dan validasi) dalam format yin.
• Parsing, memvalidasi dan mencetak data instance dalam format XML.
• Parsing, validasi dan mencetak data instance dalam format JSON (RFC 7951).
• Manipulasi dengan data instance.
• Dukungan untuk nilai default dalam data instan (RFC 6243).
• Dukungan untuk ekstensi Yang.
• Dukungan untuk Yang Metadata (RFC 7952).
• Dukungan untuk Yang Skema Mount (RFC 8528).
• Dukungan untuk Struktur Yang (RFC 8791).
• Yanglint - Alat Yang kaya fitur.

Implementasi saat ini mencakup Yang 1.0 (RFC 6020) serta Yang 1.1 (RFC 7950).

Paket

Paket Binary RPM atau DEB dari rilis terbaru dapat dibangun secara lokal menggunakan apkg , lihat README di direktori distro .

Persyaratan

Persyaratan pembangunan unix

• C Compiler
• cmake> = 2.8.12
• libpcre2> = 10.21 (termasuk paket devel)

Opsional

• doxygen (untuk menghasilkan dokumentasi)
• cmocka> = 1.0.1 (untuk tes)
• Valgrind (untuk pengujian yang ditingkatkan)
• GCOV (untuk cakupan kode)
• LCOV (untuk cakupan kode)
• GenHTML (untuk cakupan kode)

Persyaratan runtime unix

• libpcre2> = 10.21

Persyaratan Windows Build

• Visual Studio 17 (2022)
• cmake> = 3.22.0
• libpcre2 (pertimbangan yang sama seperti di POSIX)
• pthreads-win32
• dirent
• dlfcn-win32
• getopt-win32

Versi Windows tidak mendukung plugin, dan yanglint hanya berfungsi dalam mode non-interaktif. Pada Windows, semua nilai tanggal dan waktu yang pertama kali dikonversi ke UTC (jika TZ Offset ditentukan), dan kemudian dikembalikan dengan "zona waktu yang tidak ditentukan".

Bangunan

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

Opsi CMake yang berguna

Mengubah kompiler

Atur variabel CC :

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

Mengubah jalur instalasi

Untuk mengubah awalan di mana pustaka, header dan file lainnya diinstal, atur variabel CMAKE_INSTALL_PREFIX :

 $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..

Awalan default adalah /usr/local .

Bangun mode

Ada dua mode build:

• Melepaskan. Ini menghasilkan perpustakaan untuk penggunaan produksi tanpa informasi debug.
• Debug. Ini menghasilkan perpustakaan dengan informasi debug dan menonaktifkan optimalisasi kode.

Mode Debug saat ini digunakan sebagai yang default. Untuk beralih ke mode Release , masukkan di baris perintah:

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

Mengubah Direktori Plugin Ekstensi

Adapun ekstensi yang, Libyang memungkinkan pemuatan plugin ekstensi. Secara default, direktori untuk menyimpan plugin adalah Libdir/Libyang. Untuk mengubahnya, gunakan opsi CMake berikut dengan nilai yang menentukan direktori yang diinginkan:

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

Jalur direktori juga dapat diubah runtime melalui variabel lingkungan, misalnya:

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

Perhatikan bahwa plugin tidak tersedia di Windows.

Optimisasi

Setiap kali revisi terbaru dari suatu skema seharusnya dimuat (impor tanpa revisi spesifik), itu dilakukan dengan cara standar, pertama kali. Secara default, setiap kali ketika revisi terbaru dari skema yang sama diperlukan, yang awalnya dimuat digunakan kembali. Jika Anda tahu ini dapat menyebabkan masalah yang berarti revisi terbaru dari suatu skema dapat berubah selama operasi, Anda dapat memaksa Libyang untuk selalu mencari skema lagi dengan:

 $ cmake -DENABLE_LATEST_REVISIONS=OFF ..

Catatan CMake

Perhatikan bahwa, dengan CMake, jika Anda ingin mengubah kompiler atau opsinya setelah Anda menjalankan CMake, Anda perlu menghapus cachenya terlebih dahulu - cara paling sederhana untuk melakukannya adalah dengan menghapus semua konten dari direktori 'build'.

Penggunaan

Semua fungsi Libyang tersedia melalui header utama:

 #include <libyang/libyang.h>

Untuk mengkompilasi program Anda dengan Libyang, perlu menghubungkannya dengan Libyang menggunakan parameter tautan berikut:

 -lyang

Perhatikan, bahwa mungkin perlu untuk memanggil ldconfig(8) setelah instalasi perpustakaan dan jika perpustakaan diinstal ke jalur non-standar, jalur ke Libyang harus ditentukan ke tautan. Untuk membantu mengatur semua opsi kompiler, ada file libyang.pc untuk pkg-config(1) yang tersedia di pohon sumber. File diinstal dengan perpustakaan.

Jika Anda menggunakan cmake di proyek Anda, dimungkinkan juga untuk menggunakan file FindLibYANG.cmake yang disediakan untuk mendeteksi keberadaan perpustakaan Libyang dalam sistem.

Binding

Tidak ada binding untuk bahasa lain secara langsung dalam proyek ini tetapi tersedia secara terpisah.

• Python
• C ++
• Karat

Yanglint

Proyek Libyang mencakup alat kaya fitur yang disebut yanglint(1) untuk validasi dan konversi skema dan data yang dimodelkan Yang. Kode sumber terletak di /tools/lint dan dapat digunakan untuk mengeksplorasi bagaimana suatu aplikasi seharusnya menggunakan perpustakaan Libyang. yanglint(1) Biner serta halaman mannya diinstal bersama dengan perpustakaan itu sendiri.

Ada juga ReadMe yang menggambarkan beberapa contoh menggunakan yanglint .

Tes

Libyang mencakup beberapa tes yang dibangun dengan cmocka. Tes dapat ditemukan dalam tests subdirektori dan dirancang untuk memeriksa fungsionalitas perpustakaan setelah perubahan kode. Tes regresi tambahan dilakukan dengan korpus input fuzzing yang sebelumnya menyebabkan kecelakaan dilakukan. Itu tersedia dalam tests/fuzz dan dibangun secara otomatis dengan tes unit CMOCKA.

Tes secara default dibangun dalam mode pembuatan Debug dengan berjalan

 $ make

Dalam hal mode Release , tes tidak dibangun secara default (membutuhkan ketergantungan tambahan), tetapi mereka dapat diaktifkan melalui opsi CMake:

 $ cmake -DENABLE_TESTS=ON ..

Perhatikan bahwa jika header CMOCKA yang diperlukan tidak ada dalam sistem termasuk jalur, tes tidak tersedia meskipun mode build atau opsi CMake.

Tes dapat dijalankan dengan target test Make:

 $ make test

Perf

Ada alat pengukuran kinerja yang termasuk yang mencetak informasi tentang waktu yang diperlukan untuk menjalankan kasus penggunaan umum bekerja dengan data instance Yang.

Untuk mengaktifkan tes ini, gunakan opsi dan untuk mendapatkan hasil yang representatif, mengaktifkan jenis pembuatan rilis:

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

dan untuk menjalankan tes dengan melihat outputnya berjalan:

 $ make
$ ctest -V -R ly_perf

Cakupan Kode

Berdasarkan tes yang dijalankan, dimungkinkan untuk menghasilkan laporan cakupan kode. Tetapi harus diaktifkan dan perintah ini diperlukan untuk menghasilkan laporan:

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

Fuzzing

Beberapa target fuzzing yang dan instruksi fuzzing tersedia di direktori tests/fuzz .

Semua target dapat disebabkan oleh Libfuzzer dan AFL LLVM, dan target baru dapat dengan mudah ditambahkan. Contoh Asciinema yang menggambarkan pengaturan fuzzing untuk AFL (https://asciinema.org/a/311060) dan libfuzzer (https://asciinema.org/a/311035) tersedia.