doc (book): add "Getting Started" subsection: "Essential Terminology"

src/doc/src/appendix/glossary.md

@@ -3,30 +3,50 @@
 ### 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
 
 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

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)'

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)'

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

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

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)'