git: c8faaf378709 - stable/13 - ports.7: Document DEBUG_FLAGS and the process of debugging ports

[Mateusz Piotrowski]

The branch stable/13 has been updated by 0mp (doc, ports committer):

URL: https://cgit.FreeBSD.org/src/commit/?id=c8faaf378709f4ce4661da7ca73ee88e1cc63d54

commit c8faaf378709f4ce4661da7ca73ee88e1cc63d54
Author:     Mateusz Piotrowski <0mp at FreeBSD.org>
AuthorDate: 2021-04-17 20:51:54 +0000
Commit:     Mateusz Piotrowski <0mp at FreeBSD.org>
CommitDate: 2021-08-15 21:02:08 +0000

    ports.7: Document DEBUG_FLAGS and the process of debugging ports
    
    Loosely based on https://wiki.freebsd.org/BenWoods/DebuggingPorts.
    
    Reviewed by:    crees
    MFC after:      2 weeks
    Differential Revision:  https://reviews.freebsd.org/D27296
    
    (cherry picked from commit d25f7d324a9d0c33655876b920ba590918d16f4c)
---
 share/man/man7/ports.7 | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7
index 1c3cce31d2f0..797fed0d3ec6 100644
--- a/share/man/man7/ports.7
+++ b/share/man/man7/ports.7
@@ -558,6 +558,13 @@ If set, debugging symbols are installed for ports binaries.
 .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
@@ -643,6 +650,58 @@ DISABLE_MAKE_JOBS=	yes
 TRYBROKEN=		yes
 \&.endif
 .Ed
+.It Sy Example 6\&: 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
 .Sh SEE ALSO
 .Xr make 1 ,