From ecc175e84ecc0edfb593cbe31a14a5773e519f67 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 10 Sep 2019 09:12:21 -0700 Subject: [PATCH 1/2] Remove trailing spaces. --- src/doc/src/guide/cargo-home.md | 36 ++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md index fae4c3d57f2..3678d401208 100644 --- a/src/doc/src/guide/cargo-home.md +++ b/src/doc/src/guide/cargo-home.md @@ -1,8 +1,8 @@ ## Cargo Home The cargo home functions as a download and source cache. -When building a crate, cargo stores downloaded build dependencies in the cargo home. -You can alter the location of the cargo home by setting the `CARGO_HOME` [environmental variable](../reference/environment-variables.html). +When building a crate, cargo stores downloaded build dependencies in the cargo home. +You can alter the location of the cargo home by setting the `CARGO_HOME` [environmental variable](../reference/environment-variables.html). The [home](https://crates.io/crates/home) crate provides an api for getting this location if you need this information inside your rust crate. By default, the cargo home is located in `${HOME}/.cargo/`. @@ -12,10 +12,10 @@ The cargo home consists of following components: ## Files: -* `config` +* `config` Cargos global configuration file, see the [config entry in the reference](../reference/config.html). -* `credentials` +* `credentials` Private login credentials from [`cargo login`](../commands/cargo-login.html) in order to login into a registry. * `.crates.toml` @@ -23,37 +23,37 @@ The cargo home consists of following components: ## Directories: -* `bin` +* `bin` The bin directory contains executables of crates that were installed via "cargo install" or `rustup`. To be able to make these binaries accessible, add the path of the directory to your `${PATH}`. - * `git` + * `git` Git sources are stored here: - - * `git/db` + + * `git/db` When a crate depends on a git repository, cargo clones the repo as a bare repo into this directory and updates it if neccessary. - - * `git/checkouts` + + * `git/checkouts` If a git source is used, the required commit of the repo is checked out from the bare repo inside `git/db` into this directory. This provides the compiler with the actual files contained in the repo of the commit specified for that dependency. Multiple checkouts of different commits of the same repo are possible. -* `registry` +* `registry` Packages and metadata of crate registries (such as crates.io) are located here. - - * `registry/index` + + * `registry/index` The index is a bare git repository which contains the metadata (versions, dependencies etc) of all available crates of a registry. - * `registry/cache` + * `registry/cache` Downloaded dependencies are stored in the cache. The crates are compressed gzip archives named with a `.crate` extension. - - * `registry/src` + + * `registry/src` If a downloaded `.crate` archive is required by a package, it is unpacked into `registry/src` folder where rustc will find the `.rs` files. ## Caching the cargo home in CI -To avoid redownloading all crate dependencies during continuous integration, you can cache the `$CARGO_HOME` directory. +To avoid redownloading all crate dependencies during continuous integration, you can cache the `$CARGO_HOME` directory. However, caching the entire directory as is is often inefficient as it will contain downloaded sources twice. If we depend on `cargo 0.38.0` and cache the entire `$CARGO_HOME` we would actually cache the sources twice, the `cargo-0.38.0.crate` inside `registry/cache` and the extracted `.rs` files of cargoinside `registry/src`. The can unneccessarily slow down the build as downloading, extracting, recompressing and reuploading the cache ot the CI servers can take some time. @@ -77,4 +77,4 @@ See the [cargo vendor](commands/cargo-vendor.md) subcommand. In theory, you can always remove any part of the cache and cargo will do its best to restore sources if a crate needs them either by reextracting an archive or checking out a bare repo or by simply redownloading the sources from the web. -Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your commandline. +Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your commandline. From 57b3d04e7418d77fc5f7fc16097e5e3863b96ec0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 10 Sep 2019 09:37:43 -0700 Subject: [PATCH 2/2] Fix broken links, misspellings, style fixes, clarifications. --- src/doc/src/guide/cargo-home.md | 48 ++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md index 3678d401208..7a5e1c1d75a 100644 --- a/src/doc/src/guide/cargo-home.md +++ b/src/doc/src/guide/cargo-home.md @@ -1,37 +1,37 @@ ## Cargo Home -The cargo home functions as a download and source cache. -When building a crate, cargo stores downloaded build dependencies in the cargo home. -You can alter the location of the cargo home by setting the `CARGO_HOME` [environmental variable](../reference/environment-variables.html). -The [home](https://crates.io/crates/home) crate provides an api for getting this location if you need this information inside your rust crate. -By default, the cargo home is located in `${HOME}/.cargo/`. +The "Cargo home" functions as a download and source cache. +When building a crate, Cargo stores downloaded build dependencies in the Cargo home. +You can alter the location of the Cargo home by setting the `CARGO_HOME` [environmental variable][env]. +The [home](https://crates.io/crates/home) crate provides an API for getting this location if you need this information inside your Rust crate. +By default, the Cargo home is located in `$HOME/.cargo/`. -Please note that the internal structure of the cargo home is not stabilized and may be subject to change at any time. +Please note that the internal structure of the Cargo home is not stabilized and may be subject to change at any time. -The cargo home consists of following components: +The Cargo home consists of following components: ## Files: * `config` - Cargos global configuration file, see the [config entry in the reference](../reference/config.html). + Cargo's global configuration file, see the [config entry in the reference][config]. * `credentials` - Private login credentials from [`cargo login`](../commands/cargo-login.html) in order to login into a registry. + Private login credentials from [`cargo login`] in order to log in to a registry. * `.crates.toml` - This hidden file contains package information of crates installed via [cargo install](../commands/cargo-install.html). Do NOT edit by hand! + This hidden file contains package information of crates installed via [`cargo install`]. Do NOT edit by hand! ## Directories: * `bin` -The bin directory contains executables of crates that were installed via "cargo install" or `rustup`. -To be able to make these binaries accessible, add the path of the directory to your `${PATH}`. +The bin directory contains executables of crates that were installed via [`cargo install`] or [`rustup`](https://github.com/rust-lang/rustup.rs). +To be able to make these binaries accessible, add the path of the directory to your `$PATH` environment variable. * `git` Git sources are stored here: * `git/db` - When a crate depends on a git repository, cargo clones the repo as a bare repo into this directory and updates it if neccessary. + When a crate depends on a git repository, Cargo clones the repo as a bare repo into this directory and updates it if necessary. * `git/checkouts` If a git source is used, the required commit of the repo is checked out from the bare repo inside `git/db` into this directory. @@ -39,7 +39,7 @@ To be able to make these binaries accessible, add the path of the directory to y Multiple checkouts of different commits of the same repo are possible. * `registry` - Packages and metadata of crate registries (such as crates.io) are located here. + Packages and metadata of crate registries (such as [crates.io](https://crates.io/)) are located here. * `registry/index` The index is a bare git repository which contains the metadata (versions, dependencies etc) of all available crates of a registry. @@ -51,12 +51,12 @@ To be able to make these binaries accessible, add the path of the directory to y If a downloaded `.crate` archive is required by a package, it is unpacked into `registry/src` folder where rustc will find the `.rs` files. -## Caching the cargo home in CI +## Caching the Cargo home in CI To avoid redownloading all crate dependencies during continuous integration, you can cache the `$CARGO_HOME` directory. -However, caching the entire directory as is is often inefficient as it will contain downloaded sources twice. -If we depend on `cargo 0.38.0` and cache the entire `$CARGO_HOME` we would actually cache the sources twice, the `cargo-0.38.0.crate` inside `registry/cache` and the extracted `.rs` files of cargoinside `registry/src`. -The can unneccessarily slow down the build as downloading, extracting, recompressing and reuploading the cache ot the CI servers can take some time. +However, caching the entire directory is often inefficient as it will contain downloaded sources twice. +If we depend on a crate such as `serde 1.0.92` and cache the entire `$CARGO_HOME` we would actually cache the sources twice, the `serde-1.0.92.crate` inside `registry/cache` and the extracted `.rs` files of serde inside `registry/src`. +The can unnecessarily slow down the build as downloading, extracting, recompressing and reuploading the cache to the CI servers can take some time. It should be sufficient to only cache the following directories across builds: @@ -69,12 +69,18 @@ It should be sufficient to only cache the following directories across builds: ## Vendoring all dependencies of a project -See the [cargo vendor](commands/cargo-vendor.md) subcommand. +See the [`cargo vendor`] subcommand. ## Clearing the cache -In theory, you can always remove any part of the cache and cargo will do its best to restore sources if a crate needs them either by reextracting an archive or checking out a bare repo or by simply redownloading the sources from the web. +In theory, you can always remove any part of the cache and Cargo will do its best to restore sources if a crate needs them either by reextracting an archive or checking out a bare repo or by simply redownloading the sources from the web. -Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your commandline. +Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your command-line. + +[`cargo install`]: ../commands/cargo-install.md +[`cargo login`]: ../commands/cargo-login.md +[`cargo vendor`]: ../commands/cargo-vendor.md +[config]: ../reference/config.md +[env]: ../reference/environment-variables.md