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.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§
- 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.
- Support for future-incompatible warning reporting.
- job_
queue πManagement of the interaction between the maincargo
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. Seeoutput_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.
- Collection of all the stuff that is needed to perform a build.
- 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.
- 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. - Output
Options π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§
- 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 andcfg
. - Adds
--error-format
to the command to execute. - add_
plugin_ πdeps - apply_
env_ πconfig Applies environment variables from config[env]
toProcessBuilder
. - build_
base_ πargs Adds essential rustc flags and environment variables to the command to execute. - build_
deps_ πargs - Provides a way to change the precedence of
cargo rustc -- <flags>
. - check_
cfg_ πargs Generates the--check-cfg
arguments for theunit
. - compile πBuilds up and enqueue a list of pending jobs onto the
job
queue. - descriptive_
pkg_ πname Provides a package name with descriptive target information, e.g., βfoo
(bin βbarβ test)β, βfoo
(lib doctest)β. - envify π
- Generates a list of
--extern
arguments. - features_
args πAll active features for the unit passed as--cfg features=<feature-name>
. - link_
targets πLink the compiled target (often of formfoo-{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.
- 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 arustc
invocation before the job queue starts compiling any unit. - prepare_
rustdoc πPrepares flags and environments we can compute for arustdoc
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 theunit
. - rustdoc πCreates a unit of work invoking
rustdoc
for documenting theunit
. - scrape_
output_ πpath Gets the file path of function call information output fromrustdoc
. - 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
. - Like
trim_paths_args
but for rustdoc invocations.