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 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 executaion — 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 Context::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 a warning after the build script has finished running. Read the doc for more.

Functions