|
Packit |
8fb591 |
# libyang
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
[![BSD license](https://img.shields.io/badge/License-BSD-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
|
|
Packit |
8fb591 |
[![Build Status](https://secure.travis-ci.org/CESNET/libyang.png?branch=master)](http://travis-ci.org/CESNET/libyang/branches)
|
|
Packit |
8fb591 |
[![codecov.io](https://codecov.io/github/CESNET/libyang/coverage.svg?branch=master)](https://codecov.io/github/CESNET/libyang?branch=master)
|
|
Packit |
8fb591 |
[![Coverity Scan Build Status](https://scan.coverity.com/projects/5259/badge.svg)](https://scan.coverity.com/projects/5259)
|
|
Packit |
8fb591 |
[![Ohloh Project Status](https://www.openhub.net/p/libyang/widgets/project_thin_badge.gif)](https://www.openhub.net/p/libyang)
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
libyang is a YANG data modelling language parser and toolkit written (and
|
|
Packit |
8fb591 |
providing API) in C. The library is used e.g. in [libnetconf2](https://github.com/CESNET/libnetconf2),
|
|
Packit |
8fb591 |
[Netopeer2](https://github.com/CESNET/Netopeer2) or [sysrepo](https://github.com/sysrepo/sysrepo) projects.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Provided Features
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
* Parsing (and validating) schemas in YANG format.
|
|
Packit |
8fb591 |
* Parsing (and validating) schemas in YIN format.
|
|
Packit |
8fb591 |
* Parsing, validating and printing instance data in XML format.
|
|
Packit |
8fb591 |
* Parsing, validating and printing instance data in JSON format
|
|
Packit |
8fb591 |
([RFC 7951](https://tools.ietf.org/html/rfc7951)).
|
|
Packit |
8fb591 |
* Manipulation with the instance data.
|
|
Packit |
8fb591 |
* Support for default values in the instance data ([RFC 6243](https://tools.ietf.org/html/rfc6243)).
|
|
Packit |
8fb591 |
* Support for YANG extensions.
|
|
Packit |
8fb591 |
* Support for YANG Metadata ([RFC 7952](https://tools.ietf.org/html/rfc6243)).
|
|
Packit |
8fb591 |
* [yanglint](#yanglint) - feature-rich YANG tool.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Current implementation covers YANG 1.0 ([RFC 6020](https://tools.ietf.org/html/rfc6020))
|
|
Packit |
8fb591 |
as well as YANG 1.1 ([RFC 7950](https://tools.ietf.org/html/rfc7950)).
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Packages
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
We are using openSUSE Build Service to automaticaly prepare binary packages for number of GNU/Linux distros. Check
|
|
Packit |
8fb591 |
[this](https://software.opensuse.org//download.html?project=home%3Aliberouter&package=libyang) page and follow the
|
|
Packit |
8fb591 |
instructions for your distro to install `libyang` package. The `libyang` package is built once a day from the
|
|
Packit |
8fb591 |
master branch. If you want the latest code from the devel branch, install `libyang-experimental` package.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Requirements
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
### Build Requirements
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
* C compiler (gcc >= 4.9, clang >= 3.0, ...)
|
|
Packit |
8fb591 |
* cmake >= 2.8.12
|
|
Packit |
8fb591 |
* libpcre (devel package)
|
|
Packit |
8fb591 |
* note, that PCRE is supposed to be compiled with unicode support (configure's options
|
|
Packit |
8fb591 |
`--enable-utf` and `--enable-unicode-properties`)
|
|
Packit |
8fb591 |
* cmocka >= 1.0.0 (for tests only, see [Tests](#Tests))
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Optional
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
* doxygen (for generating documentation)
|
|
Packit |
8fb591 |
* valgrind (for enhanced testing)
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
### Runtime Requirements
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
* libpcre
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Building
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ mkdir build; cd build
|
|
Packit |
8fb591 |
$ cmake ..
|
|
Packit |
8fb591 |
$ make
|
|
Packit |
8fb591 |
# make install
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
### Documentation
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
The library documentation can be generated directly from the source codes using
|
|
Packit |
8fb591 |
Doxygen tool:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ make doc
|
|
Packit |
8fb591 |
$ google-chrome ../doc/html/index.html
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
The documentation is also built hourly and available at
|
|
Packit |
8fb591 |
[netopeer.liberouter.org](https://netopeer.liberouter.org/doc/libyang/master/).
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
### Useful CMake Options
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Changing Compiler
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Set `CC` variable:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ CC=/usr/bin/clang cmake ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Changing Install Path
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
To change the prefix where the library, headers and any other files are installed,
|
|
Packit |
8fb591 |
set `CMAKE_INSTALL_PREFIX` variable:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Default prefix is `/usr/local`.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Build Modes
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
There are two build modes:
|
|
Packit |
8fb591 |
* Release.
|
|
Packit |
8fb591 |
This generates library for the production use without any debug information.
|
|
Packit |
8fb591 |
* Debug.
|
|
Packit |
8fb591 |
This generates library with the debug information and disables optimization
|
|
Packit |
8fb591 |
of the code.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
The `Debug` mode is currently used as the default one. to switch to the
|
|
Packit |
8fb591 |
`Release` mode, enter at the command line:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -D CMAKE_BUILD_TYPE:String="Release" ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Changing Extensions Plugins Directory
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
As for YANG extensions, libyang allows loading extension plugins. By default, the
|
|
Packit |
8fb591 |
directory to store the plugins is LIBDIR/libyang. To change it, use the following
|
|
Packit |
8fb591 |
cmake option with the value specifying the desired directory:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DPLUGINS_DIR:PATH=`pwd`"/src/extensions/" ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
The directory path can be also changed runtime via environment variable, e.g.:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ LIBYANG_EXTENSIONS_PLUGINS_DIR=`pwd`/my/relative/path yanglint
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
#### Optimizations
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Whenever the latest revision of a schema is supposed to be loaded (import without specific revision),
|
|
Packit |
8fb591 |
it is performed in the standard way, the first time. By default, every other time when the latest
|
|
Packit |
8fb591 |
revision of the same schema is needed, the one initially loaded is reused. If you know this can cause
|
|
Packit |
8fb591 |
problems meaning the latest available revision of a schema can change during operation, you can force
|
|
Packit |
8fb591 |
libyang to always search for the schema anew by:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DENABLE_LATEST_REVISIONS=OFF ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Also, it can be efficient to store certain information about schemas that is generated during parsing
|
|
Packit |
8fb591 |
so that it does not need to be generated every time the schema is used, but it will consume some
|
|
Packit |
8fb591 |
additional space. You can enable this cache with:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DENABLE_CACHE=ON ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
### CMake Notes
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Note that, with CMake, if you want to change the compiler or its options after
|
|
Packit |
8fb591 |
you already ran CMake, you need to clear its cache first - the most simple way
|
|
Packit |
8fb591 |
to do it is to remove all content from the 'build' directory.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Usage
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
All libyang functions are available via the main header:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
#include <libyang/libyang.h>
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
To compile your program with libyang, it is necessary to link it with libyang using the
|
|
Packit |
8fb591 |
following linker parameters:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
-lyang
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Note, that it may be necessary to call `ldconfig(8)` after library installation and if the
|
|
Packit |
8fb591 |
library was installed into a non-standard path, the path to libyang must be specified to the
|
|
Packit |
8fb591 |
linker. To help with setting all the compiler's options, there is `libyang.pc` file for
|
|
Packit |
8fb591 |
`pkg-config(1)` available in the source tree. The file is installed with the library.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
If you are using `cmake` in you project, it is also possible to use the provided
|
|
Packit |
8fb591 |
`FindLibYANG.cmake` file to detect presence of the libyang library in the system.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## yanglint
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
libyang project includes a feature-rich tool called `yanglint(1)` for validation
|
|
Packit |
8fb591 |
and conversion of the schemas and YANG modeled data. The source codes are
|
|
Packit |
8fb591 |
located at [`/tools/lint`](./tools/lint) and can be used to explore how an
|
|
Packit |
8fb591 |
application is supposed to use the libyang library. `yanglint(1)` binary as
|
|
Packit |
8fb591 |
well as its man page are installed together with the library itself.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
There is also [README](./tools/lint/examples/README.md) describing some examples of
|
|
Packit |
8fb591 |
using `yanglint`.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
libyang supports YANG extensions via a plugin mechanism. Some of the plugins (for
|
|
Packit |
8fb591 |
NACM or Metadata) are available out of the box and installed together with libyang.
|
|
Packit |
8fb591 |
However, when libyang is not installed and `yanglint(1)` is used from the build
|
|
Packit |
8fb591 |
directory, the plugins are not available. There are two options:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
1. Install libyang.
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
# make install
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
2. Set environment variable `LIBYANG_EXTENSIONS_PLUGINS_DIR` to contain path to the
|
|
Packit |
8fb591 |
built extensions plugin (`./src/extensions` from the build directory).
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ LIBYANG_EXTENSIONS_PLUGINS_DIR="`pwd`/src/extensions" ./yanglint
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Tests
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
libyang includes several tests built with [cmocka](https://cmocka.org/). The tests
|
|
Packit |
8fb591 |
can be found in `tests` subdirectory and they are designed for checking library
|
|
Packit |
8fb591 |
functionality after code changes.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
The tests are by default built in the `Debug` build mode by running
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ make
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
In case of the `Release` mode, the tests are not built by default (it requires
|
|
Packit |
8fb591 |
additional dependency), but they can be enabled via cmake option:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DENABLE_BUILD_TESTS=ON ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Note that if the necessary [cmocka](https://cmocka.org/) headers are not present
|
|
Packit |
8fb591 |
in the system include paths, tests are not available despite the build mode or
|
|
Packit |
8fb591 |
cmake's options.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Tests can be run by the make's `test` target:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ make test
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
## Bindings
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
We provide bindings for high-level languages using [SWIG](http://www.swig.org/)
|
|
Packit |
8fb591 |
generator. The bindings are optional and to enable building of the specific
|
|
Packit |
8fb591 |
binding, the appropriate cmake option must be enabled, for example:
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
$ cmake -DJAVASCRIPT_BINDING=ON ..
|
|
Packit |
8fb591 |
```
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
More information about the specific binding can be found in their README files.
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
Currently supported bindings are:
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
* JavaScript
|
|
Packit |
8fb591 |
* cmake option: `JAVASCRIPT_BINDING`
|
|
Packit |
8fb591 |
* [README](./swig/javascript/README.md)
|
|
Packit |
8fb591 |
|
|
Packit |
8fb591 |
|