mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-30 05:27:55 +00:00
[#3919] Update meson docs
This commit is contained in:
Andrei Pavel
parent
89ca20560c
commit
5a0e270b22
@ -107,6 +107,16 @@ meson setup build
|
||||
meson compile -C build parser
|
||||
@endcode
|
||||
|
||||
The grammar is also kept in Backus-Naur form available for the Administrator's Reference Manual (ARM)
|
||||
in `doc/sphinx/grammar`. To regenerate it, run:
|
||||
|
||||
@code
|
||||
meson setup build
|
||||
meson compile -C build grammar
|
||||
@endcode
|
||||
|
||||
Kea also maintains a lis
|
||||
|
||||
Strictly speaking, the comment "make parser" is not necessary. If you updated the .ll or .yy file,
|
||||
the regular "make" command should pick those changes up. However, since one source file generates
|
||||
multiple output files and you are likely to be using a multi-process build (by specifying the "-j"
|
||||
|
||||
@ -10,9 +10,9 @@
|
||||
|
||||
@section debugSymbols Enabling debug symbols
|
||||
|
||||
The --enable-debug flag can be useful when developing, since it
|
||||
makes the compiler produce more abundant debugging information that
|
||||
can be read by a debugger.
|
||||
There are flags that make the compiler produce more abundant debugging
|
||||
information that can be read by a debugger. When `--buildtype=debug` is added
|
||||
to `meson setup`, it passes one of these flags to the compiler: `-g`.
|
||||
|
||||
Some compilers don't document some of the flags, such as clang for
|
||||
-g3. However, practice shows that clang behaves the same way as g++
|
||||
@ -20,7 +20,12 @@ in that regard. As an experiment, providing -g4 results in
|
||||
`error: unknown argument: '-g4'`, but providing -g3 succesfully
|
||||
compiles, and supposedly puts it into effect.
|
||||
|
||||
On top of that, the flag enables log4cplus's own logging, and adds
|
||||
more sanity checks in DNS code.
|
||||
Disabling optimizations via `-O0` is also recommended for debugging.
|
||||
|
||||
g++ also provides `-ggdb`.
|
||||
|
||||
The `-D tests=enabled` flag besides enabling unit tests, also enables useful
|
||||
debugging functionality: log4cplus's own logging, and adds more sanity checks
|
||||
in DNS code.
|
||||
|
||||
*/
|
||||
|
||||
@ -19,7 +19,7 @@ $ meson setup build
|
||||
$ meson compile -C build doc
|
||||
@endcode
|
||||
|
||||
The output files will be generated in the ./build/doc/sphinx/_build directory.
|
||||
The output files will be generated in the `./build/doc/sphinx/_build` directory.
|
||||
|
||||
The ARM has an appendix that lists all Kea commands. The commands are integrated
|
||||
into RST using the tool located at doc/sphinx/api2doc.py. The basic principle
|
||||
@ -30,12 +30,20 @@ Those JSON files are loaded by the api2doc.py tool that will generate api.txt
|
||||
that will be used by sphinx. There is no need to call this tool explicitly.
|
||||
It is called automatically when building the ARM.
|
||||
|
||||
The ARM has an appendix with the grammar. If there were new parameters added,
|
||||
you can regenerate the grammars and the appendix with the following procedure:
|
||||
The ARM has an appendix that lists all Kea messages.
|
||||
|
||||
The ARM has an appendix with the grammar.
|
||||
|
||||
The ARM has an appendix with various UML diagrams.
|
||||
|
||||
If either commands, messages, grammar, or UMLs changed, you can regenerate the
|
||||
documentation for each of them with the following procedure:
|
||||
|
||||
@code
|
||||
$ meson setup build
|
||||
$ meson compile -C build grammar
|
||||
$ meson compile -C build mes-doc
|
||||
$ meson compile -C build uml
|
||||
$ meson compile -C build doc
|
||||
@endcode
|
||||
|
||||
@ -44,6 +52,17 @@ After that, inspect the HTML output and make sure it's ok, review changes in
|
||||
update. The date is there, so we (and users) can determine if the grammar
|
||||
is or isn't out of date.
|
||||
|
||||
Sphinx is a Python tool that whas several Python packages. To ensure reproduceability of the
|
||||
documentation that it generates, a file named requirements.txt is used to lock the version for
|
||||
Sphinx and its dependencies. The file is located at `doc/sphinx/src/requirements.txt`. It can be
|
||||
regenerated based on input from `doc/sphinx/src/requirements.in` as long as you have `pip-compile`
|
||||
installed with the following procedure:
|
||||
|
||||
@code
|
||||
$ meson setup build
|
||||
$ meson compile -C build update-python-dependencies
|
||||
@endcode
|
||||
|
||||
@section docsNewCommand Documenting new command
|
||||
|
||||
There are several steps needed to document a new API command:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2012-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2012-2025 Internet Systems Consortium, Inc. ("ISC")
|
||||
//
|
||||
// This Source Code Form is subject to the terms of the Mozilla Public
|
||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
@ -44,12 +44,15 @@
|
||||
* - @subpage unitTestsDatabaseConfig
|
||||
* - @subpage unitTestsSysrepo
|
||||
* - @subpage writingShellScriptsAndTests
|
||||
* - @subpage regeneratingConfigUnitTests
|
||||
* - @subpage performance
|
||||
* - @subpage fuzzer
|
||||
* - @subpage qa
|
||||
* - @subpage ciGithub
|
||||
* - @subpage ciGitlab
|
||||
* - @subpage ciJenkins
|
||||
* - @subpage ciCppcheck
|
||||
* - @subpage ciValgrind
|
||||
*
|
||||
* @section hooksFramework Hooks Framework
|
||||
* - @subpage hooksdgDevelopersGuide
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2023 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2023-2025 Internet Systems Consortium, Inc. ("ISC")
|
||||
//
|
||||
// This Source Code Form is subject to the terms of the Mozilla Public
|
||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
@ -28,19 +28,25 @@ logged in members of the isc-projects organization.
|
||||
|
||||
@section ciGitlab Running CI pipeline on Gitlab
|
||||
|
||||
There are several jobs configure on gitlab CI:
|
||||
There are several jobs configured with Gitlab CI:
|
||||
|
||||
- shellcheck
|
||||
- are-database-scripts-in-sync
|
||||
- bandit
|
||||
- check-for-json-errors-in-doc
|
||||
- danger
|
||||
- dhcpdb_create-upgrade-consistency
|
||||
- duplicate-includes
|
||||
- duplicate-log-messages
|
||||
- missing-api-commands
|
||||
- missing-config-h-include
|
||||
- missing-git-attribute
|
||||
- pycodestyle
|
||||
- pylint
|
||||
- shellcheck
|
||||
- uninstalled-headers
|
||||
- sast-analyzer
|
||||
- flawfinder-sast
|
||||
|
||||
The pipeline can be inspected and configure here:
|
||||
The pipeline can be inspected and configured here:
|
||||
https://gitlab.isc.org/isc-projects/kea/-/ci/editor
|
||||
|
||||
@section ciJenkins Running CI pipeline on Jenkins
|
||||
@ -49,4 +55,31 @@ Jenkins is the primary CI environment. It is hosted on AWS. For details,
|
||||
see internal QA-DHCP wiki, ask on QA channel on mattermost or take a look at the
|
||||
internal `qa-dhcp` repository.
|
||||
|
||||
@section ciCppcheck Running Cppcheck locally
|
||||
|
||||
There are targets that run the cppcheck static analyzer on the Kea codebase.
|
||||
After running the following procedure, you should get an HTML report at `build/report/index.html`:
|
||||
|
||||
@code
|
||||
$ meson setup build
|
||||
$ meson compile -C build cppcheck
|
||||
$ meson compile -C build cppcheck-report
|
||||
@endcode
|
||||
|
||||
@section ciValgrind Running Valgrind locally
|
||||
|
||||
To detect memory leaks, you can run unit tests under valgrind locally with the following procedure:
|
||||
|
||||
@code
|
||||
$ meson setup build
|
||||
$ meson test -C build -v --setup valgrind
|
||||
@endcode
|
||||
|
||||
Alternatively, you can customize the valgrind command with:
|
||||
|
||||
@code
|
||||
$ meson setup build
|
||||
$ meson test -C build -v --wrapper='valgrind --leak-check=full'
|
||||
@endcode
|
||||
|
||||
*/
|
||||
|
||||
@ -632,4 +632,23 @@ do-something --some --other --optional --parameters "${@}"
|
||||
- Never use `eval`. It doesn't preserve original quoting. Have faith that there
|
||||
are always good alternatives.
|
||||
|
||||
@section regeneratingConfigUnitTests Regenerating configuration unit tests
|
||||
|
||||
There are two sets of unit tests that when changed require a bit more laborious procedure for
|
||||
regenerating.
|
||||
|
||||
- `src/bin/dhcp4/tests/get_config_unittest.cc` generated from `src/bin/dhcp4/tests/get_config_unittest.cc.skel`
|
||||
- `src/bin/dhcp6/tests/get_config_unittest.cc` generated from `src/bin/dhcp6/tests/get_config_unittest.cc.skel`
|
||||
|
||||
To regenerate, for the DHCPv6 example, start by running `./build/src/bin/dhcp6/tests/make-rebuild.sh`
|
||||
and you will be presented with a set of instructions. It does the following:
|
||||
|
||||
1. Copies the contents of the `get_config_unittest.cc.skel` file into a temporary `get_config_unittest_rebuild.cc` file.
|
||||
2. Instructs you to recompile `kea-dhcp6-tests-extract` which can be done with `meson compile -C build kea-dhcp6-tests-extract`.
|
||||
3. Runs `kea-dhcp6-tests-extract` which populates the `x` file.
|
||||
4. Instructs you to copy the contents of the `x` file into the `EXTRACTED_CONFIGS` section of `get_config_unittest_rebuild.cc`.
|
||||
5. Runs `kea-dhcp6-tests-generate` which populates the `u` file.
|
||||
6. Instructs you to copy the contents of the `u` file into the `UNPARSED_CONFIGS` section of `get_config_unittest_rebuild.cc`.
|
||||
7. Finally copies `get_config_unittest_rebuild.cc` into `get_config_unittest.cc`.
|
||||
|
||||
*/
|
||||
|
||||
@ -157,6 +157,8 @@ various development include headers and program development tools.
|
||||
Building from source code requires the following software installed on
|
||||
the system:
|
||||
|
||||
- The development tools meson, ninja, and pkg-config.
|
||||
|
||||
- Boost C++ libraries (https://www.boost.org/). The oldest Boost version
|
||||
used for testing is 1.67 (although Kea may also work with older
|
||||
versions e.g. 1.66). The Boost system library must also be installed.
|
||||
@ -169,8 +171,6 @@ the system:
|
||||
|
||||
- A C++ compiler (with C++14 support) and standard development headers.
|
||||
|
||||
- The development tools automake, libtool, and pkg-config.
|
||||
|
||||
- The MySQL client and the client development libraries, when using the
|
||||
``-D mysql=enabled`` configuration flag to build the Kea MySQL database
|
||||
backend. In this case, an instance of the MySQL server running locally
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user