Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: consolidate info on manual linux kernel configs #263056

Merged
merged 1 commit into from
Nov 23, 2023

Conversation

DanielSidhion
Copy link
Member

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:
  • 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
Copy link
Contributor

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Contributor

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
Copy link
Contributor

Shawn8901 commented Oct 25, 2023

@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
Copy link
Contributor

@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 DanielSidhion changed the title doc: show how to use manual linux kernel configs doc: consolidate info on manual linux kernel configs Oct 26, 2023
@DanielSidhion
Copy link
Member Author

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.

doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
doc/builders/packages/linux.section.md Outdated Show resolved Hide resolved
nixos/doc/manual/configuration/linux-kernel.chapter.md Outdated Show resolved Hide resolved
nixos/doc/manual/configuration/linux-kernel.chapter.md Outdated Show resolved Hide resolved
Copy link
Contributor

@Shawn8901 Shawn8901 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@fricklerhandwerk fricklerhandwerk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

The Nixpkgs documentation on the linux kernel builders 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".
The NixOS documentation went a bit deeper on manual linux kernel
configs, but that information wasn't particularly NixOS-specific.

This commit consolidates the information related to building the
kernel on Nixpkgs's documentation, while keeping any additional
NixOS-specific information on NixOS's documentation.

An additional README.md was created for contributor-facing
documentation.
@fricklerhandwerk fricklerhandwerk merged commit 5707578 into NixOS:master Nov 23, 2023
6 of 7 checks passed
@DanielSidhion DanielSidhion deleted the kernel-docs branch November 23, 2023 17:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants