Struct Shadow

pub struct Shadow {
    pub f: File,
    pub map: BTreeMap<ShadowConst, ConstVal>,
    pub std_env: BTreeMap<String, String>,
    pub deny_const: BTreeSet<ShadowConst>,
    pub out_path: String,
    pub build_pattern: BuildPattern,
}

shadow-rs configuration.

This struct encapsulates the configuration for the shadow-rs build process. It allows for fine-grained control over various aspects of the build, including file output, build constants, environment variables, deny lists, and build patterns.

While it is possible to construct a Shadow instance manually, it is highly recommended to use the ShadowBuilder builder pattern structure provided by shadow-rs. The builder pattern simplifies the setup process and ensures that all necessary configurations are properly set up, allowing you to customize multiple aspects simultaneously, such as using a denylist and a hook function at the same time.

Fields

• f: The file that shadow-rs writes build information to. This file will contain serialized build constants and other metadata.
• map: A map of build constant identifiers to their corresponding ConstVal. These are the values that will be written into the file.
• std_env: A map of environment variables obtained through std::env::vars. These variables can influence the build process.
• deny_const: A set of build constant identifiers that should be excluded from the build process. This can be populated via ShadowBuilder::deny_const.
• out_path: The path where the generated files will be placed. This is usually derived from the OUT_DIR environment variable but can be customized via ShadowBuilder::out_path.
• build_pattern: Determines the strategy for triggering package rebuilds (Lazy, RealTime, or Custom). This affects when Cargo will rerun the build script and can be configured via ShadowBuilder::build_pattern.

Example

use std::collections::BTreeSet;
use shadow_rs::{ShadowBuilder, BuildPattern, CARGO_TREE, CARGO_METADATA};

ShadowBuilder::builder()
   .build_pattern(BuildPattern::RealTime)
   .deny_const(BTreeSet::from([CARGO_TREE, CARGO_METADATA]))
   .build().unwrap();

Fields

f: File

The file that shadow-rs writes build information to.

This file will contain all the necessary information about the build, including serialized build constants and other metadata.

map: BTreeMap<ShadowConst, ConstVal>

The values of build constants to be written.

This is a mapping from ShadowConst identifiers to their corresponding ConstVal objects. Each entry in this map represents a build constant that will be included in the final build.

std_env: BTreeMap<String, String>

Build environment variables, obtained through std::env::vars.

These environment variables can affect the build process and are captured here for consistency and reproducibility.

deny_const: BTreeSet<ShadowConst>

Constants in the deny list, passed through ShadowBuilder::deny_const.

This set contains build constant identifiers that should be excluded from the build process. By specifying these, you can prevent certain constants from being written into the build file.

out_path: String

The output path where generated files will be placed.

This specifies the directory where the build script will write its output. It’s typically set using the OUT_DIR environment variable but can be customized using ShadowBuilder::out_path.

build_pattern: BuildPattern

Determines the strategy for triggering package rebuilds.

This field sets the pattern for how often the package should be rebuilt. Options include Lazy, RealTime, and Custom, each with its own implications on the build frequency and conditions under which a rebuild is triggered. It can be configured using ShadowBuilder::build_pattern.

Implementations

impl Shadow

pub fn hook<F>(&self, f: F) -> SdResult<()>

where F: Fn(&File) -> SdResult<()>,

Write the build configuration specified by this Shadow instance. The hook function is run as well, allowing it to append to shadow-rs’s output.

pub fn deny_contains(&self, deny_const: ShadowConst) -> bool

Checks if the specified build constant is in the deny list.

Arguments

• deny_const - A value of type ShadowConst representing the build constant to check.

Returns

• true if the build constant is present in the deny list; otherwise, false.

pub fn build(deny_const: BTreeSet<ShadowConst>) -> SdResult<Shadow>

👎Deprecated since 0.37.0: Please use [ShadowBuilder::builder] instead

Create a new Shadow configuration with a provided denylist. The project source path and output file are automatically derived from Cargo build environment variables.

pub fn build_with( src_path: String, out_path: String, deny_const: BTreeSet<ShadowConst>, ) -> SdResult<Shadow>

👎Deprecated since 0.37.0: Please use [ShadowBuilder::builder] instead

pub fn cargo_rerun_if_env_changed(&self)

👎Deprecated since 0.37.0: Please use [ShadowBuilder::build_pattern] instead

Request Cargo to re-run the build script if any environment variable observed by this Shadow configuration changes.

pub fn cargo_rerun_env_inject(&self, env: &[&str])

👎Deprecated since 0.37.0: Please use [ShadowBuilder::build_pattern] instead

Request Cargo to re-run the build script if any of the specified environment variables change. This function is not influenced by this Shadow configuration.

Trait Implementations

impl Debug for Shadow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.