Skip to main content

Toolchain

Struct Toolchain 

Source
pub struct Toolchain {
    pub compiler: Option<PathBuf>,
    pub version: Option<String>,
    pub system_include_paths: Vec<PathBuf>,
    pub builtin_macros: Vec<CommandLineMacro>,
    pub cuda: bool,
    pub dialect: Option<Dialect>,
    pub standard: Option<String>,
    pub source: ToolchainSource,
    pub note: Option<String>,
}
Expand description

A compiler that answered, and what it said.

Fields§

§compiler: Option<PathBuf>

The compiler that was asked, as it was found. None in the last-resort case, where no compiler could be asked at all and only the system’s conventional header directories are known.

§version: Option<String>

Its version line, when it printed one: gcc version 15.1.0 (…), clang version 18.1.8, MSVC 14.35.32215 (_MSC_FULL_VER 193532215).

Kept for a human, not for a decision: when the analysis of a project is wrong because it was read against the wrong toolchain, the first question is which toolchain it was read against.

§system_include_paths: Vec<PathBuf>

The directories it searches for #include <…>, in its own order, normalized with case preserved — they are directories to open, not keys to compare. See parse_search_list.

§builtin_macros: Vec<CommandLineMacro>

Every macro the compiler predefines, as #define lines from -dM gave them.

The half of the macro environment that is not in any file: _WIN32, __x86_64__, __cplusplus and about 480 more. A condition like #ifdef _WIN32 or #if __cplusplus >= 201703L is a question about these, and there is nowhere else to get the answer. See parse_builtin_macros, and Toolchain::macros for how they are handed to a condition evaluator.

Empty is not “none of them are defined”: it means the compiler could not be asked, which Toolchain::note says out loud and which makes every condition naming one of these Unknown.

§cuda: bool

Is this a CUDA toolchain? — nvcc, or a compiler a CUDA project drives.

CUDA is not a dialect of C++ in the sense Dialect means: nvcc compiles host code by invoking a host compiler (MSVC on Windows, GCC on Linux — -ccbin picks it), so a .cu file is C++ and MSVC-or-GNU and CUDA at once. This flag is the third layer, and it is what the parser’s CUDA rules are behind (cpp_parser::ParserConfig::cuda): the placement qualifiers and the <<<…>>> brackets, which are syntax neither the language nor either vendor’s dialect has.

Read from the macro table (__CUDACC__ is nvcc’s own statement about itself) and, when there is no table, from the compiler’s name: an nvcc that could not be asked is still nvcc.

§dialect: Option<Dialect>

The dialect the parser should read the project’s files in, when the toolchain settles it.

From the macro table when there is one (_MSC_VER, __GNUC__), and from the compiler’s name when there is not and the name is unambiguous — a cl that could not be asked is still MSVC.

§standard: Option<String>

The language standard the compiler was asked about — what the project stated, or the assumption this analysis made because nothing stated one.

It is kept because the answer is not reproducible from anything else: the value of __cplusplus in Toolchain::builtin_macros is the value for this standard, and a reader comparing two runs of the same project — or asking why <format> is empty — needs to see which one it was. Toolchain::config puts it into the configuration, where crate::include::config::predefined_macros_of uses it to state __cplusplus/_MSVC_LANG even when the compiler could not be asked. See ASSUMED_STANDARD_MSVC.

§source: ToolchainSource

How this toolchain was found, which is the first thing to check when an analysis is wrong.

§note: Option<String>

Something a user should know about this answer, when there is something: that the macros are unknown, that the headers came from a convention rather than from a compiler.

Implementations§

Source§

impl Toolchain

Source

pub fn compiler_name(&self) -> String

The compiler, as a report spells it — including the case where there is none.

A method because five callers print it and each of them would otherwise write its own match on the Option — and because “no compiler” is a result here rather than a missing value: the headers may still be real (see ToolchainSource::SystemHeaders).

Source

pub fn module_note(&self, module: &str) -> String

Where this compiler keeps a module the project does not contain, and what would let it find one it does.

The sentence an analysis owes a reader who wrote import std; and got nothing. “No file in this project declares module std” is true and useless: the file exists on the machine, in a directory only the compiler knows, and which directory that is differs per compiler — so a message that named one of them would be wrong on two thirds of the machines this runs on.

