Module compiler 

Interact with the compiler

If you consider ops::cargo_compile::compile as a rustc driver but on Cargo side, this module is kinda the rustc_interface for that merits. It contains all the interaction between Cargo and the rustc compiler, from preparing the context for the entire build process, to scheduling and executing each unit of work (e.g. running rustc), to managing and caching the output artifact of a build.

However, it hasn’t yet exposed a clear definition of each phase or session, like what rustc has done. Also, no one knows if Cargo really needs that. To be pragmatic, here we list a handful of items you may want to learn:

• BuildContext is a static context containing all information you need before a build gets started.
• BuildRunner is the center of the world, coordinating a running build and collecting information from it.
• custom_build is the home of build script executions and output parsing.
• fingerprint not only defines but also executes a set of rules to determine if a re-compile is needed.
• job_queue is where the parallelism, job scheduling, and communication machinery happen between Cargo and the compiler.
• layout defines and manages output artifacts of a build in the filesystem.
• unit_dependencies is for building a dependency graph for compilation from a result of dependency resolution.
• Unit contains sufficient information to build something, usually turning into a compiler invocation in a later phase.

Re-exports

use cargo_util::collections::HashMap; 🔒

use cargo_util::collections::HashSet; 🔒

use std::borrow::Cow; 🔒

use std::cell::OnceCell; 🔒

use std::env; 🔒

use std::env; 🔒

use std::ffi::OsStr; 🔒

use std::ffi::OsString; 🔒

use std::fmt::Display; 🔒

use std::fs; 🔒

use std::fs::File; 🔒

use std::io::BufRead; 🔒

use std::io::BufWriter; 🔒

use std::io::Write; 🔒

use std::ops::Deref; 🔒

use std::ops::Range; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::sync::Arc; 🔒

use std::sync::LazyLock; 🔒

use anyhow::Context as _; 🔒

use anyhow::Error; 🔒

use cargo_platform::Cfg; 🔒

use cargo_platform::Platform; 🔒

use cargo_util_schemas::core::CrateType; 🔒

use cargo_util_terminal::report::AnnotationKind; 🔒

use cargo_util_terminal::report::Group; 🔒

use cargo_util_terminal::report::Level; 🔒

use cargo_util_terminal::report::Renderer; 🔒

use cargo_util_terminal::report::Snippet; 🔒

use regex::Regex; 🔒

use tracing::debug; 🔒

use tracing::instrument; 🔒

use tracing::instrument; 🔒

use tracing::trace; 🔒

pub use self::build_config::UserIntent;

pub use self::build_config::BuildConfig;

pub use self::build_config::CompileMode;

pub use self::build_config::MessageFormat;

pub use self::build_context::BuildContext;

pub use self::build_context::DepKindSet;

pub use self::build_context::FileFlavor;

pub use self::build_context::FileType;

pub use self::build_context::RustcTargetData;

pub use self::build_context::TargetInfo;

pub use self::build_runner::BuildRunner;

pub use self::build_runner::Metadata;

pub use self::build_runner::UnitHash;

pub use self::compilation::Compilation;

pub use self::compilation::Doctest;

pub use self::compilation::UnitOutput;

pub use self::compile_kind::CompileKind;

pub use self::compile_kind::CompileKindFallback;

pub use self::compile_kind::CompileTarget;

pub use self::crate_type::CrateTypeExt;

pub use self::custom_build::LinkArgTarget;

pub use self::custom_build::BuildOutput;

pub use self::custom_build::BuildScriptOutputs;

pub use self::custom_build::BuildScripts;

pub use self::custom_build::LibraryPath;

pub(crate) use self::fingerprint::DirtyReason; 🔒

pub use self::fingerprint::RustdocFingerprint;

pub use self::job_queue::Freshness;

use self::job_queue::Job; 🔒

use self::job_queue::JobQueue; 🔒

use self::job_queue::JobState; 🔒

use self::job_queue::Work; 🔒

pub(crate) use self::layout::Layout; 🔒

pub use self::lto::Lto;

use self::output_depinfo::output_depinfo; 🔒

use self::output_sbom::build_sbom; 🔒

use self::trim_paths::trim_paths_args; 🔒

use self::trim_paths::trim_paths_args_rustdoc; 🔒

use self::unit_graph::UnitDep; 🔒

use crate::compiler::future_incompat::FutureIncompatReport; 🔒

use crate::compiler::locking::LockKey; 🔒

use crate::compiler::timings::SectionTiming; 🔒

pub use crate::compiler::unit::Unit;

pub use crate::compiler::unit::UnitIndex;

pub use crate::compiler::unit::UnitInterner;

use crate::context::FingerprintMethod; 🔒

use crate::diagnostics::get_key_value; 🔒

use crate::util::OnceExt; 🔒

use crate::util::errors::CargoResult; 🔒

use crate::util::errors::VerboseError; 🔒

use crate::util::interning::InternedString; 🔒

use crate::util::machine_message; 🔒

use crate::util::machine_message::Message; 🔒

use crate::util::add_path_args; 🔒

use crate::util::internal; 🔒

use crate::util::path_args; 🔒

use crate::workspace::Feature; 🔒

use crate::workspace::PackageId; 🔒

use crate::workspace::Target; 🔒

use crate::workspace::TargetKind; 🔒

use crate::workspace::manifest::TargetSourcePath; 🔒

use crate::workspace::profiles::PanicStrategy; 🔒

use crate::workspace::profiles::Profile; 🔒

use crate::workspace::profiles::StripInner; 🔒

use cargo_util::ExecStats; 🔒

use cargo_util::ProcessBuilder; 🔒

use cargo_util::ProcessError; 🔒

use cargo_util::paths; 🔒

use cargo_util_schemas::manifest::TomlDebugInfo; 🔒

use cargo_util_terminal::Verbosity; 🔒

use rustfix::diagnostics::Applicability; 🔒

Modules

artifact

Generate artifact information from unit dependencies for configuring the compiler environment.

build_config 🔒

build_context 🔒

BuildContext is a (mostly) static information about a build task.

build_runner 🔒

BuildRunner is the mutable state used during the build process.

compilation 🔒

Type definitions for the result of a compilation.

compile_kind 🔒

Type definitions for cross-compilation.

crate_type 🔒

custom_build 🔒

How to execute a build script and parse its output.

fingerprint 🔒

Tracks changes to determine if something needs to be recompiled.

future_incompat

Support for future-incompatible warning reporting.

job_queue 🔒

Management of the interaction between the main cargo and all spawned jobs.

layout 🔒

Management of the directory layout of a build

links 🔒

locking 🔒

This module handles the locking logic during compilation.

lto 🔒

output_depinfo 🔒

dep-info files for external build system integration. See output_depinfo for more.

output_sbom 🔒

cargo-sbom precursor files for external tools to create SBOM files from. See build_sbom_graph for more.

rustdoc

Utilities for building with rustdoc.

standard_lib

Code for building the standard library.

timings

Timing tracking.

trim_paths 🔒

Path prefix remapping for RFC 3127 trim-paths.

unit 🔒

Types and impls for Unit.

unit_dependencies

Constructs the dependency graph for compilation.

unit_graph

Serialization of UnitGraph for unstable option --unit-graph.

unused_deps

Structs

DefaultExecutor

A DefaultExecutor calls rustc without doing anything else. It is Cargo’s default behaviour.

ManifestErrorContext 🔒

Cloned and sendable context about the manifest file.

OutputOptions 🔒

Configuration of the display of messages emitted by the compiler, e.g. diagnostics, warnings, errors, and message caching.

Enums

CapLints 🔒

Constants

RUSTDOC_CRATE_VERSION_FLAG 🔒

Traits

Executor

A glorified callback for executing calls to rustc. Rather than calling rustc directly, we’ll use an Executor, giving clients an opportunity to intercept the build calls.

Functions

add_allow_features 🔒

Forwards -Zallow-features if it is set for cargo.

add_cap_lints 🔒

Adds --cap-lints to the command to execute.

add_codegen_incremental 🔒

Adds -C incremental=<path>.

add_codegen_linker 🔒

Adds -C linker=<path> if specified.

add_custom_flags 🔒

Adds extra rustc flags and environment variables collected from the output of a build-script to the command to execute, include custom environment variables and cfg.

add_error_format_and_color 🔒

Adds --error-format to the command to execute.

add_plugin_deps 🔒

append_crate_version_flag 🔒

apply_env_config 🔒

Applies environment variables from config [env] to ProcessBuilder.

build_base_args 🔒

Adds essential rustc flags and environment variables to the command to execute.

build_deps_args 🔒

Adds dependency-relevant rustc flags and environment variables to the command to execute, such as -L and --extern.

check_cfg_args 🔒

Generates the --check-cfg arguments for the unit.

compile 🔒

Builds up and enqueue a list of pending jobs onto the job queue.

compute_cap_lints 🔒

crate_version_flag_already_present 🔒

dep_paths_for_args 🔒

Generate a list of paths for the rustc -L args.

descriptive_pkg_name 🔒

Provides a package name with descriptive target information, e.g., ‘foo (bin “bar” test)’, ‘foo (lib doctest)’.

downgrade_lock_to_shared 🔒

envify 🔒

extern_args

Generates a list of --extern arguments.

features_args 🔒

All active features for the unit passed as --cfg features=<feature-name>.

filter_dynamic_search_path 🔒

get_dynamic_search_path 🔒

is_public_dependency_enabled 🔒

lib_search_paths

Generate a list of -L arguments

link_targets 🔒

Link the compiled target (often of form foo-{metadata_hash}) to the final target. This must happen during both “Fresh” and “Compile”.

lto_args 🔒

Adds LTO related codegen flags.

make_failed_scrape_diagnostic 🔒

Generates the warning message used when fallible doc-scrape units fail, either for rustdoc or rustc.

on_stderr_line 🔒

on_stderr_line_inner 🔒

Returns true if the line should be cached.

on_stdout_line 🔒

prebuild_lock_exclusive 🔒

prepare_rustc 🔒

Prepares flags and environments we can compute for a rustc invocation before the job queue starts compiling any unit.

prepare_rustdoc 🔒

Prepares flags and environments we can compute for a rustdoc invocation before the job queue starts compiling any unit.

replay_output_cache 🔒

Creates a unit of work that replays the cached compiler message.

rustc 🔒

Creates a unit of work invoking rustc for building the unit.

rustdoc 🔒

Creates a unit of work invoking rustdoc for documenting the unit.

rustdoc_dep_info_loc 🔒

Gets the dep-info file emitted by rustdoc.

scrape_output_path 🔒

Gets the file path of function call information output from rustdoc.

should_include_scrape_units 🔒

Checks if there are some scrape units waiting to be processed.

verbose_if_simple_exit_code 🔒