#
cargo/core/compiler/
unit_dependencies.rs

    1//! Constructs the dependency graph for compilation.
    2//!
    3//! Rust code is typically organized as a set of Cargo packages. The
    4//! dependencies between the packages themselves are stored in the
    5//! [`Resolve`] struct. However, we can't use that information as is for
    6//! compilation! A package typically contains several targets, or crates,
    7//! and these targets has inter-dependencies. For example, you need to
    8//! compile the `lib` target before the `bin` one, and you need to compile
    9//! `build.rs` before either of those.
    10//!
    11//! So, we need to lower the `Resolve`, which specifies dependencies between
    12//! *packages*, to a graph of dependencies between their *targets*, and this
    13//! is exactly what this module is doing! Well, almost exactly: another
    14//! complication is that we might want to compile the same target several times
    15//! (for example, with and without tests), so we actually build a dependency
    16//! graph of [`Unit`]s, which capture these properties.
    17
    18use std::collections::{HashMap, HashSet};
    19
    20use tracing::trace;
    21
    22use crate::core::compiler::artifact::match_artifacts_kind_with_targets;
    23use crate::core::compiler::unit_graph::{UnitDep, UnitGraph};
    24use crate::core::compiler::{
    25    CompileKind, CompileMode, CrateType, RustcTargetData, Unit, UnitInterner,
    26};
    27use crate::core::dependency::{Artifact, ArtifactKind, ArtifactTarget, DepKind};
    28use crate::core::profiles::{Profile, Profiles, UnitFor};
    29use crate::core::resolver::features::{FeaturesFor, ResolvedFeatures};
    30use crate::core::resolver::Resolve;
    31use crate::core::{Dependency, Package, PackageId, PackageSet, Target, TargetKind, Workspace};
    32use crate::ops::resolve_all_features;
    33use crate::util::interning::InternedString;
    34use crate::util::GlobalContext;
    35use crate::CargoResult;
    36
    37const IS_NO_ARTIFACT_DEP: Option<&'static Artifact> = None;
    38
    39/// Collection of stuff used while creating the [`UnitGraph`].
    40struct State<'a, 'gctx> {
    41    ws: &'a Workspace<'gctx>,
    42    gctx: &'gctx GlobalContext,
    43    /// Stores the result of building the [`UnitGraph`].
    44    unit_dependencies: UnitGraph,
    45    package_set: &'a PackageSet<'gctx>,
    46    usr_resolve: &'a Resolve,
    47    usr_features: &'a ResolvedFeatures,
    48    /// Like `usr_resolve` but for building standard library (`-Zbuild-std`).
    49    std_resolve: Option<&'a Resolve>,
    50    /// Like `usr_features` but for building standard library (`-Zbuild-std`).
    51    std_features: Option<&'a ResolvedFeatures>,
    52    /// `true` while generating the dependencies for the standard library.
    53    is_std: bool,
    54    /// The mode we are compiling in. Used for preventing from building lib thrice.
    55    global_mode: CompileMode,
    56    target_data: &'a RustcTargetData<'gctx>,
    57    profiles: &'a Profiles,
    58    interner: &'a UnitInterner,
    59    // Units for `-Zrustdoc-scrape-examples`.
    60    scrape_units: &'a [Unit],
    61
    62    /// A set of edges in `unit_dependencies` where (a, b) means that the
    63    /// dependency from a to b was added purely because it was a dev-dependency.
    64    /// This is used during `connect_run_custom_build_deps`.
    65    dev_dependency_edges: HashSet<(Unit, Unit)>,
    66}
    67
    68/// A boolean-like to indicate if a `Unit` is an artifact or not.
    69#[derive(Copy, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
    70pub enum IsArtifact {
    71    Yes,
    72    No,
    73}
    74
    75impl IsArtifact {
    76    pub fn is_true(&self) -> bool {
    77        matches!(self, IsArtifact::Yes)
    78    }
    79}
    80
    81/// Then entry point for building a dependency graph of compilation units.
    82///
    83/// You can find some information for arguments from doc of [`State`].
    84#[tracing::instrument(skip_all)]
    85pub fn build_unit_dependencies<'a, 'gctx>(
    86    ws: &'a Workspace<'gctx>,
    87    package_set: &'a PackageSet<'gctx>,
    88    resolve: &'a Resolve,
    89    features: &'a ResolvedFeatures,
    90    std_resolve: Option<&'a (Resolve, ResolvedFeatures)>,
    91    roots: &[Unit],
    92    scrape_units: &[Unit],
    93    std_roots: &HashMap<CompileKind, Vec<Unit>>,
    94    global_mode: CompileMode,
    95    target_data: &'a RustcTargetData<'gctx>,
    96    profiles: &'a Profiles,
    97    interner: &'a UnitInterner,
    98) -> CargoResult<UnitGraph> {
    99    if roots.is_empty() {
    100        // If -Zbuild-std, don't attach units if there is nothing to build.
    101        // Otherwise, other parts of the code may be confused by seeing units
    102        // in the dep graph without a root.
    103        return Ok(HashMap::new());
    104    }
    105    let (std_resolve, std_features) = match std_resolve {
    106        Some((r, f)) => (Some(r), Some(f)),
    107        None => (None, None),
    108    };
    109    let mut state = State {
    110        ws,
    111        gctx: ws.gctx(),
    112        unit_dependencies: HashMap::new(),
    113        package_set,
    114        usr_resolve: resolve,
    115        usr_features: features,
    116        std_resolve,
    117        std_features,
    118        is_std: false,
    119        global_mode,
    120        target_data,
    121        profiles,
    122        interner,
    123        scrape_units,
    124        dev_dependency_edges: HashSet::new(),
    125    };
    126
    127    let std_unit_deps = calc_deps_of_std(&mut state, std_roots)?;
    128
    129    deps_of_roots(roots, &mut state)?;
    130    super::links::validate_links(state.resolve(), &state.unit_dependencies)?;
    131    // Hopefully there aren't any links conflicts with the standard library?
    132
    133    if let Some(std_unit_deps) = std_unit_deps {
    134        attach_std_deps(&mut state, std_roots, std_unit_deps);
    135    }
    136
    137    connect_run_custom_build_deps(&mut state);
    138
    139    // Dependencies are used in tons of places throughout the backend, many of
    140    // which affect the determinism of the build itself. As a result be sure
    141    // that dependency lists are always sorted to ensure we've always got a
    142    // deterministic output.
    143    for list in state.unit_dependencies.values_mut() {
    144        list.sort();
    145    }
    146    trace!("ALL UNIT DEPENDENCIES {:#?}", state.unit_dependencies);
    147
    148    Ok(state.unit_dependencies)
    149}
    150
    151/// Compute all the dependencies for the standard library.
    152fn calc_deps_of_std(
    153    state: &mut State<'_, '_>,
    154    std_roots: &HashMap<CompileKind, Vec<Unit>>,
    155) -> CargoResult<Option<UnitGraph>> {
    156    if std_roots.is_empty() {
    157        return Ok(None);
    158    }
    159    // Compute dependencies for the standard library.
    160    state.is_std = true;
    161    for roots in std_roots.values() {
    162        deps_of_roots(roots, state)?;
    163    }
    164    state.is_std = false;
    165    Ok(Some(std::mem::take(&mut state.unit_dependencies)))
    166}
    167
    168/// Add the standard library units to the `unit_dependencies`.
    169fn attach_std_deps(
    170    state: &mut State<'_, '_>,
    171    std_roots: &HashMap<CompileKind, Vec<Unit>>,
    172    std_unit_deps: UnitGraph,
    173) {
    174    // Attach the standard library as a dependency of every target unit.
    175    let mut found = false;
    176    for (unit, deps) in state.unit_dependencies.iter_mut() {
    177        if !unit.kind.is_host() && !unit.mode.is_run_custom_build() {
    178            deps.extend(std_roots[&unit.kind].iter().map(|unit| UnitDep {
    179                unit: unit.clone(),
    180                unit_for: UnitFor::new_normal(unit.kind),
    181                extern_crate_name: unit.pkg.name(),
    182                dep_name: None,
    183                // TODO: Does this `public` make sense?
    184                public: true,
    185                noprelude: true,
    186            }));
    187            found = true;
    188        }
    189    }
    190    // And also include the dependencies of the standard library itself. Don't
    191    // include these if no units actually needed the standard library.
    192    if found {
    193        for (unit, deps) in std_unit_deps.into_iter() {
    194            if let Some(other_unit) = state.unit_dependencies.insert(unit, deps) {
    195                panic!("std unit collision with existing unit: {:?}", other_unit);
    196            }
    197        }
    198    }
    199}
    200
    201/// Compute all the dependencies of the given root units.
    202/// The result is stored in `state.unit_dependencies`.
    203fn deps_of_roots(roots: &[Unit], state: &mut State<'_, '_>) -> CargoResult<()> {
    204    for unit in roots.iter() {
    205        // Dependencies of tests/benches should not have `panic` set.
    206        // We check the global test mode to see if we are running in `cargo
    207        // test` in which case we ensure all dependencies have `panic`
    208        // cleared, and avoid building the lib thrice (once with `panic`, once
    209        // without, once for `--test`). In particular, the lib included for
    210        // Doc tests and examples are `Build` mode here.
    211        let root_compile_kind = unit.kind;
    212        let unit_for = if unit.mode.is_any_test() || state.global_mode.is_rustc_test() {
    213            if unit.target.proc_macro() {
    214                // Special-case for proc-macros, which are forced to for-host
    215                // since they need to link with the proc_macro crate.
    216                UnitFor::new_host_test(state.gctx, root_compile_kind)
    217            } else {
    218                UnitFor::new_test(state.gctx, root_compile_kind)
    219            }
    220        } else if unit.target.is_custom_build() {
    221            // This normally doesn't happen, except `clean` aggressively
    222            // generates all units.
    223            UnitFor::new_host(false, root_compile_kind)
    224        } else if unit.target.proc_macro() {
    225            UnitFor::new_host(true, root_compile_kind)
    226        } else if unit.target.for_host() {
    227            // Plugin should never have panic set.
    228            UnitFor::new_compiler(root_compile_kind)
    229        } else {
    230            UnitFor::new_normal(root_compile_kind)
    231        };
    232        deps_of(unit, state, unit_for)?;
    233    }
    234
    235    Ok(())
    236}
    237
    238/// Compute the dependencies of a single unit, recursively computing all
    239/// transitive dependencies.
    240///
    241/// The result is stored in `state.unit_dependencies`.
    242fn deps_of(unit: &Unit, state: &mut State<'_, '_>, unit_for: UnitFor) -> CargoResult<()> {
    243    // Currently the `unit_dependencies` map does not include `unit_for`. This should
    244    // be safe for now. `TestDependency` only exists to clear the `panic`
    245    // flag, and you'll never ask for a `unit` with `panic` set as a
    246    // `TestDependency`. `CustomBuild` should also be fine since if the
    247    // requested unit's settings are the same as `Any`, `CustomBuild` can't
    248    // affect anything else in the hierarchy.
    249    if !state.unit_dependencies.contains_key(unit) {
    250        let unit_deps = compute_deps(unit, state, unit_for)?;
    251        state
    252            .unit_dependencies
    253            .insert(unit.clone(), unit_deps.clone());
    254        for unit_dep in unit_deps {
    255            deps_of(&unit_dep.unit, state, unit_dep.unit_for)?;
    256        }
    257    }
    258    Ok(())
    259}
    260
    261/// Returns the direct unit dependencies for the given `Unit`.
    262fn compute_deps(
    263    unit: &Unit,
    264    state: &mut State<'_, '_>,
    265    unit_for: UnitFor,
    266) -> CargoResult<Vec<UnitDep>> {
    267    if unit.mode.is_run_custom_build() {
    268        return compute_deps_custom_build(unit, unit_for, state);
    269    } else if unit.mode.is_doc() {
    270        // Note: this does not include doc test.
    271        return compute_deps_doc(unit, state, unit_for);
    272    }
    273
    274    let mut ret = Vec::new();
    275    let mut dev_deps = Vec::new();
    276    for (dep_pkg_id, deps) in state.deps(unit, unit_for) {
    277        let Some(dep_lib) = calc_artifact_deps(unit, unit_for, dep_pkg_id, &deps, state, &mut ret)?
    278        else {
    279            continue;
    280        };
    281        let dep_pkg = state.get(dep_pkg_id);
    282        let mode = check_or_build_mode(unit.mode, dep_lib);
    283        let dep_unit_for = unit_for.with_dependency(unit, dep_lib, unit_for.root_compile_kind());
    284
    285        let start = ret.len();
    286        if state.gctx.cli_unstable().dual_proc_macros
    287            && dep_lib.proc_macro()
    288            && !unit.kind.is_host()
    289        {
    290            let unit_dep = new_unit_dep(
    291                state,
    292                unit,
    293                dep_pkg,
    294                dep_lib,
    295                dep_unit_for,
    296                unit.kind,
    297                mode,
    298                IS_NO_ARTIFACT_DEP,
    299            )?;
    300            ret.push(unit_dep);
    301            let unit_dep = new_unit_dep(
    302                state,
    303                unit,
    304                dep_pkg,
    305                dep_lib,
    306                dep_unit_for,
    307                CompileKind::Host,
    308                mode,
    309                IS_NO_ARTIFACT_DEP,
    310            )?;
    311            ret.push(unit_dep);
    312        } else {
    313            let unit_dep = new_unit_dep(
    314                state,
    315                unit,
    316                dep_pkg,
    317                dep_lib,
    318                dep_unit_for,
    319                unit.kind.for_target(dep_lib),
    320                mode,
    321                IS_NO_ARTIFACT_DEP,
    322            )?;
    323            ret.push(unit_dep);
    324        }
    325
    326        // If the unit added was a dev-dependency unit, then record that in the
    327        // dev-dependencies array. We'll add this to
    328        // `state.dev_dependency_edges` at the end and process it later in
    329        // `connect_run_custom_build_deps`.
    330        if deps.iter().all(|d| !d.is_transitive()) {
    331            for dep in ret[start..].iter() {
    332                dev_deps.push((unit.clone(), dep.unit.clone()));
    333            }
    334        }
    335    }
    336    state.dev_dependency_edges.extend(dev_deps);
    337
    338    // If this target is a build script, then what we've collected so far is
    339    // all we need. If this isn't a build script, then it depends on the
    340    // build script if there is one.
    341    if unit.target.is_custom_build() {
    342        return Ok(ret);
    343    }
    344    ret.extend(dep_build_script(unit, unit_for, state)?);
    345
    346    // If this target is a binary, test, example, etc, then it depends on
    347    // the library of the same package. The call to `resolve.deps` above
    348    // didn't include `pkg` in the return values, so we need to special case
    349    // it here and see if we need to push `(pkg, pkg_lib_target)`.
    350    if unit.target.is_lib() && unit.mode != CompileMode::Doctest {
    351        return Ok(ret);
    352    }
    353    ret.extend(maybe_lib(unit, state, unit_for)?);
    354
    355    // If any integration tests/benches are being run, make sure that
    356    // binaries are built as well.
    357    if !unit.mode.is_check()
    358        && unit.mode.is_any_test()
    359        && (unit.target.is_test() || unit.target.is_bench())
    360    {
    361        let id = unit.pkg.package_id();
    362        ret.extend(
    363            unit.pkg
    364                .targets()
    365                .iter()
    366                .filter(|t| {
    367                    // Skip binaries with required features that have not been selected.
    368                    match t.required_features() {
    369                        Some(rf) if t.is_bin() => {
    370                            let features = resolve_all_features(
    371                                state.resolve(),
    372                                state.features(),
    373                                state.package_set,
    374                                id,
    375                            );
    376                            rf.iter().all(|f| features.contains(f))
    377                        }
    378                        None if t.is_bin() => true,
    379                        _ => false,
    380                    }
    381                })
    382                .map(|t| {
    383                    new_unit_dep(
    384                        state,
    385                        unit,
    386                        &unit.pkg,
    387                        t,
    388                        UnitFor::new_normal(unit_for.root_compile_kind()),
    389                        unit.kind.for_target(t),
    390                        CompileMode::Build,
    391                        IS_NO_ARTIFACT_DEP,
    392                    )
    393                })
    394                .collect::<CargoResult<Vec<UnitDep>>>()?,
    395        );
    396    }
    397
    398    Ok(ret)
    399}
    400
    401/// Find artifacts for all `deps` of `unit` and add units that build these artifacts
    402/// to `ret`.
    403fn calc_artifact_deps<'a>(
    404    unit: &Unit,
    405    unit_for: UnitFor,
    406    dep_id: PackageId,
    407    deps: &[&Dependency],
    408    state: &State<'a, '_>,
    409    ret: &mut Vec<UnitDep>,
    410) -> CargoResult<Option<&'a Target>> {
    411    let mut has_artifact_lib = false;
    412    let mut maybe_non_artifact_lib = false;
    413    let artifact_pkg = state.get(dep_id);
    414    for dep in deps {
    415        let Some(artifact) = dep.artifact() else {
    416            maybe_non_artifact_lib = true;
    417            continue;
    418        };
    419        has_artifact_lib |= artifact.is_lib();
    420        // Custom build scripts (build/compile) never get artifact dependencies,
    421        // but the run-build-script step does (where it is handled).
    422        if !unit.target.is_custom_build() {
    423            debug_assert!(
    424                !unit.mode.is_run_custom_build(),
    425                "BUG: This should be handled in a separate branch"
    426            );
    427            ret.extend(artifact_targets_to_unit_deps(
    428                unit,
    429                unit_for.with_artifact_features(artifact),
    430                state,
    431                artifact
    432                    .target()
    433                    .and_then(|t| match t {
    434                        ArtifactTarget::BuildDependencyAssumeTarget => None,
    435                        ArtifactTarget::Force(kind) => Some(CompileKind::Target(kind)),
    436                    })
    437                    .unwrap_or(unit.kind),
    438                artifact_pkg,
    439                dep,
    440            )?);
    441        }
    442    }
    443    if has_artifact_lib || maybe_non_artifact_lib {
    444        Ok(artifact_pkg.targets().iter().find(|t| t.is_lib()))
    445    } else {
    446        Ok(None)
    447    }
    448}
    449
    450/// Returns the dependencies needed to run a build script.
    451///
    452/// The `unit` provided must represent an execution of a build script, and
    453/// the returned set of units must all be run before `unit` is run.
    454fn compute_deps_custom_build(
    455    unit: &Unit,
    456    unit_for: UnitFor,
    457    state: &State<'_, '_>,
    458) -> CargoResult<Vec<UnitDep>> {
    459    if let Some(links) = unit.pkg.manifest().links() {
    460        if unit.links_overrides.get(links).is_some() {
    461            // Overridden build scripts don't have any dependencies.
    462            return Ok(Vec::new());
    463        }
    464    }
    465    // All dependencies of this unit should use profiles for custom builds.
    466    // If this is a build script of a proc macro, make sure it uses host
    467    // features.
    468    let script_unit_for = unit_for.for_custom_build();
    469    // When not overridden, then the dependencies to run a build script are:
    470    //
    471    // 1. Compiling the build script itself.
    472    // 2. For each immediate dependency of our package which has a `links`
    473    //    key, the execution of that build script.
    474    //
    475    // We don't have a great way of handling (2) here right now so this is
    476    // deferred until after the graph of all unit dependencies has been
    477    // constructed.
    478    let compile_script_unit = new_unit_dep(
    479        state,
    480        unit,
    481        &unit.pkg,
    482        &unit.target,
    483        script_unit_for,
    484        // Build scripts always compiled for the host.
    485        CompileKind::Host,
    486        CompileMode::Build,
    487        IS_NO_ARTIFACT_DEP,
    488    )?;
    489
    490    let mut result = vec![compile_script_unit];
    491
    492    // Include any artifact dependencies.
    493    //
    494    // This is essentially the same as `calc_artifact_deps`, but there are some
    495    // subtle differences that require this to be implemented differently.
    496    //
    497    // Produce units that build all required artifact kinds (like binaries,
    498    // static libraries, etc) with the correct compile target.
    499    //
    500    // Computing the compile target for artifact units is more involved as it has to handle
    501    // various target configurations specific to artifacts, like `target = "target"` and
    502    // `target = "<triple>"`, which makes knowing the root units compile target
    503    // `root_unit_compile_target` necessary.
    504    let root_unit_compile_target = unit_for.root_compile_kind();
    505    let unit_for = UnitFor::new_host(/*host_features*/ true, root_unit_compile_target);
    506    for (dep_pkg_id, deps) in state.deps(unit, script_unit_for) {
    507        for dep in deps {
    508            if dep.kind() != DepKind::Build || dep.artifact().is_none() {
    509                continue;
    510            }
    511            let artifact_pkg = state.get(dep_pkg_id);
    512            let artifact = dep.artifact().expect("artifact dep");
    513            let resolved_artifact_compile_kind = artifact
    514                .target()
    515                .map(|target| target.to_resolved_compile_kind(root_unit_compile_target));
    516
    517            result.extend(artifact_targets_to_unit_deps(
    518                unit,
    519                unit_for.with_artifact_features_from_resolved_compile_kind(
    520                    resolved_artifact_compile_kind,
    521                ),
    522                state,
    523                resolved_artifact_compile_kind.unwrap_or(CompileKind::Host),
    524                artifact_pkg,
    525                dep,
    526            )?);
    527        }
    528    }
    529
    530    Ok(result)
    531}
    532
    533/// Given a `parent` unit containing a dependency `dep` whose package is `artifact_pkg`,
    534/// find all targets in `artifact_pkg` which refer to the `dep`s artifact declaration
    535/// and turn them into units.
    536/// Due to the nature of artifact dependencies, a single dependency in a manifest can
    537/// cause one or more targets to be build, for instance with
    538/// `artifact = ["bin:a", "bin:b", "staticlib"]`, which is very different from normal
    539/// dependencies which cause only a single unit to be created.
    540///
    541/// `compile_kind` is the computed kind for the future artifact unit
    542/// dependency, only the caller can pick the correct one.
    543fn artifact_targets_to_unit_deps(
    544    parent: &Unit,
    545    parent_unit_for: UnitFor,
    546    state: &State<'_, '_>,
    547    compile_kind: CompileKind,
    548    artifact_pkg: &Package,
    549    dep: &Dependency,
    550) -> CargoResult<Vec<UnitDep>> {
    551    let ret =
    552        match_artifacts_kind_with_targets(dep, artifact_pkg.targets(), parent.pkg.name().as_str())?
    553            .into_iter()
    554            .flat_map(|(artifact_kind, target)| {
    555                // We split target libraries into individual units, even though rustc is able
    556                // to produce multiple kinds in a single invocation for the sole reason that
    557                // each artifact kind has its own output directory, something we can't easily
    558                // teach rustc for now.
    559                match target.kind() {
    560                    TargetKind::Lib(kinds) => Box::new(
    561                        kinds
    562                            .iter()
    563                            .filter(move |tk| match (tk, artifact_kind) {
    564                                (CrateType::Cdylib, ArtifactKind::Cdylib) => true,
    565                                (CrateType::Staticlib, ArtifactKind::Staticlib) => true,
    566                                _ => false,
    567                            })
    568                            .map(|target_kind| {
    569                                new_unit_dep(
    570                                    state,
    571                                    parent,
    572                                    artifact_pkg,
    573                                    target
    574                                        .clone()
    575                                        .set_kind(TargetKind::Lib(vec![target_kind.clone()])),
    576                                    parent_unit_for,
    577                                    compile_kind,
    578                                    CompileMode::Build,
    579                                    dep.artifact(),
    580                                )
    581                            }),
    582                    ) as Box<dyn Iterator<Item = _>>,
    583                    _ => Box::new(std::iter::once(new_unit_dep(
    584                        state,
    585                        parent,
    586                        artifact_pkg,
    587                        target,
    588                        parent_unit_for,
    589                        compile_kind,
    590                        CompileMode::Build,
    591                        dep.artifact(),
    592                    ))),
    593                }
    594            })
    595            .collect::<Result<Vec<_>, _>>()?;
    596    Ok(ret)
    597}
    598
    599/// Returns the dependencies necessary to document a package.
    600fn compute_deps_doc(
    601    unit: &Unit,
    602    state: &mut State<'_, '_>,
    603    unit_for: UnitFor,
    604) -> CargoResult<Vec<UnitDep>> {
    605    // To document a library, we depend on dependencies actually being
    606    // built. If we're documenting *all* libraries, then we also depend on
    607    // the documentation of the library being built.
    608    let mut ret = Vec::new();
    609    for (id, deps) in state.deps(unit, unit_for) {
    610        let Some(dep_lib) = calc_artifact_deps(unit, unit_for, id, &deps, state, &mut ret)? else {
    611            continue;
    612        };
    613        let dep_pkg = state.get(id);
    614        // Rustdoc only needs rmeta files for regular dependencies.
    615        // However, for plugins/proc macros, deps should be built like normal.
    616        let mode = check_or_build_mode(unit.mode, dep_lib);
    617        let dep_unit_for = unit_for.with_dependency(unit, dep_lib, unit_for.root_compile_kind());
    618        let lib_unit_dep = new_unit_dep(
    619            state,
    620            unit,
    621            dep_pkg,
    622            dep_lib,
    623            dep_unit_for,
    624            unit.kind.for_target(dep_lib),
    625            mode,
    626            IS_NO_ARTIFACT_DEP,
    627        )?;
    628        ret.push(lib_unit_dep);
    629        if dep_lib.documented() {
    630            if let CompileMode::Doc { deps: true, .. } = unit.mode {
    631                // Document this lib as well.
    632                let doc_unit_dep = new_unit_dep(
    633                    state,
    634                    unit,
    635                    dep_pkg,
    636                    dep_lib,
    637                    dep_unit_for,
    638                    unit.kind.for_target(dep_lib),
    639                    unit.mode,
    640                    IS_NO_ARTIFACT_DEP,
    641                )?;
    642                ret.push(doc_unit_dep);
    643            }
    644        }
    645    }
    646
    647    // Be sure to build/run the build script for documented libraries.
    648    ret.extend(dep_build_script(unit, unit_for, state)?);
    649
    650    // If we document a binary/example, we need the library available.
    651    if unit.target.is_bin() || unit.target.is_example() {
    652        // build the lib
    653        ret.extend(maybe_lib(unit, state, unit_for)?);
    654        // and also the lib docs for intra-doc links
    655        if let Some(lib) = unit
    656            .pkg
    657            .targets()
    658            .iter()
    659            .find(|t| t.is_linkable() && t.documented())
    660        {
    661            let dep_unit_for = unit_for.with_dependency(unit, lib, unit_for.root_compile_kind());
    662            let lib_doc_unit = new_unit_dep(
    663                state,
    664                unit,
    665                &unit.pkg,
    666                lib,
    667                dep_unit_for,
    668                unit.kind.for_target(lib),
    669                unit.mode,
    670                IS_NO_ARTIFACT_DEP,
    671            )?;
    672            ret.push(lib_doc_unit);
    673        }
    674    }
    675
    676    // Add all units being scraped for examples as a dependency of top-level Doc units.
    677    if state.ws.unit_needs_doc_scrape(unit) {
    678        for scrape_unit in state.scrape_units.iter() {
    679            let scrape_unit_for = UnitFor::new_normal(scrape_unit.kind);
    680            deps_of(scrape_unit, state, scrape_unit_for)?;
    681            ret.push(new_unit_dep(
    682                state,
    683                scrape_unit,
    684                &scrape_unit.pkg,
    685                &scrape_unit.target,
    686                scrape_unit_for,
    687                scrape_unit.kind,
    688                scrape_unit.mode,
    689                IS_NO_ARTIFACT_DEP,
    690            )?);
    691        }
    692    }
    693
    694    Ok(ret)
    695}
    696
    697fn maybe_lib(
    698    unit: &Unit,
    699    state: &mut State<'_, '_>,
    700    unit_for: UnitFor,
    701) -> CargoResult<Option<UnitDep>> {
    702    unit.pkg
    703        .targets()
    704        .iter()
    705        .find(|t| t.is_linkable())
    706        .map(|t| {
    707            let mode = check_or_build_mode(unit.mode, t);
    708            let dep_unit_for = unit_for.with_dependency(unit, t, unit_for.root_compile_kind());
    709            new_unit_dep(
    710                state,
    711                unit,
    712                &unit.pkg,
    713                t,
    714                dep_unit_for,
    715                unit.kind.for_target(t),
    716                mode,
    717                IS_NO_ARTIFACT_DEP,
    718            )
    719        })
    720        .transpose()
    721}
    722
    723/// If a build script is scheduled to be run for the package specified by
    724/// `unit`, this function will return the unit to run that build script.
    725///
    726/// Overriding a build script simply means that the running of the build
    727/// script itself doesn't have any dependencies, so even in that case a unit
    728/// of work is still returned. `None` is only returned if the package has no
    729/// build script.
    730fn dep_build_script(
    731    unit: &Unit,
    732    unit_for: UnitFor,
    733    state: &State<'_, '_>,
    734) -> CargoResult<Option<UnitDep>> {
    735    unit.pkg
    736        .targets()
    737        .iter()
    738        .find(|t| t.is_custom_build())
    739        .map(|t| {
    740            // The profile stored in the Unit is the profile for the thing
    741            // the custom build script is running for.
    742            let profile = state.profiles.get_profile_run_custom_build(&unit.profile);
    743            // UnitFor::for_custom_build is used because we want the `host` flag set
    744            // for all of our build dependencies (so they all get
    745            // build-override profiles), including compiling the build.rs
    746            // script itself.
    747            //
    748            // If `is_for_host_features` here is `false`, that means we are a
    749            // build.rs script for a normal dependency and we want to set the
    750            // CARGO_FEATURE_* environment variables to the features as a
    751            // normal dep.
    752            //
    753            // If `is_for_host_features` here is `true`, that means that this
    754            // package is being used as a build dependency or proc-macro, and
    755            // so we only want to set CARGO_FEATURE_* variables for the host
    756            // side of the graph.
    757            //
    758            // Keep in mind that the RunCustomBuild unit and the Compile
    759            // build.rs unit use the same features. This is because some
    760            // people use `cfg!` and `#[cfg]` expressions to check for enabled
    761            // features instead of just checking `CARGO_FEATURE_*` at runtime.
    762            // In the case with the new feature resolver (decoupled host
    763            // deps), and a shared dependency has different features enabled
    764            // for normal vs. build, then the build.rs script will get
    765            // compiled twice. I believe it is not feasible to only build it
    766            // once because it would break a large number of scripts (they
    767            // would think they have the wrong set of features enabled).
    768            let script_unit_for = unit_for.for_custom_build();
    769            new_unit_dep_with_profile(
    770                state,
    771                unit,
    772                &unit.pkg,
    773                t,
    774                script_unit_for,
    775                unit.kind,
    776                CompileMode::RunCustomBuild,
    777                profile,
    778                IS_NO_ARTIFACT_DEP,
    779            )
    780        })
    781        .transpose()
    782}
    783
    784/// Choose the correct mode for dependencies.
    785fn check_or_build_mode(mode: CompileMode, target: &Target) -> CompileMode {
    786    match mode {
    787        CompileMode::Check { .. } | CompileMode::Doc { .. } | CompileMode::Docscrape => {
    788            if target.for_host() {
    789                // Plugin and proc macro targets should be compiled like
    790                // normal.
    791                CompileMode::Build
    792            } else {
    793                // Regular dependencies should not be checked with --test.
    794                // Regular dependencies of doc targets should emit rmeta only.
    795                CompileMode::Check { test: false }
    796            }
    797        }
    798        _ => CompileMode::Build,
    799    }
    800}
    801
    802/// Create a new Unit for a dependency from `parent` to `pkg` and `target`.
    803fn new_unit_dep(
    804    state: &State<'_, '_>,
    805    parent: &Unit,
    806    pkg: &Package,
    807    target: &Target,
    808    unit_for: UnitFor,
    809    kind: CompileKind,
    810    mode: CompileMode,
    811    artifact: Option<&Artifact>,
    812) -> CargoResult<UnitDep> {
    813    let is_local = pkg.package_id().source_id().is_path() && !state.is_std;
    814    let profile = state.profiles.get_profile(
    815        pkg.package_id(),
    816        state.ws.is_member(pkg),
    817        is_local,
    818        unit_for,
    819        kind,
    820    );
    821    new_unit_dep_with_profile(
    822        state, parent, pkg, target, unit_for, kind, mode, profile, artifact,
    823    )
    824}
    825
    826fn new_unit_dep_with_profile(
    827    state: &State<'_, '_>,
    828    parent: &Unit,
    829    pkg: &Package,
    830    target: &Target,
    831    unit_for: UnitFor,
    832    kind: CompileKind,
    833    mode: CompileMode,
    834    profile: Profile,
    835    artifact: Option<&Artifact>,
    836) -> CargoResult<UnitDep> {
    837    let (extern_crate_name, dep_name) = state.resolve().extern_crate_name_and_dep_name(
    838        parent.pkg.package_id(),
    839        pkg.package_id(),
    840        target,
    841    )?;
    842    let public = state
    843        .resolve()
    844        .is_public_dep(parent.pkg.package_id(), pkg.package_id());
    845    let features_for = unit_for.map_to_features_for(artifact);
    846    let artifact_target = match features_for {
    847        FeaturesFor::ArtifactDep(target) => Some(target),
    848        _ => None,
    849    };
    850    let features = state.activated_features(pkg.package_id(), features_for);
    851    let unit = state.interner.intern(
    852        pkg,
    853        target,
    854        profile,
    855        kind,
    856        mode,
    857        features,
    858        state.target_data.info(kind).rustflags.clone(),
    859        state.target_data.info(kind).rustdocflags.clone(),
    860        state
    861            .target_data
    862            .target_config(kind)
    863            .links_overrides
    864            .clone(),
    865        state.is_std,
    866        /*dep_hash*/ 0,
    867        artifact.map_or(IsArtifact::No, |_| IsArtifact::Yes),
    868        artifact_target,
    869    );
    870    Ok(UnitDep {
    871        unit,
    872        unit_for,
    873        extern_crate_name,
    874        dep_name,
    875        public,
    876        noprelude: false,
    877    })
    878}
    879
    880/// Fill in missing dependencies for units of the `RunCustomBuild`
    881///
    882/// As mentioned above in `compute_deps_custom_build` each build script
    883/// execution has two dependencies. The first is compiling the build script
    884/// itself (already added) and the second is that all crates the package of the
    885/// build script depends on with `links` keys, their build script execution. (a
    886/// bit confusing eh?)
    887///
    888/// Here we take the entire `deps` map and add more dependencies from execution
    889/// of one build script to execution of another build script.
    890fn connect_run_custom_build_deps(state: &mut State<'_, '_>) {
    891    let mut new_deps = Vec::new();
    892
    893    {
    894        let state = &*state;
    895        // First up build a reverse dependency map. This is a mapping of all
    896        // `RunCustomBuild` known steps to the unit which depends on them. For
    897        // example a library might depend on a build script, so this map will
    898        // have the build script as the key and the library would be in the
    899        // value's set.
    900        let mut reverse_deps_map = HashMap::new();
    901        for (unit, deps) in state.unit_dependencies.iter() {
    902            for dep in deps {
    903                if dep.unit.mode == CompileMode::RunCustomBuild {
    904                    reverse_deps_map
    905                        .entry(dep.unit.clone())
    906                        .or_insert_with(HashSet::new)
    907                        .insert(unit);
    908                }
    909            }
    910        }
    911
    912        // Next, we take a look at all build scripts executions listed in the
    913        // dependency map. Our job here is to take everything that depends on
    914        // this build script (from our reverse map above) and look at the other
    915        // package dependencies of these parents.
    916        //
    917        // If we depend on a linkable target and the build script mentions
    918        // `links`, then we depend on that package's build script! Here we use
    919        // `dep_build_script` to manufacture an appropriate build script unit to
    920        // depend on.
    921        for unit in state
    922            .unit_dependencies
    923            .keys()
    924            .filter(|k| k.mode == CompileMode::RunCustomBuild)
    925        {
    926            // This list of dependencies all depend on `unit`, an execution of
    927            // the build script.
    928            let Some(reverse_deps) = reverse_deps_map.get(unit) else {
    929                continue;
    930            };
    931
    932            let to_add = reverse_deps
    933                .iter()
    934                // Get all sibling dependencies of `unit`
    935                .flat_map(|reverse_dep| {
    936                    state.unit_dependencies[reverse_dep]
    937                        .iter()
    938                        .map(move |a| (reverse_dep, a))
    939                })
    940                // Only deps with `links`.
    941                .filter(|(_parent, other)| {
    942                    other.unit.pkg != unit.pkg
    943                        && other.unit.target.is_linkable()
    944                        && other.unit.pkg.manifest().links().is_some()
    945                })
    946                // Avoid cycles when using the doc --scrape-examples feature:
    947                // Say a workspace has crates A and B where A has a build-dependency on B.
    948                // The Doc units for A and B will have a dependency on the Docscrape for both A and B.
    949                // So this would add a dependency from B-build to A-build, causing a cycle:
    950                //   B (build) -> A (build) -> B(build)
    951                // See the test scrape_examples_avoid_build_script_cycle for a concrete example.
    952                // To avoid this cycle, we filter out the B -> A (docscrape) dependency.
    953                .filter(|(_parent, other)| !other.unit.mode.is_doc_scrape())
    954                // Skip dependencies induced via dev-dependencies since
    955                // connections between `links` and build scripts only happens
    956                // via normal dependencies. Otherwise since dev-dependencies can
    957                // be cyclic we could have cyclic build-script executions.
    958                .filter_map(move |(parent, other)| {
    959                    if state
    960                        .dev_dependency_edges
    961                        .contains(&((*parent).clone(), other.unit.clone()))
    962                    {
    963                        None
    964                    } else {
    965                        Some(other)
    966                    }
    967                })
    968                // Get the RunCustomBuild for other lib.
    969                .filter_map(|other| {
    970                    state.unit_dependencies[&other.unit]
    971                        .iter()
    972                        .find(|other_dep| other_dep.unit.mode == CompileMode::RunCustomBuild)
    973                        .cloned()
    974                })
    975                .collect::<HashSet<_>>();
    976
    977            if !to_add.is_empty() {
    978                // (RunCustomBuild, set(other RunCustomBuild))
    979                new_deps.push((unit.clone(), to_add));
    980            }
    981        }
    982    }
    983
    984    // And finally, add in all the missing dependencies!
    985    for (unit, new_deps) in new_deps {
    986        state
    987            .unit_dependencies
    988            .get_mut(&unit)
    989            .unwrap()
    990            .extend(new_deps);
    991    }
    992}
    993
    994impl<'a, 'gctx> State<'a, 'gctx> {
    995    /// Gets `std_resolve` during building std, otherwise `usr_resolve`.
    996    fn resolve(&self) -> &'a Resolve {
    997        if self.is_std {
    998            self.std_resolve.unwrap()
    999        } else {
    1000            self.usr_resolve
    1001        }
    1002    }
    1003
    1004    /// Gets `std_features` during building std, otherwise `usr_features`.
    1005    fn features(&self) -> &'a ResolvedFeatures {
    1006        if self.is_std {
    1007            self.std_features.unwrap()
    1008        } else {
    1009            self.usr_features
    1010        }
    1011    }
    1012
    1013    fn activated_features(
    1014        &self,
    1015        pkg_id: PackageId,
    1016        features_for: FeaturesFor,
    1017    ) -> Vec<InternedString> {
    1018        let features = self.features();
    1019        features.activated_features(pkg_id, features_for)
    1020    }
    1021
    1022    fn is_dep_activated(
    1023        &self,
    1024        pkg_id: PackageId,
    1025        features_for: FeaturesFor,
    1026        dep_name: InternedString,
    1027    ) -> bool {
    1028        self.features()
    1029            .is_dep_activated(pkg_id, features_for, dep_name)
    1030    }
    1031
    1032    fn get(&self, id: PackageId) -> &'a Package {
    1033        self.package_set
    1034            .get_one(id)
    1035            .unwrap_or_else(|_| panic!("expected {} to be downloaded", id))
    1036    }
    1037
    1038    /// Returns a filtered set of dependencies for the given unit.
    1039    fn deps(&self, unit: &Unit, unit_for: UnitFor) -> Vec<(PackageId, Vec<&Dependency>)> {
    1040        let pkg_id = unit.pkg.package_id();
    1041        let kind = unit.kind;
    1042        self.resolve()
    1043            .deps(pkg_id)
    1044            .filter_map(|(id, deps)| {
    1045                assert!(!deps.is_empty());
    1046                let deps: Vec<_> = deps
    1047                    .iter()
    1048                    .filter(|dep| {
    1049                        // If this target is a build command, then we only want build
    1050                        // dependencies, otherwise we want everything *other than* build
    1051                        // dependencies.
    1052                        if unit.target.is_custom_build() != dep.is_build() {
    1053                            return false;
    1054                        }
    1055
    1056                        // If this dependency is **not** a transitive dependency, then it
    1057                        // only applies to test/example targets.
    1058                        if !dep.is_transitive()
    1059                            && !unit.target.is_test()
    1060                            && !unit.target.is_example()
    1061                            && !unit.mode.is_any_test()
    1062                        {
    1063                            return false;
    1064                        }
    1065
    1066                        // If this dependency is only available for certain platforms,
    1067                        // make sure we're only enabling it for that platform.
    1068                        if !self.target_data.dep_platform_activated(dep, kind) {
    1069                            return false;
    1070                        }
    1071
    1072                        // If this is an optional dependency, and the new feature resolver
    1073                        // did not enable it, don't include it.
    1074                        if dep.is_optional() {
    1075                            // This `unit_for` is from parent dep and *SHOULD* contains its own
    1076                            // artifact dep information inside `artifact_target_for_features`.
    1077                            // So, no need to map any artifact info from an incorrect `dep.artifact()`.
    1078                            let features_for = unit_for.map_to_features_for(IS_NO_ARTIFACT_DEP);
    1079                            if !self.is_dep_activated(pkg_id, features_for, dep.name_in_toml()) {
    1080                                return false;
    1081                            }
    1082                        }
    1083
    1084                        // If we've gotten past all that, then this dependency is
    1085                        // actually used!
    1086                        true
    1087                    })
    1088                    .collect();
    1089                if deps.is_empty() {
    1090                    None
    1091                } else {
    1092                    Some((id, deps))
    1093                }
    1094            })
    1095            .collect()
    1096    }
    1097}