From a8d3b9f0a2ab61e4ce1dc0987385ab60d6403b08 Mon Sep 17 00:00:00 2001
From: DS <commits@sidhion.com>
Date: Mon, 23 Oct 2023 19:37:04 -0700
Subject: [PATCH] doc: show how to use manual linux kernel configs

The documentation on the linux kernel focused on using and extending
kernels that were already packaged, but never mentioned that it's
possible to also build a kernel almost "from scratch".

This commit gives a starting point on how to do these specialised
kernel builds.
---
 doc/builders/packages/linux.section.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/builders/packages/linux.section.md b/doc/builders/packages/linux.section.md
index b64da85791a0d95..151f4820d857520 100644
--- a/doc/builders/packages/linux.section.md
+++ b/doc/builders/packages/linux.section.md
@@ -39,3 +39,20 @@ How to add a new (major) version of the Linux kernel to Nixpkgs:
 4.  Test building the kernel: `nix-build -A linuxKernel.kernels.kernel_2_6_22`. If it compiles, ship it! For extra credit, try booting NixOS with it.
 
 5.  It may be that the new kernel requires updating the external kernel modules and kernel-dependent packages listed in the `linuxPackagesFor` function in `linux-kernels.nix` (such as the NVIDIA drivers, AUFS, etc.). If the updated packages aren’t backwards compatible with older kernels, you may need to keep the older versions around.
+
+## Manual kernel configs {#sec-manual-kernel-configs}
+
+Sometimes it may not be desirable to use the kernels already packaged in Nixpkgs, especially if most of the default configuration has to be altered or disabled to achieve a kernel as expected by the target use case. An example of this is building a kernel for use in a VM or micro VM. Nixpkgs provides the `linuxManualConfig` function for these cases: it requires the caller to pass the kernel sources and a config file, allowing one to build their own kernel with specific tuning.
+
+An example usage of `linuxManualConfig`:
+
+```nix
+{ pkgs, ... }: {
+  version = "X.Y.Z";
+  src = pkgs.fetchurl { ... };
+  configfile = ./path_to_config_file;
+  linux = pkgs.linuxManualConfig { inherit version src configfile; };
+}
+```
+
+Additional properties can be used with `linuxManualConfig` for further customisation. Readers who need more than the barebones example above should read [`pkgs/os-specific/linux/kernel/manual-config.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/os-specific/linux/kernel/manual-config.nix).