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 done1. 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.Context
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
- Generate artifact information from unit dependencies for configuring the compiler environment.
BuildContext
is a (mostly) static information about a build task.- A graph-like structure used to represent the rustc commands to build the package and the interdependencies between them.
- Type definitions for the result of a compilation.
- Type definitions for cross-compilation.
- context 🔒
Context
is the mutable state used during the build process. - How to execute a build script and parse its output.
- Tracks changes to determine if something needs to be recompiled.
- Support for future-incompatible warning reporting.
- Management of the interaction between the main
cargo
and all spawned jobs. - layout 🔒Management of the directory layout of a build
- links 🔒
- lto 🔒
- dep-info files for external build system integration. See
output_depinfo
for more. - Utilities for building with rustdoc.
- Code for building the standard library.
- timings 🔒Timing tracking.
- unit 🔒Types and impls for
Unit
. - Constructs the dependency graph for compilation.
- Serialization of
UnitGraph
for unstable option--unit-graph
.
Structs
- Configuration information for a rustc build.
- The build context, containing complete information needed for a build task before it gets started.
- Contains the parsed output of a custom build script.
- Map of packages to build script output.
- Linking information for a
Unit
. - A structure returning the result of a compilation.
- Abstraction for the representation of a compilation target that Cargo has.
- Collection of all the stuff that is needed to perform a build.
- A
DefaultExecutor
calls rustc without doing anything else. It is Cargo’s default behaviour. - Structure with enough information to run
rustdoc --test
. - Type of each file generated by a Unit.
- The
Metadata
is a hash used to make unique file names for each unit in a build. It is also used for symbol mangling. - Configuration of the display of messages emitted by the compiler, e.g. diagnostics, warnings, errors, and message caching.
- Structure used to deal with Rustdoc fingerprinting
- Collection of information about
rustc
and the host and target. - Information about the platform target gleaned from querying rustc.
- All information needed to define a unit.
- A small structure used to “intern”
Unit
values. - Information about the output of a unit.
Enums
- Indicator for how a unit is being compiled.
- The general “mode” for what to do. This is used for two purposes. The commands themselves pass this in to
compile_ws
to tell it the general execution strategy. This influences the default targets selected. The other use is in theUnit
struct to indicate what is being done with a specific target. - Types of the output artifact that the compiler emits. Usually distributable or linkable either statically or dynamically.
- Kind of each file generated by a Unit, part of
FileType
. - Indication of the freshness of a package.
- Represents one of the instructions from
cargo:rustc-link-arg-*
build script instruction family. - Possible ways to run rustc and request various parts of LTO.
- Kinds of build timings we can output.
Constants
Traits
- 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
- Forwards
-Zallow-features
if it is set for cargo. - Adds
--cap-lints
to the command to execute. - 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
. - Adds
--error-format
to the command to execute. - Applies environment variables from config
[env]
toProcessBuilder
. - Adds essential rustc flags and environment variables to the command to execute.
- compile 🔒Builds up and enqueue a list of pending jobs onto the
job
queue. - Provides a package name with descriptive target information, e.g., ‘
foo
(bin “bar” test)’, ‘foo
(lib doctest)’. - envify 🔒
- Generates a list of
--extern
arguments. - All active features for the unit passed as
--cfg features=<feature-name>
. - 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.
- Generates the warning message used when fallible doc-scrape units fail, either for rustdoc or rustc.
- Returns true if the line should be cached.
- Prepares flags and environments we can compute for a
rustc
invocation before the job queue starts compiling any unit. - Prepares flags and environments we can compute for a
rustdoc
invocation before the job queue starts compiling any unit. - Creates a unit of work that replays the cached compiler message.
- rustc 🔒Creates a unit of work invoking
rustc
for building theunit
. - rustdoc 🔒Creates a unit of work invoking
rustdoc
for documenting theunit
. - Gets the file path of function call information output from
rustdoc
. - Checks if there are some scrape units waiting to be processed.