Struct SearchPath 

pub struct SearchPath { /* private fields */ }

The directories a header is looked for in, in order.

GCC’s order, because a different one produces header shadowing bugs that are miserable to diagnose: -iquote first and only for a quoted include, then -I, then -isystem, then the configured system directories, then -idirafter. The directory of the including file comes before all of it for a quoted include, and it is not part of the numbered list because #include_next must not be able to land back on it.

Implementations

impl SearchPath

pub fn new() -> SearchPath

An empty search path.

pub fn push_quote(&mut self, dir: impl Into<PathBuf>)

Adds a -iquote directory, searched only for a quoted include.

pub fn push_bracket(&mut self, dir: impl Into<PathBuf>)

Adds a -I directory.

pub fn push_system(&mut self, dir: impl Into<PathBuf>)

Adds a -isystem directory, or one of the target’s configured system directories.

pub fn push_after(&mut self, dir: impl Into<PathBuf>)

Adds a -idirafter directory, which is searched after everything else.

pub fn remove_duplicates(&mut self)

Drops the directories that are already on the path, the way GCC does.

A duplicate is not a harmless extra entry that costs one failed open. It changes what #include_next means, which is defined as continuing past the directory the current file came from: a header found in the first /usr/include writes #include_next <stdint.h> meaning “the one below me” and finds itself in the second, and a header set that ends in a fixed point of its own is one that includes itself forever or answers __has_include_next yes where the compiler it was written for said no. It shows up as soon as somebody passes the system directories on the command line, which the compat harness does deliberately and a build system does by accident.

A -I that names a system directory loses to the system entry rather than the other way round, and that is GCC’s rule and is documented as one: keeping the earlier one would move a system directory up the order and take the system treatment off the headers in it, so the -I is the one that goes.

Two names for one directory are two directories here, where GCC compares the device and the inode and sees through a symlink. That wants a file system that can answer the question and this one deliberately only reads.

pub fn dirs(&self) -> &[Dir]

Every directory, in search order.

pub fn start(&self, form: IncludeForm) -> usize

The first entry an include of this form looks at.

An angled include skips the -iquote directories, which is the only difference between the two chains once the including file’s own directory is out of the way.

pub fn resolve( &self, fs: &dyn FileSystem, name: &str, form: IncludeForm, relative_to: Option<&Path>, from: usize, ) -> Option<Found>

Finds name, starting at entry from of the search path.

relative_to is the directory of the file doing the including, tried first for a quoted include and ignored otherwise. Pass None for an #include_next, which is defined as continuing past the directory the current file was found in and so must not look next to it again.

An absolute name is opened directly and the search path is not consulted, which is what every C compiler does and what a generated header with an absolute path needs.

pub fn tried( &self, name: &str, form: IncludeForm, relative_to: Option<&Path>, from: usize, ) -> Vec<PathBuf>

The directories a failed SearchPath::resolve with the same arguments looked in.

spec/05-preprocessor.md section 5.7 makes printing this the required behaviour for a failed include, because “file not found” without the list of places that were tried is the diagnostic that wastes the most time in this part of the compiler.

Trait Implementations

impl Clone for SearchPath

fn clone(&self) -> SearchPath

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SearchPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SearchPath

fn default() -> SearchPath

Returns the “default value” for a type.

impl Eq for SearchPath

impl PartialEq for SearchPath

fn eq(&self, other: &SearchPath) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for SearchPath