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 our bundled tree for that tuple, otherwise, and only when the target is the host, from the host’s directories.
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.

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.