Add kern(1) and kernfrag(7) manuals

1 files changed, 147 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