# 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.
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.
future_incompat
  Support for future-incompatible warning reporting.
job_queue 🔒
  Management of the interaction between the main `cargo` 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. See `output_depinfo` for more.
output_sbom 🔒
  cargo-sbom precursor files for external tools to create SBOM files from. See `build_sbom_graph` for more.
rustdoc
  Utilities for building with rustdoc.
standard_lib
  Code for building the standard library.
timings 🔒
  Timing tracking.
unit 🔒
  Types and impls for `Unit`.
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 `UnitHash`s, including `Metadata::unit_id`, `Metadata::c_metadata`, and `Metadata::c_extra_filename`.
OutputOptions 🔒
  Configuration of the display of messages emitted by the compiler, e.g. diagnostics, warnings, errors, and message caching.
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.

## Constants§

RUSTDOC_CRATE_VERSION_FLAG 🔒

## 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§

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 and `cfg`.
add_error_format_and_color 🔒
  Adds `--error-format` to the command to execute.
add_plugin_deps 🔒
append_crate_version_flag 🔒
apply_env_config 🔒
  Applies environment variables from config `[env]` to `ProcessBuilder`.
build_base_args 🔒
  Adds essential rustc flags and environment variables to the command to execute.
build_deps_args 🔒
  Adds dependency-relevant rustc flags and environment variables to the command to execute, such as `-L` and `--extern`.
build_dir_remap 🔒
  Remap all paths pointing to `build.build-dir`, i.e., `[BUILD_DIR]/debug/deps/foo-[HASH].dwo` would be remapped to `/cargo/build-dir/debug/deps/foo-[HASH].dwo` (note the `/cargo/build-dir` prefix).
check_cfg_args 🔒
  Generates the `--check-cfg` arguments for the `unit`.
compile 🔒
  Builds up and enqueue a list of pending jobs onto the `job` queue.
crate_version_flag_already_present 🔒
descriptive_pkg_name 🔒
  Provides a package name with descriptive target information, e.g., ‘`foo` (bin “bar” test)’, ‘`foo` (lib doctest)’.
envify 🔒
extern_args
  Generates a list of `--extern` arguments.
features_args 🔒
  All active features for the unit passed as `--cfg features=<feature-name>`.
filter_dynamic_search_path 🔒
get_dynamic_search_path 🔒
link_targets 🔒
  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.
make_failed_scrape_diagnostic 🔒
  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 a `rustc` invocation before the job queue starts compiling any unit.
prepare_rustdoc 🔒
  Prepares flags and environments we can compute for a `rustdoc` 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 the `unit`.
rustdoc 🔒
  Creates a unit of work invoking `rustdoc` for documenting the `unit`.
rustdoc_dep_info_loc 🔒
  Gets the dep-info file emitted by rustdoc.
scrape_output_path 🔒
  Gets the file path of function call information output from `rustdoc`.
should_include_scrape_units 🔒
  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`.
trim_paths_args_rustdoc 🔒
  Like `trim_paths_args` but for rustdoc invocations.
verbose_if_simple_exit_code 🔒