1# Files 2 3This chapter gives some pointers on where to start looking at Cargo's on-disk 4data file structures. 5 6* [`Layout`] is the abstraction for the `target` directory. It handles locking 7 the target directory, and providing paths to the parts inside. There is a 8 separate `Layout` for each "target". 9* [`Resolve`] contains the contents of the `Cargo.lock` file. See the [`encode`] 10 module for the different `Cargo.lock` formats. 11* [`TomlManifest`] contains the contents of the `Cargo.toml` file. It is translated 12 to a [`Manifest`] object for some simplification, and the `Manifest` is stored 13 in a [`Package`]. 14* The [`fingerprint`] module deals with the fingerprint information stored in 15 `target/debug/.fingerprint`. This tracks whether or not a crate needs to be 16 rebuilt. 17* `cargo install` tracks its installed files with some metadata in 18 `$CARGO_HOME`. The metadata is managed in the 19 [`common_for_install_and_uninstall`] module. 20* Git sources are cached in `$CARGO_HOME/git`. The code for this cache is in 21 the [`git`] source module. 22* Registries are cached in `$CARGO_HOME/registry`. There are three parts, the 23 index, the compressed `.crate` files, and the extracted sources of those 24 crate files. 25 * Management of the registry cache can be found in the [`registry`] source 26 module. Note that this includes an on-disk cache as an optimization for 27 accessing the git repository. 28 * Saving of `.crate` files is handled by the [`RemoteRegistry`]. 29 * Extraction of `.crate` files is handled by the [`RegistrySource`]. 30 * There is a lock for the package cache. Code must be careful, because 31 this lock must be obtained manually. See 32 [`Config::acquire_package_cache_lock`]. 33 34[`Layout`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/layout.rs 35[`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs 36[`encode`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/encode.rs 37[`TomlManifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/toml/mod.rs 38[`Manifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs 39[`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs 40[`common_for_install_and_uninstall`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/common_for_install_and_uninstall.rs 41[`git`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/git 42[`registry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs 43[`RemoteRegistry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/remote.rs 44[`RegistrySource`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs 45[`Config::acquire_package_cache_lock`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1261-L1266 46 47## Filesystems 48 49Cargo tends to get run on a very wide array of file systems. Different file 50systems can have a wide range of capabilities, and Cargo should strive to do 51its best to handle them. Some examples of issues to deal with: 52 53* Not all file systems support locking. Cargo tries to detect if locking is 54 supported, and if not, will ignore lock errors. This isn't ideal, but it is 55 difficult to deal with. 56* The [`fs::canonicalize`] function doesn't work on all file systems 57 (particularly some Windows file systems). If that function is used, there 58 should be a fallback if it fails. This function will also return `\\?\` 59 style paths on Windows, which can have some issues (such as some tools not 60 supporting them, or having issues with relative paths). 61* Timestamps can be unreliable. The [`fingerprint`] module has a deeper 62 discussion of this. One example is that Docker cache layers will erase the 63 fractional part of the time stamp. 64* Symlinks are not always supported, particularly on Windows. 65 66[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs 67[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html 68