Module cargo::core::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.
  • 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.

  1. Maybe -Zbuild-plan was designed to serve that purpose but still in flux

Modules

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 the Unit 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