nixos/doc: clean up the kernel building section a bit

[K900]

Description of changes

• suggest overriding the existing kernel before using a fully custom config
• use consistent context (no super, just pkgs) everywhere
• replace mptcp93 (long removed) in examples with a recent-ish kernel
• explain how to actually use the kernel in your config
• remove the awkward "make menuconfig" incantation (needs way more context than what's provided)

Fixes-ish #178476.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 22.11 Release Notes (or backporting 22.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

[phaer]

LGTM, much clearer than before ✨

[Shawn8901]

i like the changes.
it helped me to figure out what i did wrong when trying to build my own kernel config whilst getting not understandable nix errors as there was no real example available what really is needed.

[Shawn8901]

i have an additional question/point.

my main approval was that its more clear what to do and how to actually link the kernel with the system (pkgs.linuxPackagesFor wasnt obvious).
as i am now really playing around with overriding the config, dont you have to pass the customization like this?

let
  baseKernel = pkgs.linuxKernel.kernels.linux_5_18;
in  
  linux_custom = baseKernel.override ({
    argsOverride =  {
      autoModules = false;
      kernelPreferBuiltin = true;
      modDirVersion = "5.18.6-shawn1";
      structuredExtraConfig = with pkgs.lib; with pkgs.lib.kernel; {
        PREEMPT = mkForce yes;
        PREEMPT_BUILD = mkForce yes;
        PREEMPT_VOLUNTARY = mkForce no;
        PREEMPT_COUNT = mkForce yes;
        PREEMPTION = mkForce yes;
    };
  };
});

That actually gives me:

nix-repl> packages.x86_64-linux.linux_custom.modDirVersion
"5.18.6-shawn1"

whilst just

  linux_custom = baseKernel.override ({
     modDirVersion = "5.18.6-shawn1";
    [...]
  });

prints

nix-repl> packages.x86_64-linux.linux_custom.modDirVersion
"5.18.6"

edit: i noticed, that i cannot randomly override modDirVersion, but i think that its still an issue as my custom config is also not explorable via nix repl.

which looks for me that overriding needs to be passed via argsOverride which then possibly has to be updated in the documentation.

Could you please cross check it? Would be glad if the documented way actually works.
hint: as i am currently really try to get that booting, i am not fully at that, so there is possibly something else missing.
i am trying to add a kernel as new package to a flake, which is overriding a shipped one, so maybe its totally unrelated and would work on "just doing overlays".

[K900]

Gonna draft this for now until I can sit down and double-check everything.

[ncfavier]

Revived this in #207095, along with some other minor simplifications.

which looks for me that overriding needs to be passed via argsOverride which then possibly has to be updated in the documentation.

Each kernel version calls buildLinux with args // { src, modDirVersion, version } // args.argsOverride, so you should only use argsOverride when you want to override one of the attributes in the middle. In general you shouldn't touch src or modDirVersion (which is tied to src, added a note about that in the manual). version can be overridden though, and that will only work with argsOverride.version. Maybe we should move args after the hardcoded attributes and just get rid of that argsOverride nonsense.