Add kern(1) and kernfrag(7) manuals

2 files changed, 281 insertions, 0 deletions

diff --git a/kern.1 b/kern.1
new file mode 100644
index 0000000..e1b1d2e
--- /dev/null
+++ b/kern.1
@@ -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