eselect-kernel

List available kernel symlink targets with their numbers

$ eselect kernel list

$ eselect kernel set [name|number]

$ eselect kernel show

$ eselect kernel update

eselect kernel command [argument]
or (less common, but direct executable)
eselect-kernel command [argument]

list (or ls)
    Displays a numbered list of all available kernel source directories found under /usr/src/.

set number
    Sets the active kernel source by creating or updating the /usr/src/linux symlink to point to the kernel source corresponding to the specified number from the 'list' output.

show
    Shows the currently active kernel source directory that /usr/src/linux points to.

unset
    Removes the /usr/src/linux symlink. Use with caution as this can break module compilation processes.

help
    Displays a brief help message for the command and its available options.

eselect-kernel is a specialized module of the eselect utility, a cornerstone tool within the Gentoo Linux distribution. Its primary function is to manage the symbolic link /usr/src/linux, which is a crucial pointer to the currently active kernel source directory. This symlink is essential for various system operations, particularly when building out-of-tree kernel modules (like proprietary graphics drivers, virtual machine guest additions, or ZFS), as these processes rely on /usr/src/linux to locate the correct kernel headers and build environment. It simplifies switching between different kernel versions or configurations (e.g., gentoo-sources, vanilla-sources, hardened-sources) installed on the system, providing a user-friendly interface instead of manual symlink manipulation.

Caveats and Limitations:
1. Gentoo-Specific: This command is almost exclusively found and used on Gentoo Linux and its derivatives. It is not part of standard Linux distributions like Debian, Ubuntu, Fedora, or Arch Linux.
2. Kernel Sources Required: For eselect-kernel to be useful, kernel source packages (e.g., sys-kernel/gentoo-sources) must be installed on your system via emerge.
3. No Automatic Recompilation: Changing the active kernel symlink does not automatically recompile your kernel or any kernel modules. You must manually recompile any out-of-tree modules that depend on the kernel source after changing it, or re-run kernel build processes.
4. Impact on Module Builds: It primarily affects future compilation of kernel modules or tools that look for kernel headers at /usr/src/linux, not the currently running kernel itself.

The symbolic link /usr/src/linux is a conventional location for tools and scripts (such as those used by dkms, proprietary graphics drivers, or virtual machine guest additions) to find the currently active kernel source tree. This symlink provides a stable, predictable path regardless of the specific kernel version or configuration installed. eselect-kernel simplifies the management of this crucial symlink, ensuring that such tools can always locate the correct headers and build environment for the kernel you intend to build modules against.

Kernel source packages (e.g., sys-kernel/gentoo-sources, sys-kernel/vanilla-sources) are installed via Gentoo's package manager, Portage (using the emerge command). Each kernel source package typically installs its files into a version-specific directory, such as /usr/src/linux-5.15.76-gentoo. eselect-kernel then allows you to choose which of these installed directories /usr/src/linux should point to, making it easy to manage multiple kernel installations.

eselect-kernel is an integral part of the broader eselect framework, which has been a fundamental utility in Gentoo Linux since its early development. The eselect system was designed to provide a consistent and user-friendly interface for managing system-wide configuration choices, such as default Java environments, Python interpreters, news readers, and critically, kernel sources. This design reflects Gentoo's philosophy of providing users with granular control over their system, allowing easy switching between different installed versions of components without manual symlink or configuration file editing. Its role in managing /usr/src/linux has remained consistent as a core function for system maintenance and out-of-tree module compilation.

eselect(1), emerge(1), genkernel(8), ln(1), modprobe(8)