kernfrag.7


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

.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