§The three, and what is measured behind each
  • MSVC. import std; is C++23 and /std:c++latest (ASSUMED_STANDARD_MSVC is what this analysis asks for when a project states nothing). The source of the standard module ships with the toolchain: <VC>/Tools/MSVC/<version>/modules/std.ixx, and the build has to compile it into an .ifc and name it — /reference std=std.ifc, or /ifcSearchDir <dir>. Measured on 14.35.32215: the file is 3 194 bytes, a global module fragment with the C headers, then export module std; and an #include of every standard header. There is also std.compat.ixx beside it, which re-exports std and the C library’s global names.
  • GCC and Clang. A module has to have been built before anything can import it, and where the result goes is not a directory this analysis can look in and find the answer: GCC writes gcm.cache/<module>.gcm beside where the compiler was run, Clang names a prebuilt module file on the command line (-fmodule-file=<module>=<file>) or looks in -fprebuilt-module-path=<dir>. Neither ships the standard library as a module, so import std; needs a build step that a project has to have, and until it does there is no file to read.

Dialect has two values and these are three compilers, so GCC and Clang share a sentence — and that is the honest direction: the fact this layer has is “the compiler is MSVC or it is not”, and a sentence that guessed which of the two it is would be right half the time for no gain over one that names both mechanisms.

The compiler’s name is deliberately not in the sentence — the dialect is what decides it, and the reader already knows which compiler they are using.

Source

pub fn partition_note(&self, module: &str, partition: &str) -> String

Where this compiler keeps a partition’s interface unit, and what would let it find one.

The same question as Toolchain::module_note about a partition, which is not a module: import :area; is only legal inside the module that declares area, and the file that declares it is a unit of that module rather than a module of its own. So the note is not “build a module and name it” but “this partition has no file, and the module’s interface is compiled against it”.

§What the compiler requires, measured

target/build_partitions.bat, MSVC 14.35.32215, and the direction is the one that surprises:

cl /interface /ifcOutput shapes.ifc shapes.cppm                     → C7621: cannot find module partition "area"
cl /interface /ifcOutput shapes-area.ifc shapes-area.cppm           → ok, no /reference needed
cl /interface /ifcOutput shapes.ifc /reference shapes:area=shapes-area.ifc shapes.cppm → ok

The primary interface unit needs the partition’s .ifc; the partition needs nothing. The name on the command line is module:partition — shapes:area — which is the spelling the standard uses for a partition and is not the name of any module.

GCC and Clang are named rather than described precisely, for the reason Toolchain::module_note gives: this layer’s fact is “MSVC or not”, and the two build a partition into their module file the same way they build the module itself.

Source

pub fn standard_module_source(&self, module: &str) -> PathBuf

Where this toolchain ships the source of a standard module, if it ships one at all.

Beside the include directories rather than inside them — <VC>/Tools/MSVC/<version>/modules/std.ixx sits in a modules directory that is a sibling of include, which is why the module search has to look there (see ModuleScanner::search_directories) and why this is not just the first include path plus a name.

A path, not a promise: it is returned whether or not the file is there, because the answer is about where the toolchain keeps such a thing and a caller that wants to know whether it exists can ask the filesystem.

Source

pub fn macros(&self) -> Vec<(&str, Option<&str>)>

The predefined macros, as the map a condition is evaluated against.

A name with no value (#define __linux) maps to None, which is what defined(NAME) asks about; a name with one (#define __cplusplus 202002L) keeps it, which is what #if __cplusplus >= 201703L needs.

Source

pub fn include_paths(&self) -> Vec<IncludePath>

This toolchain’s directories as include paths — all of them system paths.

They are what -isystem would name, which is why diagnostics inside them are the compiler’s business rather than the project’s. The distinction is not cosmetic: it is what a consumer reads to decide whether an error in a file is worth showing the user.

Source

pub fn config(&self, base: &CompilerConfig) -> CompilerConfig

A configuration with this toolchain’s own directories appended.

§Why appended

Because that is where the compiler searches them. g++ -I dir finds dir before any of its own directories, and -isystem dir does too — so a project’s paths keep the positions the project gave them, and the toolchain’s come last, which is the order a #include is actually resolved in.

§Why it is idempotent

A directory already in the list is not added again. The first occurrence is the one that decides — a search stops at the first directory that has the file — so a second occurrence can never win, and a configuration that grew every time it was prepared would say the same thing in more words. (GCC reaches the same conclusion out loud: ignoring duplicate directory ….)

Trait Implementations§

Source§

impl Clone for Toolchain

Source§

fn clone(&self) -> Toolchain

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Toolchain

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Eq for Toolchain

Source§

impl PartialEq for Toolchain

Source§

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

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Toolchain

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.