Module search 

The header search path, as section 8.5 states it.

Design: spec/cross-compile/08-sysroots.md section 8.5.

The failure this prevents

Host contamination. A cross build picks up a header from the machine it is running on, produces something that works there, and does not work anywhere else. It is a quiet failure: the build succeeds, the tests pass on the build machine, and the binary is wrong somewhere the person who made it will not look.

spec/cross-compile/02-the-goal.md claim 5 is the test that catches it, byte identical output from two different hosts, and it catches it only because the rule below makes step 3 a function of the target when the target is not the host. That is why Options::host_include exists as a separate field rather than as a default: there is exactly one place a host directory can enter, it is guarded by one condition, and both are in include_paths where they can be read.

The rule

1. -I in the order given.
2. The compiler’s own headers. Always present, on every target including freestanding, and never taken from a sysroot, because stddef.h describes the compiler and not the C library.
3. The target’s libc headers, from --sysroot if given, otherwise from an Apple SDK this machine has, otherwise from our bundled tree for that tuple, otherwise, and only when the target is the host, from the host’s directories. For a Linux target the bundled case is four directories rather than two: the libc’s per architecture tree, the libc’s generic tree, the kernel’s asm/ for the architecture, and the kernel’s shared tree. That is the order zig cc -E -v prints for a glibc target.
4. Nothing else. No /usr/local/include in a cross build, ever.

-nostdinc removes 3, -nobuiltininc removes 2, --sysroot replaces 3’s root, and -isysroot is the Darwin spelling of the same thing.

Why an SDK is a source of its own

Options::sdk is the fourth of those sources and it is not one of the other three. It is not a tree the user named, because on a mac it is found by asking xcrun and on Windows by asking the Visual Studio installer, and nobody wrote either on the command line. It is not a bundled tree, because spec/cross-compile/13-distribution.md section 13.4 says we may never ship one. And it is not the host’s own directories, because the SDK holds the headers of every architecture of its platform rather than of this machine, so one installed SDK serves x86_64-macos on an arm64 mac and one Windows Kit serves aarch64-windows-msvc on an x86_64 box, which is what the platform’s own tools do with them.

The other half of the same rule is that a target behind one of those licence walls never takes the bundled branch at all, whatever the caller passes, because crate::Wall is the statement that no tree of ours can exist for it. A path under the cache for such a target would be a directory nothing will ever put a file in, named in a -v listing as though a fetch were coming.

Structs

Entry

One directory in the search path, and the reason it is there.

Options

What the driver knows that the rule needs.

Enums

Origin

Which of section 8.5’s four steps put a directory in the list.

Functions

include_paths

The directories to search for an included file, in order.