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

Severity

Constants

CARGO_ERROR_SYNTAX 🔒

A build script instruction that tells Cargo to display an error after the build script has finished running. Read the doc for more.

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_log_messages_in_build_outputs 🔒

When a build script run fails, store only log messages, 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.

Type Aliases

LogMessage