Module cargo::core::compiler::custom_build

How to execute a build script and parse its output.

Preparing a build script run

A build script is an optional Rust script Cargo will run before building your package. As of this writing, two kinds of special Units will be constructed when there is a build script in a package.

• Build script compilation — This unit is generally the same as units that would compile other Cargo targets. It will recursively creates units of its dependencies. One biggest difference is that the Unit of compiling a build script is flagged as TargetKind::CustomBuild.
• Build script execution — During the construction of the UnitGraph, Cargo inserts a Unit with CompileMode::RunCustomBuild. This unit depends on the unit of compiling the associated build script, to ensure the executable is available before running. The Work of running the build script is prepared in the function prepare.

Running a build script

When running a build script, Cargo is aware of the progress and the result of a build script. Standard output is the chosen interprocess communication between Cargo and build script processes. A set of strings is defined for that purpose. These strings, a.k.a. instructions, are interpreted by BuildOutput::parse and stored in BuildRunner::build_script_outputs. The entire execution work is constructed by build_work.

Structs

• BuildDeps
  Dependency information as declared by a build script that might trigger a recompile of itself.
• BuildOutput
  Contains the parsed output of a custom build script.
• BuildScriptOutputs
  Map of packages to build script output.
• BuildScripts
  Linking information for a Unit.

Enums

• LinkArgTarget
  Represents one of the instructions from cargo::rustc-link-arg-* build script instruction family.

Constants

• NEW_CARGO_WARNING_SYNTAX 🔒
  A build script instruction that tells Cargo to display a warning after the build script has finished running. Read the doc for more.
• OLD_CARGO_WARNING_SYNTAX 🔒
  Deprecated: A build script instruction that tells Cargo to display a warning after the build script has finished running. Read the doc for more.

Functions

• build_map
  Computes several maps in BuildRunner.
• build_work 🔒
  Constructs the unit of work of running a build script.
• emit_build_output 🔒
  Emits the output of a build script as a machine_message::BuildScript JSON string to standard output.
• insert_warnings_in_build_outputs 🔒
  When a build script run fails, store only warnings and nuke other outputs, as they are likely broken.
• prepare
  Prepares a Work that executes the target as a custom build script.
• prepare_metabuild 🔒
  Prepares the Rust script for the unstable feature metabuild.
• prev_build_output 🔒
  Returns the previous parsed BuildOutput, if any, from a previous execution.