git: d946a88e0ce3 - main - build.7: explain how to build KBI-compatible standalone module

The branch main has been updated by kib:

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

commit d946a88e0ce347a9a6fdbfdae0b23ef192b9bddc
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2026-06-26 00:21:36 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2026-06-26 00:44:46 +0000

    build.7: explain how to build KBI-compatible standalone module
    
    Reviewed by:    imp, kevans
    Sponsored by:   The FreeBSD Foundation
    MFC after:      3 days
    Differential revision:  https://reviews.freebsd.org/D57859
---
 share/man/man7/build.7 | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/share/man/man7/build.7 b/share/man/man7/build.7
index 9db04f12c15a..0ec12cf33cbc 100644
--- a/share/man/man7/build.7
+++ b/share/man/man7/build.7
@@ -1116,6 +1116,46 @@ Rebuild and reinstall a single loadable kernel module, in this case
 cd /usr/src/sys/modules/sound
 make all install clean cleandepend KMODDIR=/boot/kernel
 .Ed
+.Pp
+Important detail is that the kernel binary interface is affected
+by its configuration.
+Modules build outside of the regular kernel build procedure still
+must be built against the target kernel configuration, which is
+defined by the set of the
+.Pa opt_*.h
+headers generated by
+.Xr config 8 .
+Use the
+.Va KERNBUILDDIR
+variable to point the module build to the configured kernel.
+There is no need to actually build the configured kernel in
+that directory, module build only consumes the headers from it.
+.Pp
+Additionally, the
+.Va SYSDIR
+environment variable may be useful to point to specific kernel source
+tree used to build the target kernel, since the kernel headers
+define the binary interface for modules.
+.Pp
+Assuming that the
+.Fx
+sources are located in the
+.Pa /home/user/src
+directory, the used kernel config is named
+.Vd MY_KERNEL
+and that the module sources are in
+.Pa my-module
+directory, the following sequence of the commands would populate
+.Pa /home/user/my-kernel-builddir
+directory with the
+.Pa opt_*.h
+headers and then build the module compatible with
+.Vd MY_KERNEL .
+.Bd -literal -offset -indent
+config -d /home/user/my-kernel-builddir -s /home/user/src/sys/amd64/conf MY-KERNEL
+cd my-module
+make all KERNBUILDDIR=/home/user/my-kernel-builddir SYSDIR
+.Ed
 .Ss Example 5: Quickly rebuild a kernel in place
 Quickly rebuild and reinstall the kernel, only recompiling the files
 changed since last build; note that this will only work if the full