git: bb5a2106555d - stable/14 - config.5: Document CONF_CFLAGS under 'makeoptions'

The branch stable/14 has been updated by olce:

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

commit bb5a2106555d810bb6a5ec0a80584abf8154cfbd
Author:     Olivier Certner <olce@FreeBSD.org>
AuthorDate: 2025-05-27 07:41:19 +0000
Commit:     Olivier Certner <olce@FreeBSD.org>
CommitDate: 2025-06-16 20:09:06 +0000

    config.5: Document CONF_CFLAGS under 'makeoptions'
    
    This variable serves to tweak CFLAGS from the kernel configuration file,
    easing some custom kernel builds.  It was introduced by bde@ in 1999.
    
    The description has been kept simple on purpose.  It does not completely
    reflect reality as the build infrastructure actually appends variables
    to CFLAGS after CONF_CFLAGS has been processed in a few cases.  However,
    these cases do not collide with expected common uses of CONF_CFLAGS, so
    have not been mentioned.
    
    Reviewed by:    markj (older version)
    MFC after:      3 days
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D50544
    
    (cherry picked from commit 1bdf1b8186359d4ea26e26de03e03b7c1543b707)
    
    Event:          Kitchener-Waterloo Hackathon 202506
---
 usr.sbin/config/config.5 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/usr.sbin/config/config.5 b/usr.sbin/config/config.5
index f77b79a31510..a04ecd4ac0fe 100644
--- a/usr.sbin/config/config.5
+++ b/usr.sbin/config/config.5
@@ -307,11 +307,28 @@ variable is specified,
 .Ar value
 is assumed to be the empty string.
 .Pp
+Note that, as the common makefiles overwrite the
+.Va CFLAGS
+variable after having processed the configuration file,
+customizing
+.Va CFLAGS
+directly via
+.Ic makeoptions
+is not possible.
+Nonetheless, custom compiler flags can be specified using the
+.Va CONF_CFLAGS
+variable instead.
+Its content is appended to
+.Va CFLAGS
+after the common makefiles have set the latter, allowing to override their
+compilation flags.
+.Pp
 Example:
 .Bd -literal -offset indent -compact
 makeoptions MYMAKEOPTION="foo"
 makeoptions MYMAKEOPTION+="bar"
 makeoptions MYNULLMAKEOPTION
+makeoptions CONF_CFLAGS+="-DSOME_CONTROLLING_MACRO"
 .Ed
 .\" -------- MAXUSERS --------
 .Pp