diff options
| -rw-r--r-- | kern.1 | 147 | ||||
| -rw-r--r-- | kernfrag.7 | 134 |
2 files changed, 281 insertions, 0 deletions
@@ -0,0 +1,147 @@ +.Dd May 4, 2020 +.Dt KERN 1 +.Os +.Sh NAME +.Nm kern +.Nd configure, build, and install kernels +.Sh SYNOPSIS +.Nm +.Op all +.Nm +.Ic set +.Op Ar kernel +.Nm +.Ic config +.Op Ar host +.Nm +.Ic diff +.Op Ar config +.Nm +.Ic build +.Nm +.Ic install +.Nm +.Ic postinst +.Nm +.Ic clean +.Sh DESCRIPTION +.Nm +is a program for automating the deployment of kernels on Gentoo-based systems. +It is comprised of a set of commands that manage specific tasks related to +building, configuring, and installing kernels. +.Pp +Commands that operate directly on the kernel sources need to be launched from +within the source tree directory, usually +.Pa /usr/src/linux . +Specifically, those commands are +.Em config , +.Em diff , +.Em build , +and +.Em install . +.Pp +.Nm +uses +.Xr sudo 8 +internally to launch commands that require superuser permissions. +Care was taken to minimize the amount of privilege escalation. +Particularly, the +.Em build +command does not build the kernel with superuser permissions, as the +.Em set +command changes the owner of the kernel source tree to the user invoking +.Nm . +.Pp +Throughout this manual, the +.Dq selected kernel +refers to the kernel source tree that is referenced by the +.Pa /usr/src/linux +symbolic link. +In other words, the +.Dq selected kernel +is the currently selected kernel as reported by +.Xr kernel.eselect 5 . +.Pp +The commands are as follows: +.Bl -tag -width Ds +.It Sy all +Changes the current directory to +.Pa /usr/src/linux +and runs the whole suite of commands in order. +.Pp +This command additionally prompts the user for confirmation if the +generated configuration file differs from the one used by the running +kernel. +.It Sy set Op Ar kernel +Sets the selected kernel to +.Em kernel . +This command uses +.Xr eselect 1 , +particularly its +.Xr kernel.eselect 5 +backend to achieve this. +The +.Em kernel +argument can be any kernel name understood by that backend, for example +.Sq linux-5.4.36-gentoo . +.Pp +If no kernel is given, this command determines the latest available kernel automatically. +.It Sy config Op Ar template +Configures the kernel with the given +.Xr kernfrag 7 +.Em template . +.Pp +If no template is given, this command uses the output of +.Xr hostname 1 +as the template name. +.It Sy diff Op Ar config +Uses +.Xr nvim 1 +to display the differences between the generated kernel configuration and +.Em config . +.Pp +If no config is given, this command compares against the configuration of the currently +running kernel. +This requires +.Sy IKCONFIG_PROC +to be enabled. +.It Sy build +Builds the selected kernel. +.It Sy install +Installs the selected kernel. +.Pp +This command mounts +.Pa /boot +if it is a separate partition and not already mounted. +.It Sy postinst +Runs any relevant post-installation jobs. +Currently this calls +.Xr emerge 1 +with +.Em @module-rebuild . +.It Sy clean +Uses +.Em eclean-kernel +to remove obsolete kernels. +.El +.Pp +If no command is given, assume +.Em all . +.Sh FILES +.Bl -tag -width Ds +.It Pa /usr/src/linux +A symbolic link pointing to the directory that contains the kernel source tree. +.It Pa /etc/kernfrag +The directory containing the +.Xr kernfrag 7 +tree. +.El +.Sh SEE ALSO +.Xr emerge 1 , +.Xr eselect 1 , +.Xr kernfrag 7 +.Sh AUTHORS +.An -nosplit +.Nm +was written by +.An Wynn Wolf Arbor Aq Mt wolf@oriole.systems diff --git a/kernfrag.7 b/kernfrag.7 new file mode 100644 index 0000000..60eb4d5 --- /dev/null +++ b/kernfrag.7 @@ -0,0 +1,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 |