diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8176e16b6..245ef11c8f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Here's a quick list of how to contribute a patch: 2. **open an issue** in [Kea project](https://gitlab.isc.org/isc-projects/kea/issues/new), make sure it describes what you want to fix and **why** 3. **ask someone from the ISC team to give you permission to fork Kea** (ask @tomek, @vicky, @ondrej - or @godfryd or basically anyone from the Kea dev team) + or basically anyone from the Kea dev team) 4. **fork Kea code**: go to Kea project page, click [Fork button](https://gitlab.isc.org/isc-projects/kea/forks/new). If you can't, you didn't complete step 3. 5. **Implement your fix or feature, push code** to your repo. Make sure it compiles, has unit-tests, @@ -188,8 +188,9 @@ make distcheck There are other useful switches which can be passed to configure. It is always a good idea to use `–enable-logger-checks`, which does sanity checks on logger parameters. Use `–-enable-debug` to -enable various additional consistency checks that reduce performance but help during development. If -you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are +enable debug symbols and various additional consistency checks that reduce performance but help +during development. +If you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are modifying DHCP code, you are likely to be interested in enabling a non-default database backends for DHCP. Note that if the backend is not enabled, the database-specific unit-tests are skipped. To enable the MySQL backend, use the switch `–with-mysql`; for PostgreSQL, use `–with-pgsql`. @@ -216,7 +217,7 @@ particular, new users can't fork the code on their own and it requires someone f grant the ability to fork projects. Fortunately, this is easy to do and we glady do this for anyone who asks and provides a good reason. "I'd like to fix bug X or develop feature Y" is an excellent reason. The best place for asking is either kea-dev or asking in a comment in your issue. Make sure -you put a name tag (@tomek, @godfryd, @vicky or @ondrej). When you write a comment in an issue or +you put a name tag (@tomek, @vicky or @ondrej). When you write a comment in an issue or merge request and add a name tag on it, the user is automatically notified. Once you fork the Kea code in gitlab, you have your own copy and you can commit your changes there diff --git a/doc/devel/Makefile.am b/doc/devel/Makefile.am index 687b9c1a63..2db3150756 100644 --- a/doc/devel/Makefile.am +++ b/doc/devel/Makefile.am @@ -5,6 +5,7 @@ EXTRA_DIST += config-backend.dox EXTRA_DIST += congestion-handling.dox EXTRA_DIST += contribute.dox EXTRA_DIST += cross-compile.dox +EXTRA_DIST += debug.dox EXTRA_DIST += doc.dox EXTRA_DIST += fuzz.dox EXTRA_DIST += mainpage.dox diff --git a/doc/devel/debug.dox b/doc/devel/debug.dox new file mode 100644 index 0000000000..556ed2ebd9 --- /dev/null +++ b/doc/devel/debug.dox @@ -0,0 +1,26 @@ +// Copyright (C) 2023 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 +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** + + @page debug Debugging Kea + +@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. + +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++ +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. + +*/ diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index d7481159da..2699df6837 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -154,7 +154,8 @@ * - @subpage LoggingApi * - @subpage SocketSessionUtility * - @subpage crossCompile + * - @subpage debug * - @subpage docs - * - Documentation warnings and errors + * - Documentation Warnings and Errors * */