140 lines
7.2 KiB
Text
140 lines
7.2 KiB
Text
|
/**
|
||
|
|
* @page build Building libyang
|
||
|
|
*
|
||
|
|
* [TOC]
|
||
|
|
*
|
||
|
|
* libyang utilizes CMake build system to detect necessary dependencies, checkout the build environment and prepare Makefiles
|
||
|
|
* for the compilation of the library and acompanied tools.
|
||
|
|
*
|
||
|
|
* @section buildRequirements Requirements
|
||
|
|
*
|
||
|
|
* @subsection buildRequirementsCompile Building Requirements
|
||
|
|
*
|
||
|
|
* - C compiler (gcc, clang, ...)
|
||
|
|
* - CMake >= 2.8.12
|
||
|
|
* - libpcre2 (including headers - devel package) >= 10.30
|
||
|
|
*
|
||
|
|
* @subsubsection buildRequirementsCompileOptional Optional Requirements
|
||
|
|
*
|
||
|
|
* - doxygen (for generating documentation)
|
||
|
|
* - cmocka >= 1.0.0 (for tests)
|
||
|
|
* - valgrind (for enhanced testing)
|
||
|
|
* - gcov (for code coverage)
|
||
|
|
* - lcov (for code coverage)
|
||
|
|
* - genhtml (for code coverage)
|
||
|
|
*
|
||
|
|
* @subsection buildRequirementsRun Runtime Requirements
|
||
|
|
*
|
||
|
|
* - libpcre2 (runtime package) >= 10.30
|
||
|
|
*
|
||
|
|
* @section buildCommands Building
|
||
|
|
*
|
||
|
|
* To simply build libyang library and the accompanied tools with the default settings, follow these steps (the `#` character
|
||
|
|
* indicates command(s) to run with `root` privileges):
|
||
|
|
*
|
||
|
|
* $ mkdir build; cd build
|
||
|
|
* $ cmake ..
|
||
|
|
* $ make
|
||
|
|
* # make install
|
||
|
|
*
|
||
|
|
* The default settings can be changed with various CMake variables set via command line or using e.g. `ccmake(1)` tool.
|
||
|
|
* The following sections introduces those variables and explain their meaning.
|
||
|
|
*
|
||
|
|
* @section buildTypes Build Types
|
||
|
|
*
|
||
|
|
* There are several build types according to the primary goal of using the built binaries.
|
||
|
|
*
|
||
|
|
* @subsection buildTypesRelese Release
|
||
|
|
*
|
||
|
|
* Build type to produce final binaries for production use without any debug option. The compiler flags are set as follows:
|
||
|
|
*
|
||
|
|
* -Wall -Wextra -Wno-missing-field-initializers -std=c99 -O3 -DNDEBUG
|
||
|
|
*
|
||
|
|
* Here is the list of the selected additional options available in the *Release* build type.
|
||
|
|
*
|
||
|
|
* Option | Description | Default
|
||
|
|
* ----------------------|------------------------------------------------------------------------------------|--------
|
||
|
|
* ENABLE_BUILD_TESTS | Build tests. | OFF
|
||
|
|
* ENABLE_VALGRIND_TESTS | Build tests with valgrind. | OFF
|
||
|
|
* ENABLE_COVERAGE | Build code coverage report from tests. | OFF
|
||
|
|
* ENABLE_FUZZ_TARGETS | Build target programs suitable for fuzzing with AFL. | OFF
|
||
|
|
* BUILD_SHARED_LIBS | Build shared (.so) instead of static (.a) library | ON
|
||
|
|
* INTERNAL_DOCS | Include developers notes and internal API description into generated Documentation | OFF
|
||
|
|
*
|
||
|
|
* Here is the list of available important targets for the `make(1)` tool:
|
||
|
|
*
|
||
|
|
* Target | Description
|
||
|
|
* -------|------------------------------------------------------------------------------------------------------------
|
||
|
|
* all | Default target, builds libyang library (.so), `yanglint(1)` and `yangre(1)`.
|
||
|
|
* clean | Removes files generated by the make process.
|
||
|
|
* cclean | Extends the `clean` target by removing all the cmake generated files.
|
||
|
|
* doc | Generate HTML documentation. Requires `doxygen(1)`.
|
||
|
|
*
|
||
|
|
* @subsection buildTypesDebug Debug
|
||
|
|
*
|
||
|
|
* `Debug` is the default build type, the produced binaries include additional debug information and the prepared tests are
|
||
|
|
* also built. The compiler flags are set as follows:
|
||
|
|
*
|
||
|
|
* -Wall -Wextra -Wno-missing-field-initializers -std=c99 -g3 -O0
|
||
|
|
*
|
||
|
|
* Here is the list of the selected additional options available in the *Debug* build type.
|
||
|
|
*
|
||
|
|
* Option | Description | Default
|
||
|
|
* ----------------------|------------------------------------------------------------------------------------|--------
|
||
|
|
* ENABLE_BUILD_TESTS | Build tests. | ON
|
||
|
|
* ENABLE_VALGRIND_TESTS | Build tests with valgrind. | ON
|
||
|
|
* ENABLE_COVERAGE | Build code coverage report from tests. | OFF
|
||
|
|
* ENABLE_FUZZ_TARGETS | Build target programs suitable for fuzzing with AFL. | OFF
|
||
|
|
* BUILD_SHARED_LIBS | Build shared (.so) instead of static (.a) library | ON
|
||
|
|
* INTERNAL_DOCS | Include developers notes and internal API description into generated Documentation | OFF
|
||
|
|
*
|
||
|
|
* Here is the list of available important targets for the `make(1)` tool:
|
||
|
|
*
|
||
|
|
* Target | Description
|
||
|
|
* -------------|------------------------------------------------------------------------------------------------------
|
||
|
|
* all | Default target, builds libyang library (.so), `yanglint(1)` and `yangre(1)`.
|
||
|
|
* clean | Removes files generated by the make process.
|
||
|
|
* cclean | Extends the `clean` target by removing all the cmake generated files.
|
||
|
|
* doc | Generate HTML documentation. Requires `doxygen(1)`.
|
||
|
|
* test | Run implementation tests. Requires `cmocka` (and `valgrind(1)` for part of the tests).
|
||
|
|
* format | Reformat source codes using `uncrustify(1)`.
|
||
|
|
* format-check | Dry-run of the `format` target.
|
||
|
|
*
|
||
|
|
* @subsection buildTypesABICheck ABICheck
|
||
|
|
*
|
||
|
|
* Special build type to perform check of the ABI/API compatibility and generate reports. In addition to the basic
|
||
|
|
* requirements, the build type requires some of the <a href="https://abi-laboratory.pro/">ABI Laboratory tools</a>:
|
||
|
|
* `abi-dumper(1)` and `abi-compliance-checker(1)`.
|
||
|
|
*
|
||
|
|
* The compiler flags are set as follows:
|
||
|
|
*
|
||
|
|
* -Wall -Wextra -Wno-missing-field-initializers -std=c99 -g -Og
|
||
|
|
*
|
||
|
|
* All the additional options are switched OFF and the settings should not be changed.
|
||
|
|
*
|
||
|
|
* Here is the list of available important targets for the `make(1)` tool:
|
||
|
|
*
|
||
|
|
* Target | Description
|
||
|
|
* -------------|------------------------------------------------------------------------------------------------------
|
||
|
|
* all | Default target, builds libyang library (.so), `yanglint(1)` and `yangre(1)`.
|
||
|
|
* clean | Removes files generated by the make process.
|
||
|
|
* cclean | Extends the `clean` target by removing all the cmake generated files.
|
||
|
|
* doc | Generate HTML documentation. Requires `doxygen(1)`.
|
||
|
|
* abi-check | Check the backward compatibility of the API/ABI changes. Requires `abi-compliance-checker(1)` and `abi-dump(1)`.
|
||
|
|
* abi-dump | Helper target for `abi-check` generating API/ABI reports. Requires `abi-dump(1)`.
|
||
|
|
|
||
|
|
* @subsection buildTypesDocOnly DocOnly
|
||
|
|
*
|
||
|
|
* Special build type to avoid any requirements except those for building documentation. There are no compiler flags set
|
||
|
|
* since the build type does not allow building any binary output. The settings of the additional options should not be
|
||
|
|
* changed.
|
||
|
|
*
|
||
|
|
* Here is the list of available important targets for the `make(1)` tool:
|
||
|
|
*
|
||
|
|
* Target | Description
|
||
|
|
* -------------|------------------------------------------------------------------------------------------------------
|
||
|
|
* all | Default target, does nothing.
|
||
|
|
* doc | Generate HTML documentation. Requires `doxygen(1)`.
|
||
|
|
*
|
||
|
|
*/
|