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