Skip to content

Commit c4c03c4

Browse files
committed
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
1 parent 759b60c commit c4c03c4

File tree

1 file changed

+55
-2
lines changed

1 file changed

+55
-2
lines changed

src/doc/src/guide/why-cargo-exists.md

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,41 @@
11
## Why Cargo Exists
22

3-
Cargo is a tool that allows Rust packages to declare their various
4-
dependencies and ensure that you’ll always get a repeatable build.
3+
### Preliminaries
4+
5+
In Rust, as you may know, a library or executable program is called a
6+
[*crate*][def-crate]. Crates are compiled using the Rust compiler,
7+
`rustc`. When starting with Rust, the first source code most people encounter
8+
is that of the venerable “hello world” program, which they compile by invoking
9+
`rustc` directly:
10+
11+
```console
12+
$ rustc hello.rs
13+
$ ./hello
14+
Hello, world!
15+
```
16+
17+
Note that the above command required that we specify the file name
18+
explicitly. If we were to directly use `rustc` to compile a different program,
19+
a different command line invocation would be required. If we needed to specify
20+
any specific compiler flags or include external dependencies, then the
21+
needed command would be even more specific (and elaborate).
22+
23+
Furthermore, most non-trivial programs will likely have dependencies on
24+
external libraries, and will therefore also depend transitively on *their*
25+
dependencies. Obtaining the correct versions of all the necessary dependencies
26+
and keeping them up to date would be laborious and error-prone if done by
27+
hand.
28+
29+
Rather than work only with crates and `rustc`, we can avoid the manual tedium
30+
involved with performing the above tasks by introducing a higher-level
31+
["*package*"][def-package] abstraction and by using a
32+
[*package manager*][def-package-manager].
33+
34+
### Enter: Cargo
35+
36+
*Cargo* is the Rust package manager. It is a tool that allows Rust
37+
[*packages*][def-package] to declare their various dependencies and ensure
38+
that you’ll always get a repeatable build.
539

640
To accomplish this goal, Cargo does four things:
741

@@ -10,3 +44,22 @@ To accomplish this goal, Cargo does four things:
1044
* Invokes `rustc` or another build tool with the correct parameters to build
1145
your package.
1246
* Introduces conventions to make working with Rust packages easier.
47+
48+
To a large extent, Cargo normalizes the commands needed to build a given
49+
program or library; this is one aspect to the above mentioned conventions. As
50+
we show later, the same command can be used to build different
51+
[*artifacts*][def-artifact], regardless of their names. Rather than invoke
52+
`rustc` directly, we can instead invoke something generic such as `cargo
53+
build` and let cargo worry about constructing the correct `rustc`
54+
invocation. Furthermore, Cargo will automatically fetch from a
55+
[*registry*][def-registry] any dependencies we have defined for our artifact,
56+
and arrange for them to be incorporated into our build as needed.
57+
58+
It is only a slight exageration to say that once you know how to build one
59+
Cargo-based project, you know how to build *all* of them.
60+
61+
[def-artifact]: ../appendix/glossary.md#artifact '"artifact" (glossary entry)'
62+
[def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)'
63+
[def-package]: ../appendix/glossary.md#package '"package" (glossary entry)'
64+
[def-package-manager]: ../appendix/glossary.md#package-manager '"package manager" (glossary entry)'
65+
[def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)'

0 commit comments

Comments
 (0)