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

1 files changed, 40 insertions, 0 deletions

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