From 37a6c8d27bcd895360bc20b15356479616573a2a Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 09:38:50 -0500 Subject: [PATCH 01/14] doc (book)[01/14]: glossary beef-up Add a handful of entries to the glossary of The Cargo Book, and add intra-glossary hyperlinks for terms. A full catalog of the specific changes follows. Glossary entries added: + 'Cargo.lock' -- just points to the 'lock file' entry + 'Cargo.toml' -- just points to the 'manifest' entry + 'Module' -- explained in relation to 'crate' + 'Package manager' -- first term in the Introduction + 'Package registry' -- Another term from the Introduction. This entry just points to the 'registry' entry Glossary entries modified: + 'Artifact' - Extend def. to include generated docs. + 'Crate' - Refer to a "Rust crate" as a hint that it is a term that exists outside of Cargo. - Refer to a "Cargo package" (rather than just "package") to reflect the fact that the term is a concept introduced by Cargo (as opposed to being inherent to Rust). - Link to related terms: 'module', 'package', 'registry', and 'target'. + 'Edition' - Link to related term: 'manifest'. + 'Feature' - Link to related term: 'manifest'. + 'Index' - Markdown: add emphasis to first mention of term "index". - Link to related terms: 'crate', 'registry'. + 'Lock file' - Link to related terms: 'package', 'workspace'. + 'Manifest' - Link to related terms: 'package', 'workspace'. + 'Member' - Link to related terms: 'package', 'workspace'. + 'Package' - Note that every target is a crate, and that the type (library or binary) is determined by the Cargo.toml file. - Note relationship to workspaces. - For "package root", add "compare to" note referencing "workspace root". - Link to related terms: 'crate', 'manifest', 'target', 'workspace'. + 'Registry' - Link to related terms: 'crate', 'index', 'package'. + 'Source' - Link to related terms: 'crate', 'package'. + 'Target' - Link to related terms: 'artifact', 'manifest', 'package', 'workspace'. + 'Test Targets' - Link to related terms: 'crate', 'manifest'. + 'Workspace' - For "workspace root", add "compare to" note referencing "package root". - Link to related terms: 'lock file', 'manifest', 'member', 'package'. --- src/doc/src/appendix/glossary.md | 158 +++++++++++++++++++++++-------- 1 file changed, 117 insertions(+), 41 deletions(-) diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index d643f593c45..9ac0561e972 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -3,21 +3,41 @@ ### Artifact An *artifact* is the file or set of files created as a result of the -compilation process. This includes linkable libraries and executable binaries. +compilation process. This includes linkable libraries, executable binaries, +and generated documentation. + +### Cargo + +*Cargo* is the Rust [*package manager*](#package-manager), and the primary +topic of this book. + +### Cargo.lock + +See [*lock file*](#lock-file). + +### Cargo.toml + +See [*manifest*](#manifest). ### Crate -Every target in a package is a *crate*. Crates are either libraries or -executable binaries. It may loosely refer to either the source code of the -target, or the compiled artifact that the target produces. A crate may also -refer to a compressed package fetched from a registry. +A Rust *crate* is either a library or an executable program, referred to as +either a *library crate* or a *binary crate*, respectively. + +Every [target](#target) defined for a Cargo [package](#package) is a *crate*. + +Loosely, the term *crate* may refer to either the source code of the target or +to the compiled artifact that the target produces. It may also refer to a +compressed package fetched from a [registry](#registry). + +The source code for a given crate may be subdivided into [*modules*](#module). ### Edition A *Rust edition* is a developmental landmark of the Rust language. The [edition of a package][edition-field] is specified in the `Cargo.toml` -manifest, and individual targets can specify which edition they use. See the -[Edition Guide] for more information. +[manifest](#manifest), and individual targets can specify which edition they +use. See the [Edition Guide] for more information. ### Feature @@ -25,8 +45,8 @@ The meaning of *feature* depends on the context: - A [*feature*][feature] is a named flag which allows for conditional compilation. A feature can refer to an optional dependency, or an arbitrary - name defined in a `Cargo.toml` manifest that can be checked within source - code. + name defined in a `Cargo.toml` [manifest](#manifest) that can be checked + within source code. - Cargo has [*unstable feature flags*][cargo-unstable] which can be used to enable experimental behavior of Cargo itself. @@ -40,55 +60,107 @@ The meaning of *feature* depends on the context: ### Index -The index is the searchable list of crates in a registry. +The *index* is the searchable list of [*crates*](#crate) in a +[*registry*](#registry). ### Lock file The `Cargo.lock` *lock file* is a file that captures the exact version of -every dependency used in a workspace or package. It is automatically generated -by Cargo. See [Cargo.toml vs Cargo.lock]. +every dependency used in a [*workspace*](#workspace) or +[*package*](#package). It is automatically generated by Cargo. See +[Cargo.toml vs Cargo.lock]. ### Manifest -A [*manifest*][manifest] is a description of a package or a workspace in a -file named `Cargo.toml`. +A [*manifest*][manifest] is a description of a [package](#package) or a +[workspace](#workspace) in a file named `Cargo.toml`. A [*virtual manifest*][virtual] is a `Cargo.toml` file that only describes a workspace, and does not include a package. ### Member -A *member* is a package that belongs to a workspace. +A *member* is a [*package*](#package) that belongs to a +[*workspace*](#workspace). + +### Module + +Rust's module system is used to organize code into logical units called +*modules*, which provide isolated namespaces within the code. + +The source code for a given [crate](#crate) may be subdivided into one or more +separate modules. This is usually done to organize the code into areas of +related functionality or to control the visible scope (public/private) of +symbols within the source (structs, functions, and so on). + +A [`Cargo.toml`](#manifest) file is primarily concerned with the +[package](#package) it defines, its crates, and the packages of the crates on +which they depend. Nevertheless, you will see the term "module" often when +working with Rust, so you should understand its relationship to a given crate. ### Package -A *package* is a collection of source files and a `Cargo.toml` manifest which -describes the package. A package has a name and version which is used for -specifying dependencies between packages. A package contains multiple targets, -which are either libraries or executable binaries. +A *package* is a collection of source files and a `Cargo.toml` +[*manifest*](#manifest) file which describes the package. A package has a name +and version which is used for specifying dependencies between packages. + +A package contains multiple [*targets*](#target), each of which is a +[*crate*](#crate). The `Cargo.toml` file describes the type of the crates +(binary or library) within the package, along with some metadata about each +one -- how each is to be built, what their direct dependencies are, etc., as +described throughout this book. The *package root* is the directory where the package's `Cargo.toml` manifest -is located. +is located. (Compare with [*workspace root*](#workspace).) The [*package ID specification*][pkgid-spec], or *SPEC*, is a string used to uniquely reference a specific version of a package from a specific source. +Small to medium sized Rust projects will only need a single package, though it +is common for them to have multiple crates. + +Larger projects may involve multiple packages, in which case Cargo +[*workspaces*](#workspace) can be used to manage common dependencies and other +related metadata between the packages. + +### Package manager + +Broadly speaking, a *package manager* is a program (or collection of related +programs) in a software ecosystem that automates the process of obtaining, +installing, and upgrading artifacts. Within a programming language ecosystem, +a package manager is a developer-focused tool whose primary functionality is +to download library artifacts and their dependencies from some central +repository; this capability is often combined with the ability to perform +software builds (by invoking the language-specific compiler). + +[*Cargo*](#cargo) is the package manager within the Rust ecosystem. Cargo +downloads your Rust [package](#package)’s dependencies +([*artifacts*](#artifact) known as [*crates*](#crate)), compiles your +packages, makes distributable packages, and (optionally) uploads them to +[crates.io][], the Rust community’s [*package registry*](#registry). + +### Package registry + +See [*registry*](#registry). + ### Project Another name for a [package](#package). ### Registry -A *registry* is a service that contains a collection of downloadable crates -that can be installed or used as dependencies for a package. The default -registry is [crates.io](https://crates.io). The registry has an *index* which +A *registry* is a service that contains a collection of downloadable +[*crates*](#crate) that can be installed or used as dependencies for a +[*package*](#package). The default registry in the Rust ecosystem is +[crates.io](https://crates.io). The registry has an [*index*](#index) which contains a list of all crates, and tells Cargo how to download the crates that are needed. ### Source -A *source* is a provider that contains crates that may be included as -dependencies for a package. There are several kinds of sources: +A *source* is a provider that contains [*crates*](#crate) that may be included +as dependencies for a [*package*](#package). There are several kinds of +sources: - **Registry source** — See [registry](#registry). - **Local registry source** — A set of crates stored as compressed files on @@ -110,16 +182,17 @@ See [package ID specification](#package). The meaning of the term *target* depends on the context: -- **Cargo Target** — Cargo packages consist of *targets* which correspond to - artifacts that will be produced. Packages can have library, binary, example, - test, and benchmark targets. The [list of targets][targets] are configured - in the `Cargo.toml` manifest, often inferred automatically by the [directory +- **Cargo Target** — Cargo [*packages*](#package) consist of *targets* which + correspond to [*artifacts*](#artifact) that will be produced. Packages can + have library, binary, example, test, and benchmark targets. The + [list of targets][targets] are configured in the `Cargo.toml` + [*manifest*](#manifest), often inferred automatically by the [directory layout] of the source files. - **Target Directory** — Cargo places all built artifacts and intermediate files in the *target* directory. By default this is a directory named - `target` at the workspace root, or the package root if not using a - workspace. The directory may be changed with the `--target-dir` command-line - option, the `CARGO_TARGET_DIR` [environment variable], or the + `target` at the [*workspace*](#workspace) root, or the package root if not + using a workspace. The directory may be changed with the `--target-dir` + command-line option, the `CARGO_TARGET_DIR` [environment variable], or the `build.target-dir` [config option]. - **Target Architecture** — The OS and machine architecture for the built artifacts are typically referred to as a *target*. @@ -154,22 +227,24 @@ correctness of code. There are two types of test artifacts: individual units of code. * **Integration test target** — An [*integration test target*][integration-tests] is an executable binary compiled from a *test - target* which is a distinct crate whose source is located in the `tests` - directory or specified by the [`[[test]]` table][targets] in the - `Cargo.toml` manifest. It is intended to only test the public API of a - library, or execute a binary to verify its operation. + target* which is a distinct [*crate*](#crate) whose source is located in the + `tests` directory or specified by the [`[[test]]` table][targets] in the + `Cargo.toml` [*manifest*](#manifest). It is intended to only test the public + API of a library, or execute a binary to verify its operation. ### Workspace -A [*workspace*][workspace] is a collection of one or more packages that share -common dependency resolution (with a shared `Cargo.lock`), output directory, -and various settings such as profiles. +A [*workspace*][workspace] is a collection of one or more +[*packages*](#package) that share common dependency resolution (with a shared +`Cargo.lock` [*lock file*](#lock-file)), output directory, and various +settings such as profiles. A [*virtual workspace*][virtual] is a workspace where the root `Cargo.toml` -manifest does not define a package, and only lists the workspace members. +[*manifest*](#manifest) does not define a package, and only lists the +workspace [*members*](#member). The *workspace root* is the directory where the workspace's `Cargo.toml` -manifest is located. +manifest is located. (Compare with [*package root*](#package).) [Cargo.toml vs Cargo.lock]: ../guide/cargo-toml-vs-cargo-lock.md @@ -178,6 +253,7 @@ manifest is located. [Source Replacement]: ../reference/source-replacement.md [cargo-unstable]: ../reference/unstable.md [config option]: ../reference/config.md +[crates.io]: https://crates.io/ [directory layout]: ../guide/project-layout.md [edition guide]: ../../edition-guide/index.html [edition-field]: ../reference/manifest.md#the-edition-field From c9a658a1e07f011c7513347696c92862a044fb3b Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 09:58:19 -0500 Subject: [PATCH 02/14] doc (book)[02/14]: "Introduction": add links to glossary for key terms No language changes; just make these existing terms link to their corresponding entries in the glossary: - crate - package - package manager - package registry --- src/doc/src/index.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/doc/src/index.md b/src/doc/src/index.md index ed99358b1f5..41d40c519ab 100644 --- a/src/doc/src/index.md +++ b/src/doc/src/index.md @@ -2,9 +2,9 @@ ![Cargo Logo](images/Cargo-Logo-Small.png) -Cargo is the [Rust] *package manager*. Cargo downloads your Rust package’s +Cargo is the [Rust] [*package manager*][def-package-manager]. Cargo downloads your Rust [package][def-package]'s dependencies, compiles your packages, makes distributable packages, and uploads them to -[crates.io], the Rust community’s *package registry*. You can contribute +[crates.io], the Rust community’s [*package registry*][def-package-registry]. You can contribute to this book on [GitHub]. @@ -12,7 +12,8 @@ to this book on [GitHub]. **[Getting Started](getting-started/index.md)** -To get started with Cargo, install Cargo (and Rust) and set up your first crate. +To get started with Cargo, install Cargo (and Rust) and set up your first +[*crate*][def-crate]. **[Cargo Guide](guide/index.md)** @@ -39,6 +40,10 @@ The commands will let you interact with Cargo using its command-line interface. * [Rust documentation website](https://doc.rust-lang.org/) — Links to official Rust documentation and tools. +[def-crate]: ./appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ./appendix/glossary.md#package '"package" (glossary entry)' +[def-package-manager]: ./appendix/glossary.md#package-manager '"package manager" (glossary entry)' +[def-package-registry]: ./appendix/glossary.md#package-registry '"package registry" (glossary entry)' [rust]: https://www.rust-lang.org/ [crates.io]: https://crates.io/ [GitHub]: https://github.com/rust-lang/cargo/tree/master/src/doc From 4da7c38dec9f2732db1a8ab6653e69a56cbb3ebf Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 11:37:56 -0500 Subject: [PATCH 03/14] doc (book)[03/14]: "Getting Started" index: link "crate" to glossary entry --- src/doc/src/getting-started/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/src/getting-started/index.md b/src/doc/src/getting-started/index.md index ed775db70b6..710e9943bfe 100644 --- a/src/doc/src/getting-started/index.md +++ b/src/doc/src/getting-started/index.md @@ -1,6 +1,9 @@ ## Getting Started -To get started with Cargo, install Cargo (and Rust) and set up your first crate. +To get started with Cargo, install Cargo (and Rust) and set up your first +[*crate*][def-crate]. * [Installation](installation.md) * [First steps with Cargo](first-steps.md) + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' From 759b60cf7cec32af960ff54ebaac8f3d91a567ee Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 11:47:19 -0500 Subject: [PATCH 04/14] doc (book)[04/14]: "Getting Started"/"First Steps...": add intro blurb In the "First Steps with Cargo" section, add a short introductory paragraph informing the reader what to expect from the page. This provides a transition for the reader who may not yet know what a package is. Rather than jump right into "To start a new package with Cargo, ...", we now set the context for the purpose of the page, and also provide hyperlinks into our Glossary for the terms 'package', 'manifest', and 'crate'. --- src/doc/src/getting-started/first-steps.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/src/doc/src/getting-started/first-steps.md b/src/doc/src/getting-started/first-steps.md index 9c0a46b4071..4a4233eeb36 100644 --- a/src/doc/src/getting-started/first-steps.md +++ b/src/doc/src/getting-started/first-steps.md @@ -1,13 +1,18 @@ ## First Steps with Cargo +This section provides a quick sense for the `cargo` command line tool. We +demonstrate its ability to generate a new [***package***][def-package] for us, +its ability to compile the [***crate***][def-crate] within the package, and +its ability to run the resulting program. + To start a new package with Cargo, use `cargo new`: ```console $ cargo new hello_world ``` -Cargo defaults to `--bin` to make a binary program. To make a library, we'd -pass `--lib`. +Cargo defaults to `--bin` to make a binary program. To make a library, we +would pass `--lib`, instead. Let’s check out what Cargo has generated for us: @@ -34,8 +39,8 @@ edition = "2018" [dependencies] ``` -This is called a **manifest**, and it contains all of the metadata that Cargo -needs to compile your package. +This is called a [***manifest***][def-manifest], and it contains all of the +metadata that Cargo needs to compile your package. Here’s what’s in `src/main.rs`: @@ -45,7 +50,8 @@ fn main() { } ``` -Cargo generated a “hello world” for us. Let’s compile it: +Cargo generated a “hello world” program for us, otherwise known as a +[***binary crate***][def-crate]. Let’s compile it: ```console $ cargo build @@ -71,3 +77,7 @@ Hello, world! ### Going further For more details on using Cargo, check out the [Cargo Guide](../guide/index.md) + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' From c4c03c4d4dc87353b4c231586cbcf1c7718595a7 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 13:52:03 -0500 Subject: [PATCH 05/14] doc (book)[05/14]: "Cargo Guide"/"Why Cargo Exists": add "Preliminaries" The "Why Cargo Exists" section of the "Cargo Guide" is here split into two subsections: "Preliminaries" "Enter: Cargo" The content in "Preliminaries" is new, and provides a transition that motivates the need for a package manager rather than using 'rustc' directly. It provides footing for the reader that knows very little about Rust and nothing about Cargo. The "Enter: Cargo" subsection contains the previous content, augmented with a new paragraph explaining how the conventional list of build targets simplifies working with Cargo packages: "...once you know how to build one Cargo-based project, you know how to build /all/ of them." The following terms are linked to their Glossary entries: - artifact - crate - package - package manager - registry --- src/doc/src/guide/why-cargo-exists.md | 57 ++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/src/doc/src/guide/why-cargo-exists.md b/src/doc/src/guide/why-cargo-exists.md index 215bbceeb4b..852af8f85b5 100644 --- a/src/doc/src/guide/why-cargo-exists.md +++ b/src/doc/src/guide/why-cargo-exists.md @@ -1,7 +1,41 @@ ## Why Cargo Exists -Cargo is a tool that allows Rust packages to declare their various -dependencies and ensure that you’ll always get a repeatable build. +### Preliminaries + +In Rust, as you may know, a library or executable program is called a +[*crate*][def-crate]. Crates are compiled using the Rust compiler, +`rustc`. When starting with Rust, the first source code most people encounter +is that of the venerable “hello world” program, which they compile by invoking +`rustc` directly: + +```console +$ rustc hello.rs +$ ./hello +Hello, world! +``` + +Note that the above command required that we specify the file name +explicitly. If we were to directly use `rustc` to compile a different program, +a different command line invocation would be required. If we needed to specify +any specific compiler flags or include external dependencies, then the +needed command would be even more specific (and elaborate). + +Furthermore, most non-trivial programs will likely have dependencies on +external libraries, and will therefore also depend transitively on *their* +dependencies. Obtaining the correct versions of all the necessary dependencies +and keeping them up to date would be laborious and error-prone if done by +hand. + +Rather than work only with crates and `rustc`, we can avoid the manual tedium +involved with performing the above tasks by introducing a higher-level +["*package*"][def-package] abstraction and by using a +[*package manager*][def-package-manager]. + +### Enter: Cargo + +*Cargo* is the Rust package manager. It is a tool that allows Rust +[*packages*][def-package] to declare their various dependencies and ensure +that you’ll always get a repeatable build. To accomplish this goal, Cargo does four things: @@ -10,3 +44,22 @@ To accomplish this goal, Cargo does four things: * Invokes `rustc` or another build tool with the correct parameters to build your package. * Introduces conventions to make working with Rust packages easier. + +To a large extent, Cargo normalizes the commands needed to build a given +program or library; this is one aspect to the above mentioned conventions. As +we show later, the same command can be used to build different +[*artifacts*][def-artifact], regardless of their names. Rather than invoke +`rustc` directly, we can instead invoke something generic such as `cargo +build` and let cargo worry about constructing the correct `rustc` +invocation. Furthermore, Cargo will automatically fetch from a +[*registry*][def-registry] any dependencies we have defined for our artifact, +and arrange for them to be incorporated into our build as needed. + +It is only a slight exageration to say that once you know how to build one +Cargo-based project, you know how to build *all* of them. + +[def-artifact]: ../appendix/glossary.md#artifact '"artifact" (glossary entry)' +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-package-manager]: ../appendix/glossary.md#package-manager '"package manager" (glossary entry)' +[def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' From f86202257b8a305983bbd75374efcaf6a020a0dd Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:05:47 -0500 Subject: [PATCH 06/14] doc (book)[06/14]: "Cargo Guide"/"Creating a New...": link terms to glossary The following terms are linked to their Glossary entries: - crate - manifest - package Also note that the generated "hello world" program is known as a "binary crate". --- src/doc/src/guide/creating-a-new-project.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/doc/src/guide/creating-a-new-project.md b/src/doc/src/guide/creating-a-new-project.md index a66142c1567..909978749e8 100644 --- a/src/doc/src/guide/creating-a-new-project.md +++ b/src/doc/src/guide/creating-a-new-project.md @@ -1,6 +1,6 @@ ## Creating a New Package -To start a new package with Cargo, use `cargo new`: +To start a new [package][def-package] with Cargo, use `cargo new`: ```console $ cargo new hello_world --bin @@ -36,9 +36,9 @@ edition = "2018" ``` -This is called a **manifest**, and it contains all of the metadata that Cargo -needs to compile your package. This file is written in the [TOML] format -(pronounced /tɑməl/). +This is called a [***manifest***][def-manifest], and it contains all of the +metadata that Cargo needs to compile your package. This file is written in the +[TOML] format (pronounced /tɑməl/). Here’s what’s in `src/main.rs`: @@ -48,7 +48,8 @@ fn main() { } ``` -Cargo generated a “hello world” for us. Let’s compile it: +Cargo generated a “hello world” program for us, otherwise known as a +[*binary crate*][def-crate]. Let’s compile it: ```console $ cargo build @@ -92,3 +93,6 @@ shorter since the compiler doesn't do optimizations, but the code will run slower. Release mode takes longer to compile, but the code will run faster. [TOML]: https://toml.io/ +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' From d2c181f6244324b5ab714a6dd63c1b60f321d5b7 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:08:39 -0500 Subject: [PATCH 07/14] doc (book)[07/14]: "Cargo Guide"/"Working on an...": link terms to glossary The following term(s) are linked to their Glossary entries: - package --- src/doc/src/guide/working-on-an-existing-project.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/doc/src/guide/working-on-an-existing-project.md b/src/doc/src/guide/working-on-an-existing-project.md index ff5a31f2dd7..b0ddb18a88e 100644 --- a/src/doc/src/guide/working-on-an-existing-project.md +++ b/src/doc/src/guide/working-on-an-existing-project.md @@ -1,7 +1,7 @@ ## Working on an Existing Cargo Package -If you download an existing package that uses Cargo, it’s really easy -to get going. +If you download an existing [package][def-package] that uses Cargo, it’s +really easy to get going. First, get the package from somewhere. In this example, we’ll use `rand` cloned from its repository on GitHub: @@ -20,3 +20,5 @@ $ cargo build This will fetch all of the dependencies and then build them, along with the package. + +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' From d500dc8d30c451f8ce92c984547dc3cf9bd6ade9 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:14:46 -0500 Subject: [PATCH 08/14] doc (book)[08/14]: "Cargo Guide"/"Dependencies": link terms to glossary The following term(s) are linked to their Glossary entries: - crate - package - package registry --- src/doc/src/guide/dependencies.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/src/doc/src/guide/dependencies.md b/src/doc/src/guide/dependencies.md index 9ca6061e684..0964cbdb180 100644 --- a/src/doc/src/guide/dependencies.md +++ b/src/doc/src/guide/dependencies.md @@ -1,8 +1,9 @@ ## Dependencies -[crates.io] is the Rust community's central package registry that serves as a -location to discover and download packages. `cargo` is configured to use it by -default to find requested packages. +[crates.io] is the Rust community's central [*package registry*][def-package-registry] +that serves as a location to discover and download +[packages][def-package]. `cargo` is configured to use it by default to find +requested packages. To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. @@ -10,9 +11,9 @@ To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. ### Adding a dependency -If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that, -then list the crate name and version that you would like to use. This example -adds a dependency of the `time` crate: +If your `Cargo.toml` doesn't already have a `[dependencies]` section, add +that, then list the [crate][def-crate] name and version that you would like to +use. This example adds a dependency of the `time` crate: ```toml [dependencies] @@ -87,3 +88,7 @@ $ cargo run Running `target/hello_world` Did our date match? true ``` + +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-package-registry]: ../appendix/glossary.md#package-registry '"package-registry" (glossary entry)' From 1fbc9928dedffa7b6983667000708b551facd658 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:20:26 -0500 Subject: [PATCH 09/14] doc (book)[09/14]: "Cargo Guide"/"Package Layout": link terms to glossary The following term(s) are linked to their Glossary entries: - module - package --- src/doc/src/guide/project-layout.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md index 4869924c688..a3ce3f8a704 100644 --- a/src/doc/src/guide/project-layout.md +++ b/src/doc/src/guide/project-layout.md @@ -1,7 +1,7 @@ ## Package Layout Cargo uses conventions for file placement to make it easy to dive into a new -Cargo package: +Cargo [package][def-package]: ```text . @@ -44,9 +44,9 @@ Cargo package: * Integration tests go in the `tests` directory. If a binary, example, bench, or integration test consists of multiple source -files, place a `main.rs` file along with the extra modules within a -subdirectory of the `src/bin`, `examples`, `benches`, or `tests` directory. -The name of the executable will be the directory name. +files, place a `main.rs` file along with the extra [*modules*][def-module] +within a subdirectory of the `src/bin`, `examples`, `benches`, or `tests` +directory. The name of the executable will be the directory name. You can learn more about Rust's module system in [the book][book-modules]. @@ -56,4 +56,6 @@ automatically infers target names. [book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html [Configuring a target]: ../reference/cargo-targets.md#configuring-a-target +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-module]: ../appendix/glossary.md#module '"module" (glossary entry)' [Target auto-discovery]: ../reference/cargo-targets.md#target-auto-discovery From 05ee4c69de4041ab92837d31773a0a3955f87a32 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:40:34 -0500 Subject: [PATCH 10/14] doc (book)[10/14]: "Cargo Guide"/"Cargo.toml vs...": link terms to glossary The following term(s) are linked to their Glossary entries: - manifest - package --- src/doc/src/guide/cargo-toml-vs-cargo-lock.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md index 12711247830..39fb336d66a 100644 --- a/src/doc/src/guide/cargo-toml-vs-cargo-lock.md +++ b/src/doc/src/guide/cargo-toml-vs-cargo-lock.md @@ -8,18 +8,20 @@ about them, here’s a summary: * `Cargo.lock` contains exact information about your dependencies. It is maintained by Cargo and should not be manually edited. -If you’re building a non-end product, such as a rust library that other rust packages will depend on, put -`Cargo.lock` in your `.gitignore`. If you’re building an end product, which are executable -like command-line tool or an application, or a system library with crate-type of `staticlib` or `cdylib`, -check `Cargo.lock` into `git`. If you're curious about why that is, see +If you’re building a non-end product, such as a rust library that other rust +[packages][def-package] will depend on, put `Cargo.lock` in your +`.gitignore`. If you’re building an end product, which are executable like +command-line tool or an application, or a system library with crate-type of +`staticlib` or `cdylib`, check `Cargo.lock` into `git`. If you're curious +about why that is, see ["Why do binaries have `Cargo.lock` in version control, but not libraries?" in the FAQ](../faq.md#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). Let’s dig in a little bit more. -`Cargo.toml` is a **manifest** file in which we can specify a bunch of -different metadata about our package. For example, we can say that we depend -on another package: +`Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a +bunch of different metadata about our package. For example, we can say that we +depend on another package: ```toml [package] @@ -101,3 +103,6 @@ This will write out a new `Cargo.lock` with the new version information. Note that the argument to `cargo update` is actually a [Package ID Specification](../reference/pkgid-spec.md) and `rand` is just a short specification. + +[def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' From c0b09f188ba3f2477349c0ebac52f17c1e432f25 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:43:06 -0500 Subject: [PATCH 11/14] doc (book)[11/14]: "Cargo Guide"/"Tests": link terms to glossary The following term(s) are linked to their Glossary entries: - package --- src/doc/src/guide/tests.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md index 90247174f42..479efb920af 100644 --- a/src/doc/src/guide/tests.md +++ b/src/doc/src/guide/tests.md @@ -6,8 +6,8 @@ Tests in your `src` files should be unit tests, and tests in `tests/` should be integration-style tests. As such, you’ll need to import your crates into the files in `tests`. -Here's an example of running `cargo test` in our package, which currently has -no tests: +Here's an example of running `cargo test` in our [package][def-package], which +currently has no tests: ```console $ cargo test @@ -36,4 +36,5 @@ examples you’ve included and will also test the examples in your documentation. Please see the [testing guide][testing] in the Rust documentation for more details. +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' [testing]: ../../book/ch11-00-testing.html From aeb517bdea64d7c48a3fa5031754f670962382e9 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:45:11 -0500 Subject: [PATCH 12/14] doc (book)[12/14]: "Cargo Guide"/"Continuous Integration": link terms to glossary The following term(s) are linked to their Glossary entries: - package --- src/doc/src/guide/continuous-integration.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/src/guide/continuous-integration.md b/src/doc/src/guide/continuous-integration.md index 25d2e385154..924c58a7701 100644 --- a/src/doc/src/guide/continuous-integration.md +++ b/src/doc/src/guide/continuous-integration.md @@ -2,7 +2,8 @@ ### Travis CI -To test your package on Travis CI, here is a sample `.travis.yml` file: +To test your [package][def-package] on Travis CI, here is a sample +`.travis.yml` file: ```yaml language: rust @@ -86,3 +87,5 @@ This will test and build documentation on the stable channel and nightly channel, but any breakage in nightly will not fail your overall build. Please see the [builds.sr.ht documentation](https://man.sr.ht/builds.sr.ht/) for more information. + +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' From 365b738ebaa456c31284187c12ed09f7fbc55554 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:53:34 -0500 Subject: [PATCH 13/14] doc (book)[13/14]: "Cargo Guide"/"Cargo Home": link terms to glossary The following term(s) are linked to their Glossary entries: - crate - package - registry --- src/doc/src/guide/cargo-home.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/doc/src/guide/cargo-home.md b/src/doc/src/guide/cargo-home.md index ea13ef9b3db..00b1b7909d8 100644 --- a/src/doc/src/guide/cargo-home.md +++ b/src/doc/src/guide/cargo-home.md @@ -1,7 +1,7 @@ ## 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. +When building a [crate][def-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/`. @@ -16,10 +16,10 @@ The Cargo home consists of following components: Cargo's global configuration file, see the [config entry in the reference][config]. * `credentials.toml` - Private login credentials from [`cargo login`] in order to log in to a registry. + Private login credentials from [`cargo login`] in order to log in to a [registry][def-registry]. * `.crates.toml` - This hidden file contains package information of crates installed via [`cargo install`]. Do NOT edit by hand! + This hidden file contains [package][def-package] information of crates installed via [`cargo install`]. Do NOT edit by hand! ## Directories: @@ -83,4 +83,7 @@ Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate pro [`cargo login`]: ../commands/cargo-login.md [`cargo vendor`]: ../commands/cargo-vendor.md [config]: ../reference/config.md +[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' +[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' +[def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' [env]: ../reference/environment-variables.md From ab7822166f808d818eff6383177b890dd52e8328 Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Sat, 21 Nov 2020 14:59:40 -0500 Subject: [PATCH 14/14] doc (book)[14/14]: "Cargo Guide"/"Build Cache": link terms to glossary The following term(s) are linked to their Glossary entries: - workspace --- src/doc/src/guide/build-cache.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index 013dd5136c5..e86d0ebb6c6 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -1,9 +1,10 @@ ## Build cache Cargo stores the output of a build into the "target" directory. By default, -this is the directory named `target` in the root of your workspace. To change -the location, you can set the `CARGO_TARGET_DIR` [environment variable], the -[`build.target-dir`] config value, or the `--target-dir` command-line flag. +this is the directory named `target` in the root of your +[*workspace*][def-worksapce]. To change the location, you can set the +`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config +value, or the `--target-dir` command-line flag. The directory layout depends on whether or not you are using the `--target` flag to build for a specific platform. If `--target` is not specified, Cargo @@ -90,6 +91,7 @@ configuration][config]. Refer to sccache documentation for more details. [`cargo publish`]: ../commands/cargo-publish.md [build scripts]: ../reference/build-scripts.md [config]: ../reference/config.md +[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' [environment variable]: ../reference/environment-variables.md [incremental output]: ../reference/profiles.md#incremental [sccache]: https://github.com/mozilla/sccache