# Module cargo::core::compiler::custom_build

source ·
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 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

- 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`.

## Constants

- CARGO_WARNING 🔒
  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 `Context`.
- 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.