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

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=5ff4e8af631f4e36bcf79f7e29ae80c8c587f18e

commit 5ff4e8af631f4e36bcf79f7e29ae80c8c587f18e
Author:     Fernando Apesteguía <[email protected]>
AuthorDate: 2023-08-29 11:06:28 +0000
Commit:     Fernando Apesteguía <[email protected]>
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:    [email protected]
    Reviewed by:    carlavilla@
    Differential Revision: https://reviews.freebsd.org/D41653
---
 .../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
 ....
+
+[[testing-debugging-ports]]
+== 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
+line:
+
+[source,shell]
+....
+# cd category/port && make -DWITH_DEBUG DEBUG_FLAGSS="-g -O0"
+....
+
+[NOTE]
+====
+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
+[.filename]#/etc/make.conf#.
+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.