Module compiler

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 done¹. 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.
• 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
  The Metadata is a hash used to make unique file names for each unit in a build. It is also used for symbol mangling.
• 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.
• 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.
• CompileMode
  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.
• 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.
• 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.

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.
• cargo_rustc_higher_args_precedence 🔒
  Provides a way to change the precedence of cargo rustc -- <flags>.
• 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 🔒
• 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.
• 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 🔒