[go: up one dir, main page]

Module compiler

cargo::core

Module compiler 

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

  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.
future_incompat
Support for future-incompatible warning reporting.
rustdoc
Utilities for building with rustdoc.
standard_lib
Code for building the standard library.
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.
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 specific action to be performed on each Unit of work.
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.
LibraryPath
Represents a path added to the library search path.
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.
UserIntent
Represents the high-level operation requested by the user.

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§

extern_args
Generates a list of --extern arguments.