Module compiler

Expand description

§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.

Maybe -Zbuild-plan was designed to serve that purpose but still in flux. ↩

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_plan 🔒: A graph-like structure used to represent the rustc commands to build the package and the interdependencies between them.
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 🔒
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.
unit 🔒: Types and impls for Unit.
unit_dependencies: Constructs the dependency graph for compilation.
unit_graph: Serialization of UnitGraph for unstable option --unit-graph.

Structs§

BuildConfig: Configuration information for a rustc build.
BuildContext: The build context, containing complete information needed for a build task before it gets started.
BuildOutput: Contains the parsed output of a custom build script.
BuildRunner: Collection of all the stuff that is needed to perform a build.
BuildScriptOutputs: Map of packages to build script output.
BuildScripts: Linking information for a Unit.
Compilation: A structure returning the result of a compilation.
CompileTarget: Abstraction for the representation of a compilation target that Cargo has.
DefaultExecutor: A DefaultExecutor calls rustc without doing anything else. It is Cargo’s default behaviour.
Doctest: Structure with enough information to run rustdoc --test.
FileType: Type of each file generated by a Unit.
Metadata: Metadata tracks several UnitHashs, including Metadata::unit_id, Metadata::c_metadata, and Metadata::c_extra_filename.
OutputOptions 🔒: Configuration of the display of messages emitted by the compiler, e.g. diagnostics, warnings, errors, and message caching.
RustDocFingerprint: Structure used to deal with Rustdoc fingerprinting
RustcTargetData: Collection of information about rustc and the host and target.
TargetInfo: Information about the platform target gleaned from querying rustc.
Unit: All information needed to define a unit.
UnitHash: Uniquely identify a Unit under specific circumstances, see Metadata for more.
UnitInterner: A small structure used to “intern” Unit values.
UnitOutput: Information about the output of a unit.

Enums§

CompileKind: Indicator for how a unit is being compiled.
CompileKindFallback: Fallback behavior in the CompileKind::from_requested_targets_with_fallback function when no targets are specified.
CompileMode: The general “mode” for what to do.
CrateType: Types of the output artifact that the compiler emits. Usually distributable or linkable either statically or dynamically.
FileFlavor: Kind of each file generated by a Unit, part of FileType.
Freshness: Indication of the freshness of a package.
LinkArgTarget: Represents one of the instructions from cargo::rustc-link-arg-* build script instruction family.
Lto: Possible ways to run rustc and request various parts of LTO.
MessageFormat
TimingOutput: Kinds of build timings we can output.

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_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.
crate_version_flag_already_present 🔒
descriptive_pkg_name 🔒: Provides a package name with descriptive target information, e.g., ‘foo (bin “bar” test)’, ‘foo (lib doctest)’.
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 🔒
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 🔒
package_remap 🔒: Path prefix remap rules for dependencies.
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.
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.
sysroot_remap 🔒: Path prefix remap rules for sysroot.
trim_paths_args 🔒: Generates the --remap-path-scope and --remap-path-prefix for RFC 3127. See also unstable feature -Ztrim-paths.
trim_paths_args_rustdoc 🔒: Like trim_paths_args but for rustdoc invocations.
verbose_if_simple_exit_code 🔒

Module compilerCopy item path