.Dd May 4, 2020
.Dt KERNFRAG 7
.Os
.Sh NAME
.Nm kernfrag
.Nd compose Linux kernel configurations
.Sh DESCRIPTION
.Nm
is a framework for arranging and composing Linux kernel configurations.
It is comprised of two distinct types of files,
.Em fragments
and
.Em templates ,
which are organized within a specific directory structure.
.Pp
Utilities such as
.Xr kern 1
then use the kernel's
.Em merge_config.sh
script to compose a complete configuration file from a given template
and all fragments referenced within it.
.Pp
Note that by default,
.Em merge_config.sh
will merge fragments with the
kernel's default configuration as generated by
.Sq make alldefconfig .
In other words, configuration symbols that are enabled (or disabled) by
default need not be included explicitly.
.Pp
This manual requires a basic understanding of the kernel build system.
For more information, refer to the resources linked in the
.Sx SEE ALSO
section of this manual.
.Sh FRAGMENTS
A
.Em fragment
is a text file containing a set of configuration symbols and
their respective values.
.Pp
The format of this file is analogous to the one used by the kernel
configuration file.
For example:
.Bd -literal -offset indent
# We only really care about standard PC systems
# CONFIG_X86_EXTENDED_PLATFORM is not set

# We want to support transparent hugepages, though applications
# should ask for them specifically with madvise
CONFIG_TRANSPARENT_HUGEPAGE=y
CONFIG_TRANSPARENT_HUGEPAGE_MADVISE=y
.Ed
.Sh TEMPLATES
A
.Em template
is a text file containing a list of
.Em fragment
paths.
.Pp
One such path is given per line, relative to the
.Pa fragments/
directory in the root
.Nm
structure.
Empty lines or comments are not allowed.
For example:
.Bd -literal -offset indent
devices/input/xpad
devices/net/r8169
devices/usb/sound
.Ed
.Sh DIRECTORY STRUCTURE
The canonical root directory for the
.Nm
structure is
.Pa /etc/kernfrag .
Contained within are two directories,
.Pa fragments/
and
.Pa templates/ .
.Pp
The
.Pa fragments/
directory contains an arbitrarily nested tree of fragments.
It is recommended to group fragments according to the nature of the
configuration symbols they contain.
For example, a group for device drivers can be arranged like this:
.Bd -literal -offset indent
fragments/devices/
├── input
│   └── xpad
├── net
│   ├── r8169
│   └── tigon3
└── usb
    ├── bluetooth
    └── sound
.Ed
.Pp
The
.Pa templates/
directory contains all templates.
Usually there is one template for each host managed by the user.
A special
.Qq base
template is used by
.Xr kern 1
to determine which fragments are always included.
.Pp
For example, the following listing contains templates for two hosts
and the previously mentioned
.Qq base
template.
.Bd -literal -offset indent
templates/
├── aphrodite
├── base
└── hephaestus
.Ed
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/kernfrag
The canonical root directory for the
.Nm
structure.
.El
.Sh SEE ALSO
.Xr kern 1
.Bl -tag -width Ds
.It The Kernel Build System:
https://www.kernel.org/doc/html/latest/kbuild/index.html
.It The kernel's merge_config shell script
.Pa /usr/src/linux/scripts/kconfig/merge_config.sh
.El