git: 5ff4e8af63 - main - [phb]: Add information on how to debug ports

From: Fernando Apesteguía <>
Date: Thu, 31 Aug 2023 11:11:26 UTC
The branch main has been updated by fernape:


commit 5ff4e8af631f4e36bcf79f7e29ae80c8c587f18e
Author:     Fernando Apesteguía <>
AuthorDate: 2023-08-29 11:06:28 +0000
Commit:     Fernando Apesteguía <>
CommitDate: 2023-08-31 11:10:28 +0000

    [phb]: Add information on how to debug ports
    Heavily based on ports(7).
    PR:             247271
    Reported by:
    Reviewed by:    carlavilla@
    Differential Revision:
 .../en/books/porters-handbook/testing/_index.adoc  | 36 ++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
index 6f326f6ac8..b4e88cfe4c 100644
--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
@@ -628,3 +628,39 @@ To skip the prompt and remove all unused files unconditionally, the `-y` argumen
 # poudriere distclean -p portstree -y
+== Debugging ports
+Sometimes things go wrong and the port fails at run time.
+The framework provides some facilities to help in debugging ports.
+These helpers are limited since the way of debugging a port heavily depends on
+the technology used.
+The following variables help with debugging ports:
+* `WITH_DEBUG`. If set, ports are built with debugging symbols.
+* `WITH_DEBUG_PORTS`. Specifies a list of ports to be built with `WITH_DEBUG` set.
+* `DEBUG_FLAGS`. Used to specify additional flags to `CFLAGS`. Defaults to `-g`.
+When `WITH_DEBUG` is set, either globally or for a list of ports, the resulting
+binaries are not stripped.
+These variables can be specified in [.filename]#make.conf# or in the command
+# cd category/port && make -DWITH_DEBUG DEBUG_FLAGSS="-g -O0"
+If the port is built using package:ports-mgmt/poudriere[] the debugging
+variables must be specified in poudriere's [.filename]#make.conf# and not in
+Refer to package:ports-mgmt/poudriere[] documentation for details.
+Please refer to the debugging information in the
+extref:{developers-handbook}[Developer's Handbook, debugging] for more details
+about the debugging tools available.