doc: consolidate info on manual linux kernel configs

[DanielSidhion]

Description of changes

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 PR gives a starting point on how to do these specialised kernel builds.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• 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/)
• 23.11 Release Notes (or backporting 23.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
• Fits CONTRIBUTING.md.

[Shawn8901]

Partly mentioned here, near the end of that chapter. Possibly cross linking between the article could be a good idea, so that it's easier to find, but on my opinion the explaination (which is also not super clear covered in the other part of the doc) fits more on how to configure, than how the builder should be documented.

[DanielSidhion]

Thanks for the review! I hadn't even seen that section on the NixOS documentation, partly because I'm not doing this for a NixOS system, but rather for a micro VM. This is what led me to creating this PR: most of the documentation on the kernel builder seems very NixOS-specific, but there are other valid reasons to build a kernel.

Given what I said above, I believe this documentation fits Nixpkg's documentation way more than NixOS's. The kernels built manually are very likely not intended to be used in NixOS, so I don't see why this should be seen as how to configure the kernel. The manual config kernel builder is almost an entirely different builder given how much pkgs.buildLinux adds on top of pkgs.linuxManualConfig.

What do you think, @Shawn8901 ? I'm leaning towards merging the information from NixOS's docs in this PR to consolidate details on the manual kernel build, and add a link on NixOS's docs to Nixpkg's section on manual kernel builds.

[DanielSidhion]

Just went through a lot of issues on the repo looking for more data on use cases, and found:

1. kernelTarget attr is ignored in buildKernel (linux) #234084 with a similar use case to mine (kernel used without NixOS)
2. Documentation Issue: How to rebuild a kernel with a custom kernel config #178476 using the custom kernel in NixOS
3. broken "kernel.features" in linuxManualConfig #216529 also using the custom kernel in NixOS

I still stand by the opinion that the pkgs.linuxManualConfig docs should be in Nixpkgs, but perhaps there should be a bit more to document on the NixOS side regarding kernel features and kernel packages specifically with pkgs.linuxManualConfig.

[Shawn8901]

I am totally fine with moving either and have no preference, which fits more, but possibly that question can be answered by someone of the documentation team (I am just a random person from the internet 🙂 ). I was just mentioning the other place, as i was kind of involved in one of them (the history of the second issue that you have linked, and their other linked issues, is the source of that), but would personally prefer to have one good doc for that, than have it split and to maintain basically the same content in multiple places, as the usecase overall is already kind of more rarely used, so we don't have many eyes on it, that use it regularly.

[Shawn8901]

@fricklerhandwerk , sorry for the ping, but from discourse I read often your name in relation to docs. :)
I am asking myself if the mentioned problem (or at least my problem) will go away, with all the work of nix.dev? Or are there any opinions about the docs of How to custom compilate kernels?
For me the argument, that it's not a NixOS-only use case totally make sense, so that people may not peek into the nixos docs.

[fricklerhandwerk]

@Shawn8901 thanks for the ping. I don't subscribe to Nixpkgs activities notifications as that gets out of hand quickly. For feedback on documentation, feel free to ping the @NixOS/documentation-team as these are multiple people, who'll be aware of the issue and then be able to quickly discuss it in place or in one of our meetings that happen twice a week.

I agree with you and @DanielSidhion that all the build-related docs should go into Nixpkgs, so merging them here is good. Thanks a lot for helping out! (Or as we tend to say in the docs team: taking a shovel)

Ping me again if you would like to receive and have the time to process a review pass on style and wording. I think it's not required here because the existing docs are okay, and just merging them is already a strong improvement. If you're motivated you can always do a follow-up to improve the text, following the Nix manual documentation style guide (the details on docBook, syntax, and the @docroot@ thing are specific to Nix and don't apply to Nixpkgs).

[DanielSidhion]

Thank you for all the discussion folks! @fricklerhandwerk I'm going ahead and requesting a review from you since I decided to change the structure of the text a bit. The how-to on adding a new kernel version feels a bit out of place, let me know if you think a specific section for that would be more appropriate.

[Shawn8901]

i did just a quick read over, and i am not a native english speaker (so will likely not see bad sentence building or so), but for what i read its good for me.

[fricklerhandwerk]

Really good, only a few nits left to pick. Ping me when done, I'll merge.