Index: share/man/man7/ports.7
===================================================================
--- share/man/man7/ports.7
+++ share/man/man7/ports.7
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 10, 2020
+.Dd November 20, 2020
 .Dt PORTS 7
 .Os
 .Sh NAME
@@ -558,6 +558,13 @@
 .It Va WITH_DEBUG_PORTS
 A list of origins for which to set
 .Va WITH_DEBUG .
+.It Va DEBUG_FLAGS
+.Pq Default: Ql -g
+Additional
+.Va CFLAGS
+to set when
+.Va WITH_DEBUG
+is set.
 .It Va WITH_CCACHE_BUILD
 .Pq Vt bool
 If set, enables the use of
@@ -631,6 +638,59 @@
 .Pp
 These and other options-related variables are documented in
 .Pa /usr/ports/Mk/bsd.options.mk .
+.It Sy Example 5\&: No Debugging Ports
+By default ports are built and packaged without debugging support (e.g.,
+debugging symbols are stripped from binaries, optimization flags are used for
+compiling, verbose logging is disabled).
+Whether ports are built with debugging symbols can be controlled by the
+settings in
+.Xr make.conf 5 ,
+e.g.,
+.Bd -literal -offset 2n
+# Enable debugging for all ports.
+WITH_DEBUG=		yes
+# Enable debugging for selected ports.
+WITH_DEBUG_PORTS=	mail/dovecot security/krb5
+.Ed
+.Pp
+It is also possible to use the debug variables on the command line:
+.Bd -literal -offset 2n
+.Li # Ic make -DWITH_DEBUG DEBUG_FLAGS="-g -O0" build
+.Ed
+.Pp
+See the
+.Sx MAKE VARIABLES
+section to learn more about the debug variables.
+.Pp
+To understand the details of what happens when the debug variables are set it
+is best to consult the files located at
+.Pa ${PORTSDIR}/Mk/*
+.Po Pa bsd.port.mk
+in particular
+.Pc .
+.Pp
+If debugging is enabled for a specific port, the ports framework will:
+.Bl -bullet
+.It
+Add
+.Va DEBUG_FLAGS
+(defaults to
+.Ql -g )
+to
+.Va CFLAGS .
+.It
+Try to prevent the binaries from being stripped (including checking the install
+target to replace
+.Ql install-strip
+with
+.Ql install ) .
+Whether a binary has been stripped can be checked with
+.Xr file 1 .
+.It
+Try to enable other debugging features like debug build type or verbose logging.
+However, this is port-specific and the ports framework might not be aware of
+each supported debugging feature a given piece of software has to offer).
+.El
 .El
 .Sh SEE ALSO
 .Xr make 1 ,