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"
@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++
`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.
*/
$ 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
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
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:
-// 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
* - @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
-// 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
@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
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
+
*/
- 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`.
+
*/
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.
- 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
projects / thirdparty / kea.git / commitdiff
