d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

ports.7: Document DEBUG_FLAGS and the process of debugging ports

Browse Source 
Loosely based on https://wiki.freebsd.org/BenWoods/DebuggingPorts.

Reviewed by:	crees
MFC after:	2 weeks
Differential Revision:	https://reviews.freebsd.org/D27296
This commit is contained in:
Mateusz Piotrowski 2021-04-17 22:51:54 +02:00
parent be6b8b7a3a
commit d25f7d324a
1 changed files with 59 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
share/man/man7/ports.7
View File

@ -572,6 +572,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
@ -657,6 +664,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 ,