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