Expand description
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 Unit
s 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 asTargetKind::CustomBuild
. - Build script execution — During the construction of the
UnitGraph
, Cargo inserts aUnit
withCompileMode::RunCustomBuild
. This unit depends on the unit of compiling the associated build script, to ensure the executable is available before running. TheWork
of running the build script is prepared in the functionprepare
.
§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§
- Dependency information as declared by a build script that might trigger a recompile of itself.
- Contains the parsed output of a custom build script.
- Map of packages to build script output.
- Linking information for a
Unit
.
Enums§
- Represents one of the instructions from
cargo::rustc-link-arg-*
build script instruction family.
Constants§
- A build script instruction that tells Cargo to display an error after the build script has finished running. Read the doc for more.
- A build script instruction that tells Cargo to display a warning after the build script has finished running. Read the doc for more.
- 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§
- Computes several maps in
BuildRunner
. - Constructs the unit of work of running a build script.
- Emits the output of a build script as a
machine_message::BuildScript
JSON string to standard output. - When a build script run fails, store only log messages, and nuke other outputs, as they are likely broken.
- Prepares a
Work
that executes the target as a custom build script. - Prepares the Rust script for the unstable feature metabuild.
- Returns the previous parsed
BuildOutput
, if any, from a previous execution.