doc: Explain how to hack on kernel

Presents the options available (linuxManualConfig versus overriding
extraConfig, ignoreConfigErrors, autoModules, kernelPreferBuiltin.

For advanced hostPlatform customization refer to the commands shared by ericson1234 at
https://github.com/NixOS/nixpkgs/pull/33813 but it is too advanced to
put in the doc.

1 files changed, 51 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml
index 6502aaec83e..f4d697c42db 100644
--- a/nixos/doc/manual/configuration/linux-kernel.xml
+++ b/nixos/doc/manual/configuration/linux-kernel.xml
@@ -67,6 +67,57 @@ nixpkgs.config.packageOverrides = pkgs:
   parameters, run <command>sysctl -a</command>.
  </para>
  <section>
+  <title>Customize your kernel</title>
+
+  <para>
+   The first step before compiling the kernel is to generate an appropriate
+   <literal>.config</literal> configuration. Either you pass your own config via
+   the <literal>configfile</literal> setting of <literal>linuxManualConfig</literal>:
+  <screen><![CDATA[
+  custom-kernel = super.linuxManualConfig {
+    inherit (super) stdenv hostPlatform;
+    inherit (linux_4_9) src;
+    version = "${linux_4_9.version}-custom";
+
+    configfile = /home/me/my_kernel_config;
+    allowImportFromDerivation = true;
+  };
+  ]]></screen>
+
+You can edit the config with this snippet (by default <command>make menuconfig</command> won't work
+  out of the box on nixos):
+  <screen><![CDATA[
+      nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})'
+  ]]></screen>
+
+
+  or you can let nixpkgs generate the configuration.
+  Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>.
+  The answers depend on parameters passed to <filename>pkgs/os-specific/linux/kernel/generic.nix</filename>
+  (which you can influence by overriding <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
+<screen><![CDATA[
+
+  mptcp93.override ({
+      name="mptcp-local";
+
+      ignoreConfigErrors = true;
+      autoModules = false;
+      kernelPreferBuiltin = true;
+
+      enableParallelBuilding = true;
+
+      extraConfig = ''
+        DEBUG_KERNEL y
+        FRAME_POINTER y
+        KGDB y
+        KGDB_SERIAL_CONSOLE y
+        DEBUG_INFO y
+      '';
+    });
+  ]]></screen>
+  </para>
+ </section>
+ <section>
   <title>Developing kernel modules</title>
 
   <para>