[#3919] Update meson docs

doc/devel/bison.dox

@@ -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"

doc/devel/debug.dox

@@ -10,9 +10,9 @@
 
 @section debugSymbols Enabling debug symbols
 
-The --enable-debug flag can be useful when developing, since it
+There are flags that make the compiler produce more abundant debugging
-makes the compiler produce more abundant debugging information that
+information that can be read by a debugger. When `--buildtype=debug` is added
-can be read by a debugger.
+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
+Disabling optimizations via `-O0` is also recommended for debugging.
-more sanity checks in DNS code.
+
+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.
 
 */

doc/devel/doc.dox

@@ -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,
+The ARM has an appendix that lists all Kea messages.
-you can regenerate the grammars and the appendix with the following procedure:
+
+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:

doc/devel/mainpage.dox

@@ -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

doc/devel/qa.dox

@@ -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
+
 */

doc/devel/unit-tests.dox

@@ -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`.
+
  */

doc/sphinx/arm/install.rst

@@ -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