Expose kernel headers and perf to distributions

[Ben Hillis (benhillis)]

Summary

• mount kernel-matched headers from the unified artifacts VHD at /usr/src/linux-headers-$(uname -r) and point /lib/modules/$(uname -r)/build to them
• mount kernel-matched perf tooling at /usr/lib/linux-tools/$(uname -r), add it to the default PATH, and configure PERF_EXEC_PATH
• shadow an existing distro /usr/bin/perf with the matching bundled binary without replacing the distro file
• add WSL2 coverage for header compilation, perf execution, stale build links, and symlinked distro perf binaries

Follow-up to #41267.

Validation

• cmake --build . -- -m
• bin\x64\debug\test.bat /name:*KernelArtifacts*
• mkdocs build -f doc\mkdocs.yml
• .\FormatSource.ps1

[Copilot]

Pull request overview

This PR extends the unified kernel artifacts VHD integration to expose kernel-matched Linux headers and perf tooling inside WSL distributions, wiring the required mounts/env-vars through mini_init → distro init, and adding WSL2 tests + documentation to validate the behavior.

Changes:

• Add support to surface kernel headers at /usr/src/linux-headers-$(uname -r) and ensure /lib/modules/$(uname -r)/build points to them.
• Add support to surface perf at /usr/lib/linux-tools/$(uname -r), add it to default PATH, and set PERF_EXEC_PATH (plus optional shadowing of distro /usr/bin/perf).
• Add WSL2 test coverage for header usability, perf execution, and “stale artifact” replacement across VM restarts.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/windows/UnitTests.cpp	Adds WSL2 coverage validating header presence/usability, perf availability, and restart behavior.
src/shared/inc/lxinitshared.h	Introduces new env-var names for kernel headers/perf temporary mounts and target paths.
src/linux/init/WslDistributionConfig.h	Adds KernelPerfPath plumbing so perf can be added to PATH / configured in the environment block.
src/linux/init/util.cpp	Strengthens UtilMountFile() by validating the source is a regular file before mounting.
src/linux/init/main.cpp	Binds headers/perf from the artifacts VHD and passes them through to distro init via env-vars.
src/linux/init/config.cpp	Moves temporary mounts into the distro namespace; sets up build link and perf shadowing + env exposure.
doc/docs/technical-documentation/boot-process.md	Documents the new kernel headers/perf exposure behavior during boot.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/linux/init/config.cpp:188

• MoveTemporaryMount constructs RemoveMountAndEnvironmentOnScopeExit, which caches m_mountPath from getenv(). In RemoveMountAndEnvironmentOnScopeExit::~RemoveMountAndEnvironmentOnScopeExit() (config.cpp:114-137), unsetenv(m_environmentName) happens before umount2(m_mountPath)/rmdir(m_mountPath). Because getenv() pointers can be invalidated by unsetenv/setenv, this can use a dangling pointer and attempt to unmount an invalid path (undefined behavior). Consider storing a std::string copy of the mount path (or unmounting before unsetenv) so cleanup is safe.

    auto tempMount = RemoveMountAndEnvironmentOnScopeExit(MountEnvironmentName);
    const char* target = tempMount ? getenv(PathEnvironmentName) : nullptr;
    if (target == nullptr)
    {
        return;

src/linux/init/config.cpp:1198

• The comment says the distro file system is only modified when perf is present as a regular file, but the code uses stat("/usr/bin/perf"), which follows symlinks and will also modify the resolved target when /usr/bin/perf is a symlink to a regular file (as exercised by the new unit test). Please update the comment to match the actual behavior (or switch to lstat() if symlinked perf should be excluded).

        // If the distro ships its own perf, shadow it with a bind mount so that the binary matching the
        // running kernel is used.
        //
        // N.B. The distro's file system is only modified if perf is already present as a regular file.
        //      Distros without perf pick it up via $PATH instead.

[Blue (OneBlue)]

LGTM, one minor comment

[Blue (OneBlue)]

nit: I think this would be a bit easier to read if we just built in the current directory. We can just remove t in scope exit