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.

---

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

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.

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 🔒