Documentation Issue: How to rebuild a kernel with a custom kernel config

[rgrunbla]

Context

Reading the manual, in particular https://nixos.org/manual/nixos/stable/index.html#sec-linux-config-customizing, I don't understand how to use the excerpt:

custom-kernel = let base_kernel = linuxKernel.kernels.linux_4_9;
  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;
};

Seeing the super, I assume you have to use it in an overlay, e.g. :

  nixpkgs.overlays = [
    (self: super: {
      custom-kernel =
        let base_kernel = linuxKernel.kernels.linux_5_10;
        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;
        };
    })
  ];

which complains about linuxKernel not being defined, e.g error: undefined variable 'linuxKernel', so I replace linuxKernel with super.linuxKernel.

I then use boot.kernelPackages = pkgs.custom-kernel; to use this kernel package, which gives me this error:

error: anonymous function at /nix/store/1554bc8x8qcppxl8g1airnz357fb7nhs-source/pkgs/os-specific/linux/kernel/manual-config.nix:16:4 called without required argument 'lib'

       at /nix/store/1554bc8x8qcppxl8g1airnz357fb7nhs-source/lib/customisation.nix:69:16:

           68|     let
           69|       result = f origArgs;
             |                ^
           70|
(use '--show-trace' to show detailed location information)

I tried adding lib to the inherited variables, next to hostPlatform, but I then get this error:

error: anonymous function at /nix/store/1554bc8x8qcppxl8g1airnz357fb7nhs-source/pkgs/os-specific/linux/kernel/manual-config.nix:16:4 called with unexpected argument 'hostPlatform'

       at /nix/store/1554bc8x8qcppxl8g1airnz357fb7nhs-source/lib/customisation.nix:69:16:

           68|     let
           69|       result = f origArgs;
             |                ^
           70|
(use '--show-trace' to show detailed location information)

At this point I stopped trying to recompile the kernel with a custom config because it seems I misunderstood how to recompile a customized kernel.

I also tried following the wiki, in particular, https://nixos.wiki/wiki/Linux_kernel#Booting_a_kernel_from_a_custom_source, without much success (the config was not taken into account).

Question

How are you supposed to recompile a nixos linux kernel using a custom .config file ? Can the doc be improved with more details on the procedure ?

Technical details

Please run nix-shell -p nix-info --run "nix-info -m" and paste the result.

$ nix-shell -p nix-info --run "nix-info -m"
 - system: `"x86_64-linux"`
 - host os: `Linux 5.15.47, NixOS, 22.05 (Quokka), 22.05.998.d17a56d90ec`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.9.1`
 - channels(root): `"nixos-22.05, nixos-22.05-22.05"`
 - channels(remy): `""`
 - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`

[phaer]

I believe the error is because you are trying to use just a kernel for kernelPackages, while that includes other things as well (e.g. an nvidia driver).

See e.g. linuxPackages_custom_tinyconfig_kernel in all-packages.nix for an example. Or the option description of boot.kernelPackages.

    base = linuxPackages.kernel;
    tinyLinuxPackages = linuxKernel.customPackage {
      inherit (base) version src;
      allowImportFromDerivation = false;
      configfile = linuxConfig {
        makeTarget = "tinyconfig";
        src = base.src;
      };
    };

[rgrunbla]

So how am I supposed to use the linuxPackages_custom_tinyconfig_kernel definiton to build my own kernel ? Because if I do a

      custom-kernel =
        let
          base = pkgs.linuxPackages.kernel;
          tinyLinuxPackages = pkgs.linuxKernel.customPackage {
            inherit (base) version src;
            allowImportFromDerivation = false;
            configfile = pkgs.linuxConfig {
              makeTarget = "tinyconfig";
              src = base.src;
            };
          };
        in
        tinyLinuxPackages.kernel;

in an overlay, I still get errors like this:

error: attribute 'extend' missing

       at /nix/store/1554bc8x8qcppxl8g1airnz357fb7nhs-source/nixos/modules/system/boot/kernel.nix:40:31:

           39|       type = types.raw;
           40|       apply = kernelPackages: kernelPackages.extend (self: super: {
             |                               ^
           41|         kernel = super.kernel.override (originalArgs: {
(use '--show-trace' to show detailed location information)

I'm therefore asking, again: can someone show me how to rebuild a kernel with a custom kernel config, in a nixos system, with the context regarding how to do it (e.g. specifying if it's in an overlay, and so on).

Thanks

[ncfavier]

Trying to make the doc a bit better in #207095