.Dd June 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 using the base
template and 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 git-diff 1
if available, otherwise
.Xr diff 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 the configuration file to be present under
.Pa /boot .
.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 Wolfgang Müller Aq Mt wolf@oriole.systems