#
cargo/core/compiler/
layout.rs

    1//! Management of the directory layout of a build
    2//!
    3//! The directory layout is a little tricky at times, hence a separate file to
    4//! house this logic. The current layout looks like this:
    5//!
    6//! ```text
    7//! # This is the root directory for all output, the top-level package
    8//! # places all of its output here.
    9//! target/
    10//!
    11//!     # Cache of `rustc -Vv` output for performance.
    12//!     .rustc-info.json
    13//!
    14//!     # All final artifacts are linked into this directory from `deps`.
    15//!     # Note that named profiles will soon be included as separate directories
    16//!     # here. They have a restricted format, similar to Rust identifiers, so
    17//!     # Cargo-specific directories added in the future should use some prefix
    18//!     # like `.` to avoid name collisions.
    19//!     debug/  # or release/
    20//!
    21//!         # File used to lock the directory to prevent multiple cargo processes
    22//!         # from using it at the same time.
    23//!         .cargo-lock
    24//!
    25//!         # Hidden directory that holds all of the fingerprint files for all
    26//!         # packages
    27//!         .fingerprint/
    28//!             # Each package is in a separate directory.
    29//!             # Note that different target kinds have different filename prefixes.
    30//!             $pkgname-$META/
    31//!                 # Set of source filenames for this package.
    32//!                 dep-lib-$targetname
    33//!                 # Timestamp when this package was last built.
    34//!                 invoked.timestamp
    35//!                 # The fingerprint hash.
    36//!                 lib-$targetname
    37//!                 # Detailed information used for logging the reason why
    38//!                 # something is being recompiled.
    39//!                 lib-$targetname.json
    40//!                 # The console output from the compiler. This is cached
    41//!                 # so that warnings can be redisplayed for "fresh" units.
    42//!                 output-lib-$targetname
    43//!
    44//!         # This is the root directory for all rustc artifacts except build
    45//!         # scripts, examples, and test and bench executables. Almost every
    46//!         # artifact should have a metadata hash added to its filename to
    47//!         # prevent collisions. One notable exception is dynamic libraries.
    48//!         deps/
    49//!
    50//!             # Each artifact dependency gets in its own directory.
    51//!             /artifact/$pkgname-$META/$kind
    52//!
    53//!         # Root directory for all compiled examples.
    54//!         examples/
    55//!
    56//!         # Directory used to store incremental data for the compiler (when
    57//!         # incremental is enabled.
    58//!         incremental/
    59//!
    60//!         # This is the location at which the output of all custom build
    61//!         # commands are rooted.
    62//!         build/
    63//!
    64//!             # Each package gets its own directory where its build script and
    65//!             # script output are placed
    66//!             $pkgname-$META/    # For the build script itself.
    67//!                 # The build script executable (name may be changed by user).
    68//!                 build-script-build-$META
    69//!                 # Hard link to build-script-build-$META.
    70//!                 build-script-build
    71//!                 # Dependency information generated by rustc.
    72//!                 build-script-build-$META.d
    73//!                 # Debug information, depending on platform and profile
    74//!                 # settings.
    75//!                 <debug symbols>
    76//!
    77//!             # The package shows up twice with two different metadata hashes.
    78//!             $pkgname-$META/  # For the output of the build script.
    79//!                 # Timestamp when the build script was last executed.
    80//!                 invoked.timestamp
    81//!                 # Directory where script can output files ($OUT_DIR).
    82//!                 out/
    83//!                 # Output from the build script.
    84//!                 output
    85//!                 # Path to `out`, used to help when the target directory is
    86//!                 # moved.
    87//!                 root-output
    88//!                 # Stderr output from the build script.
    89//!                 stderr
    90//!
    91//!     # Output from rustdoc
    92//!     doc/
    93//!
    94//!     # Used by `cargo package` and `cargo publish` to build a `.crate` file.
    95//!     package/
    96//!
    97//!     # Experimental feature for generated build scripts.
    98//!     .metabuild/
    99//! ```
    100//!
    101//! When cross-compiling, the layout is the same, except it appears in
    102//! `target/$TRIPLE`.
    103
    104use crate::core::Workspace;
    105use crate::core::compiler::CompileTarget;
    106use crate::util::flock::is_on_nfs_mount;
    107use crate::util::{CargoResult, FileLock};
    108use cargo_util::paths;
    109use std::path::{Path, PathBuf};
    110
    111/// Contains the paths of all target output locations.
    112///
    113/// See module docs for more information.
    114pub struct Layout {
    115    artifact_dir: Option<ArtifactDirLayout>,
    116    build_dir: BuildDirLayout,
    117}
    118
    119impl Layout {
    120    /// Calculate the paths for build output, lock the build directory, and return as a Layout.
    121    ///
    122    /// This function will block if the directory is already locked.
    123    ///
    124    /// `dest` should be the final artifact directory name. Currently either
    125    /// "debug" or "release".
    126    pub fn new(
    127        ws: &Workspace<'_>,
    128        target: Option<CompileTarget>,
    129        dest: &str,
    130        must_take_artifact_dir_lock: bool,
    131    ) -> CargoResult<Layout> {
    132        let is_new_layout = ws.gctx().cli_unstable().build_dir_new_layout;
    133        let mut root = ws.target_dir();
    134        let mut build_root = ws.build_dir();
    135        if let Some(target) = target {
    136            root.push(target.short_name());
    137            build_root.push(target.short_name());
    138        }
    139        let build_dest = build_root.join(dest);
    140        let dest = root.join(dest);
    141        // If the root directory doesn't already exist go ahead and create it
    142        // here. Use this opportunity to exclude it from backups as well if the
    143        // system supports it since this is a freshly created folder.
    144        //
    145        paths::create_dir_all_excluded_from_backups_atomic(root.as_path_unlocked())?;
    146        if root != build_root {
    147            paths::create_dir_all_excluded_from_backups_atomic(build_root.as_path_unlocked())?;
    148        }
    149
    150        // Now that the excluded from backups target root is created we can create the
    151        // actual destination (sub)subdirectory.
    152        paths::create_dir_all(dest.as_path_unlocked())?;
    153
    154        // We always need to take the build-dir lock but if the build-dir == artifact-dir then we
    155        // only take the artifact-dir. (locking both as they are the same dir)
    156        // However we need to take into account that for some builds like `cargo check` we avoid
    157        // locking the artifact-dir. We still need to lock the build-dir to avoid file corruption.
    158        let build_dir_lock = if (must_take_artifact_dir_lock && root == build_root)
    159            || is_on_nfs_mount(build_root.as_path_unlocked())
    160        {
    161            None
    162        } else {
    163            Some(build_dest.open_rw_exclusive_create(
    164                ".cargo-lock",
    165                ws.gctx(),
    166                "build directory",
    167            )?)
    168        };
    169        let build_root = build_root.into_path_unlocked();
    170        let build_dest = build_dest.as_path_unlocked();
    171        let deps = build_dest.join("deps");
    172        let artifact = deps.join("artifact");
    173
    174        let artifact_dir = if must_take_artifact_dir_lock {
    175            // For now we don't do any more finer-grained locking on the artifact
    176            // directory, so just lock the entire thing for the duration of this
    177            // compile.
    178            let artifact_dir_lock = if is_on_nfs_mount(root.as_path_unlocked()) {
    179                None
    180            } else {
    181                Some(dest.open_rw_exclusive_create(
    182                    ".cargo-lock",
    183                    ws.gctx(),
    184                    "artifact directory",
    185                )?)
    186            };
    187            let root = root.into_path_unlocked();
    188            let dest = dest.into_path_unlocked();
    189            Some(ArtifactDirLayout {
    190                dest: dest.clone(),
    191                examples: dest.join("examples"),
    192                doc: root.join("doc"),
    193                timings: root.join("cargo-timings"),
    194                _lock: artifact_dir_lock,
    195            })
    196        } else {
    197            None
    198        };
    199        Ok(Layout {
    200            artifact_dir,
    201            build_dir: BuildDirLayout {
    202                root: build_root.clone(),
    203                deps,
    204                build: build_dest.join("build"),
    205                artifact,
    206                incremental: build_dest.join("incremental"),
    207                fingerprint: build_dest.join(".fingerprint"),
    208                examples: build_dest.join("examples"),
    209                tmp: build_root.join("tmp"),
    210                _lock: build_dir_lock,
    211                is_new_layout,
    212            },
    213        })
    214    }
    215
    216    /// Makes sure all directories stored in the Layout exist on the filesystem.
    217    pub fn prepare(&mut self) -> CargoResult<()> {
    218        if let Some(ref mut artifact_dir) = self.artifact_dir {
    219            artifact_dir.prepare()?;
    220        }
    221        self.build_dir.prepare()?;
    222
    223        Ok(())
    224    }
    225
    226    pub fn artifact_dir(&self) -> Option<&ArtifactDirLayout> {
    227        self.artifact_dir.as_ref()
    228    }
    229
    230    pub fn build_dir(&self) -> &BuildDirLayout {
    231        &self.build_dir
    232    }
    233}
    234
    235pub struct ArtifactDirLayout {
    236    /// The final artifact destination: `<artifact-dir>/debug` (or `release`).
    237    dest: PathBuf,
    238    /// The directory for examples
    239    examples: PathBuf,
    240    /// The directory for rustdoc output
    241    doc: PathBuf,
    242    /// The directory for --timings output
    243    timings: PathBuf,
    244    /// The lockfile for a build (`.cargo-lock`). Will be unlocked when this
    245    /// struct is `drop`ped.
    246    _lock: Option<FileLock>,
    247}
    248
    249impl ArtifactDirLayout {
    250    /// Makes sure all directories stored in the Layout exist on the filesystem.
    251    pub fn prepare(&mut self) -> CargoResult<()> {
    252        paths::create_dir_all(&self.examples)?;
    253
    254        Ok(())
    255    }
    256    /// Fetch the destination path for final artifacts  (`/…/target/debug`).
    257    pub fn dest(&self) -> &Path {
    258        &self.dest
    259    }
    260    /// Fetch the examples path.
    261    pub fn examples(&self) -> &Path {
    262        &self.examples
    263    }
    264    /// Fetch the doc path.
    265    pub fn doc(&self) -> &Path {
    266        &self.doc
    267    }
    268    /// Fetch the cargo-timings path.
    269    pub fn timings(&self) -> &Path {
    270        &self.timings
    271    }
    272}
    273
    274pub struct BuildDirLayout {
    275    /// The root directory: `/path/to/build-dir`.
    276    /// If cross compiling: `/path/to/build-dir/$TRIPLE`.
    277    root: PathBuf,
    278    /// The directory with rustc artifacts
    279    deps: PathBuf,
    280    /// The primary directory for build files
    281    build: PathBuf,
    282    /// The directory for artifacts, i.e. binaries, cdylibs, staticlibs
    283    artifact: PathBuf,
    284    /// The directory for incremental files
    285    incremental: PathBuf,
    286    /// The directory for fingerprints
    287    fingerprint: PathBuf,
    288    /// The directory for pre-uplifted examples: `build-dir/debug/examples`
    289    examples: PathBuf,
    290    /// The directory for temporary data of integration tests and benches
    291    tmp: PathBuf,
    292    /// The lockfile for a build (`.cargo-lock`). Will be unlocked when this
    293    /// struct is `drop`ped.
    294    ///
    295    /// Will be `None` when the build-dir and target-dir are the same path as we cannot
    296    /// lock the same path twice.
    297    _lock: Option<FileLock>,
    298    is_new_layout: bool,
    299}
    300
    301impl BuildDirLayout {
    302    /// Makes sure all directories stored in the Layout exist on the filesystem.
    303    pub fn prepare(&mut self) -> CargoResult<()> {
    304        if !self.is_new_layout {
    305            paths::create_dir_all(&self.deps)?;
    306            paths::create_dir_all(&self.fingerprint)?;
    307        }
    308        paths::create_dir_all(&self.incremental)?;
    309        paths::create_dir_all(&self.examples)?;
    310        paths::create_dir_all(&self.build)?;
    311
    312        Ok(())
    313    }
    314    /// Fetch the deps path.
    315    pub fn deps(&self, pkg_dir: &str) -> PathBuf {
    316        if self.is_new_layout {
    317            self.deps_new_layout(pkg_dir)
    318        } else {
    319            self.legacy_deps().to_path_buf()
    320        }
    321    }
    322    /// Fetch the deps path. (new layout)
    323    ///
    324    /// New features should consider using this so we can avoid their migrations.
    325    pub fn deps_new_layout(&self, pkg_dir: &str) -> PathBuf {
    326        self.build_unit(pkg_dir).join("deps")
    327    }
    328    /// Fetch the deps path. (old layout)
    329    pub fn legacy_deps(&self) -> &Path {
    330        &self.deps
    331    }
    332    pub fn root(&self) -> &Path {
    333        &self.root
    334    }
    335    /// Fetch the build examples path.
    336    pub fn examples(&self) -> &Path {
    337        &self.examples
    338    }
    339    /// Fetch the incremental path.
    340    pub fn incremental(&self) -> &Path {
    341        &self.incremental
    342    }
    343    /// Fetch the fingerprint path.
    344    pub fn fingerprint(&self, pkg_dir: &str) -> PathBuf {
    345        if self.is_new_layout {
    346            self.build_unit(pkg_dir).join("fingerprint")
    347        } else {
    348            self.legacy_fingerprint().to_path_buf().join(pkg_dir)
    349        }
    350    }
    351    /// Fetch the fingerprint path. (old layout)
    352    pub fn legacy_fingerprint(&self) -> &Path {
    353        &self.fingerprint
    354    }
    355    /// Fetch the build path.
    356    pub fn build(&self) -> &Path {
    357        &self.build
    358    }
    359    /// Fetch the build script path.
    360    pub fn build_script(&self, pkg_dir: &str) -> PathBuf {
    361        if self.is_new_layout {
    362            self.build_unit(pkg_dir).join("build-script")
    363        } else {
    364            self.build().join(pkg_dir)
    365        }
    366    }
    367    /// Fetch the build script execution path.
    368    pub fn build_script_execution(&self, pkg_dir: &str) -> PathBuf {
    369        if self.is_new_layout {
    370            self.build_unit(pkg_dir).join("build-script-execution")
    371        } else {
    372            self.build().join(pkg_dir)
    373        }
    374    }
    375    /// Fetch the artifact path.
    376    pub fn artifact(&self) -> &Path {
    377        &self.artifact
    378    }
    379    /// Fetch the build unit path
    380    pub fn build_unit(&self, pkg_dir: &str) -> PathBuf {
    381        self.build().join(pkg_dir)
    382    }
    383    /// Create and return the tmp path.
    384    pub fn prepare_tmp(&self) -> CargoResult<&Path> {
    385        paths::create_dir_all(&self.tmp)?;
    386        Ok(&self.tmp)
    387    }
    388}