[phb]: Add information on how to debug ports

Heavily based on ports(7).

PR:		247271
Reported by:	pauamma@gundo.com
Reviewed by:	carlavilla@
Differential Revision: https://reviews.freebsd.org/D41653

1 files changed, 36 insertions, 0 deletions

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.