nixos/doc: update custom kernel instructions

Document the `linux.override` way first, then `linuxManualConfig`.

Add a `linux.configEnv` passthru attribute for quickly getting a
`make nconfig`-ready shell.

nixos/doc/manual/configuration/linux-kernel.chapter.md

@@ -82,61 +82,68 @@ boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
 sets the kernel's TCP keepalive time to 120 seconds. To see the
 available parameters, run `sysctl -a`.
 
-## Customize your kernel {#sec-linux-config-customizing}
+## Building a custom kernel {#sec-linux-config-customizing}
 
-The first step before compiling the kernel is to generate an appropriate
+You can customize the default kernel configuration by overriding the arguments for your kernel package:
-`.config` configuration. Either you pass your own config via the
-`configfile` setting of `linuxKernel.manualConfig`:
 
 ```nix
-custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9;
+pkgs.linux_latest.override {
-  in super.linuxKernel.manualConfig {
-    inherit (super) stdenv hostPlatform;
-    inherit (base_kernel) src;
-    version = "${base_kernel.version}-custom";
-
-    configfile = /home/me/my_kernel_config;
-    allowImportFromDerivation = true;
-};
-```
-
-You can edit the config with this snippet (by default `make
-   menuconfig` won\'t work out of the box on nixos):
-
-```ShellSession
-nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
-```
-
-or you can let nixpkgs generate the configuration. Nixpkgs generates it
-via answering the interactive kernel utility `make config`. The answers
-depend on parameters passed to
-`pkgs/os-specific/linux/kernel/generic.nix` (which you can influence by
-overriding `extraConfig, autoModules,
-   modDirVersion, preferBuiltin, extraConfig`).
-
-```nix
-mptcp93.override ({
-  name="mptcp-local";
-
   ignoreConfigErrors = true;
   autoModules = false;
   kernelPreferBuiltin = true;
+  extraStructuredConfig = with lib.kernel; {
+    DEBUG_KERNEL = yes;
+    FRAME_POINTER = yes;
+    KGDB = yes;
+    KGDB_SERIAL_CONSOLE = yes;
+    DEBUG_INFO = yes;
+  };
+}
+```
 
-  enableParallelBuilding = true;
+See `pkgs/os-specific/linux/kernel/generic.nix` for details on how these arguments
+affect the generated configuration. You can also build a custom version of Linux by calling
+`pkgs.buildLinux` directly, which requires the `src` and `version` arguments to be specified.
 
-  extraConfig = ''
+To use your custom kernel package in your NixOS configuration, set
-    DEBUG_KERNEL y
+
-    FRAME_POINTER y
+```nix
-    KGDB y
+boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
-    KGDB_SERIAL_CONSOLE y
+```
-    DEBUG_INFO y
+
-  '';
+Note that this method will use the common configuration defined in `pkgs/os-specific/linux/kernel/common-config.nix`,
-});
+which is suitable for a NixOS system.
+
+If you already have a generated configuration file, you can build a kernel that uses it with `pkgs.linuxManualConfig`:
+
+```nix
+let
+  baseKernel = pkgs.linux_latest;
+in pkgs.linuxManualConfig {
+  inherit (baseKernel) src modDirVersion;
+  version = "${baseKernel.version}-custom";
+  configfile = ./my_kernel_config;
+  allowImportFromDerivation = true;
+}
+```
+
+::: {.note}
+The build will fail if `modDirVersion` does not match the source's `kernel.release` file,
+so `modDirVersion` should remain tied to `src`.
+:::
+
+To edit the `.config` file for Linux X.Y, proceed as follows:
+
+```ShellSession
+$ nix-shell '<nixpkgs>' -A linuxKernel.kernels.linux_X_Y.configEnv
+$ unpackPhase
+$ cd linux-*
+$ make nconfig
 ```
 
 ## Developing kernel modules {#sec-linux-config-developing-modules}
 
-When developing kernel modules it\'s often convenient to run
+When developing kernel modules it's often convenient to run
 edit-compile-run loop as quickly as possible. See below snippet as an
 example of developing `mellanox` drivers.
 

nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml

@@ -96,65 +96,82 @@ boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
     available parameters, run <literal>sysctl -a</literal>.
   </para>
   <section xml:id="sec-linux-config-customizing">
-    <title>Customize your kernel</title>
+    <title>Building a custom kernel</title>
     <para>
-      The first step before compiling the kernel is to generate an
+      You can customize the default kernel configuration by overriding
-      appropriate <literal>.config</literal> configuration. Either you
+      the arguments for your kernel package:
-      pass your own config via the <literal>configfile</literal> setting
-      of <literal>linuxKernel.manualConfig</literal>:
     </para>
     <programlisting language="bash">
-custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9;
+pkgs.linux_latest.override {
-  in super.linuxKernel.manualConfig {
-    inherit (super) stdenv hostPlatform;
-    inherit (base_kernel) src;
-    version = &quot;${base_kernel.version}-custom&quot;;
-
-    configfile = /home/me/my_kernel_config;
-    allowImportFromDerivation = true;
-};
-</programlisting>
-    <para>
-      You can edit the config with this snippet (by default
-      <literal>make menuconfig</literal> won't work out of the box on
-      nixos):
-    </para>
-    <programlisting>
-nix-shell -E 'with import &lt;nixpkgs&gt; {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkg-config ncurses ];})'
-</programlisting>
-    <para>
-      or you can let nixpkgs generate the configuration. Nixpkgs
-      generates it via answering the interactive kernel utility
-      <literal>make config</literal>. The answers depend on parameters
-      passed to
-      <literal>pkgs/os-specific/linux/kernel/generic.nix</literal>
-      (which you can influence by overriding
-      <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
-    </para>
-    <programlisting language="bash">
-mptcp93.override ({
-  name=&quot;mptcp-local&quot;;
-
   ignoreConfigErrors = true;
   autoModules = false;
   kernelPreferBuiltin = true;
-
+  extraStructuredConfig = with lib.kernel; {
-  enableParallelBuilding = true;
+    DEBUG_KERNEL = yes;
-
+    FRAME_POINTER = yes;
-  extraConfig = ''
+    KGDB = yes;
-    DEBUG_KERNEL y
+    KGDB_SERIAL_CONSOLE = yes;
-    FRAME_POINTER y
+    DEBUG_INFO = yes;
-    KGDB y
+  };
-    KGDB_SERIAL_CONSOLE y
+}
-    DEBUG_INFO y
+</programlisting>
-  '';
+    <para>
-});
+      See <literal>pkgs/os-specific/linux/kernel/generic.nix</literal>
+      for details on how these arguments affect the generated
+      configuration. You can also build a custom version of Linux by
+      calling <literal>pkgs.buildLinux</literal> directly, which
+      requires the <literal>src</literal> and <literal>version</literal>
+      arguments to be specified.
+    </para>
+    <para>
+      To use your custom kernel package in your NixOS configuration, set
+    </para>
+    <programlisting language="bash">
+boot.kernelPackages = pkgs.linuxPackagesFor yourCustomKernel;
+</programlisting>
+    <para>
+      Note that this method will use the common configuration defined in
+      <literal>pkgs/os-specific/linux/kernel/common-config.nix</literal>,
+      which is suitable for a NixOS system.
+    </para>
+    <para>
+      If you already have a generated configuration file, you can build
+      a kernel that uses it with
+      <literal>pkgs.linuxManualConfig</literal>:
+    </para>
+    <programlisting language="bash">
+let
+  baseKernel = pkgs.linux_latest;
+in pkgs.linuxManualConfig {
+  inherit (baseKernel) src modDirVersion;
+  version = &quot;${baseKernel.version}-custom&quot;;
+  configfile = ./my_kernel_config;
+  allowImportFromDerivation = true;
+}
+</programlisting>
+    <note>
+      <para>
+        The build will fail if <literal>modDirVersion</literal> does not
+        match the source’s <literal>kernel.release</literal> file, so
+        <literal>modDirVersion</literal> should remain tied to
+        <literal>src</literal>.
+      </para>
+    </note>
+    <para>
+      To edit the <literal>.config</literal> file for Linux X.Y, proceed
+      as follows:
+    </para>
+    <programlisting>
+$ nix-shell '&lt;nixpkgs&gt;' -A linuxKernel.kernels.linux_X_Y.configEnv
+$ unpackPhase
+$ cd linux-*
+$ make nconfig
 </programlisting>
   </section>
   <section xml:id="sec-linux-config-developing-modules">
     <title>Developing kernel modules</title>
     <para>
-      When developing kernel modules it's often convenient to run
+      When developing kernel modules it’s often convenient to run
       edit-compile-run loop as quickly as possible. See below snippet as
       an example of developing <literal>mellanox</literal> drivers.
     </para>

pkgs/os-specific/linux/kernel/generic.nix

@@ -206,6 +206,15 @@ let
     features = kernelFeatures;
     inherit commonStructuredConfig structuredExtraConfig extraMakeFlags isZen isHardened isLibre;
     isXen = lib.warn "The isXen attribute is deprecated. All Nixpkgs kernels that support it now have Xen enabled." true;
+
+    # Adds dependencies needed to edit the config:
+    # nix-shell '<nixpkgs>' -A linux.configEnv --command 'make nconfig'
+    configEnv = kernel.overrideAttrs (old: {
+      nativeBuildInputs = old.nativeBuildInputs or [] ++ (with buildPackages; [
+        pkg-config ncurses
+      ]);
+    });
+
     passthru = kernel.passthru // (removeAttrs passthru [ "passthru" ]);
     tests = let
       overridableKernel = finalKernel // {