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 containg 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 machinary 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.
- Support for future-incompatible warning reporting.
- Utilities for building with rustdoc.
- Code for building the standard library.
- 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 use for symbol mangling. - 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 instruction 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.
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
- Generates a list of
--extern
arguments.