This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/prs-ready-for-review/3032/445

@veprbl could you review this?

Strict header check diminishes the possibility that certain header file functionality will be lost. This, however, adds some burden to maintain those lists in the nixpkgs tree, as new headers may be added. Maybe I'm not aware of some common case that this is supposed to catch, but unless there is one, this would be better (IMO) implemented as an external experimental tool first.

Libsystem is assembled by borrowing headers for many apple packages, trying to make up a header stub imitating /Library/Developer/CommandLineTools/usr/include on our local macOS. We are pouring all headers to Libsystem, some are extra and some are missing comparing to the origin macOS, usually we don't care about the extra, but we need to make sure no file got lost after update.

The problem is, we don't know the exact header list and which package a header comes from. For example, NSSystemDirectories.h exists in an old Libc but not in the new one, so we need to borrow it from the old while others from the new. Same as libproc.h, but it could also be found in newer xnu, so we can change the source. However, these information is not on any record.

Apple is not much nice to opensource so we can't get the those headers from a tarball or a tool, and it's risky to update because apple may drop headers (they do!) in new release. But the headers we are using is several years old and it start to block normal use (#101229).

This PR could make it easy to find the missing headers during updating. Since we are assembling Libsystem inside nixpkgs (mainly in the installPhase of Libsystem), I think put the header list here should be proper.

Alternatively, we move all the headers to https://github.com/NixOS/darwin-stubs . (But this will take much more work comparing to this PR and #108590).

cc @matthewbauer