You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[ These notes refer to The Cargo Book, as it exists as of commit 2af662e. ]
Description
The trasition between the "Introduction" and the the "Getting Started"/"First
Steps with Cargo" page could be made more reader-friendly by explaining a
handful of essential terms before they are used in an actionable way. These
terms include:
package
crate
library crate
binary crate
module
workspace
Just knowing that these are "essential terms", knowing roughly what they mean,
and how they relate to one another sets the reader up for success with the
sections that follow.
Motivation
The current reading sequence is as follows:
The "Introduction" mentions that Cargo is Rust's "package manager", and
that it manipulates "packages" (whatever those are).
The "Getting Started" index urges the user to install Cargo (and Rust)
and to set up the user's first crate (whatever that is).
The "Getting Started"/"Installation" page gets the use squared away with
tools installation.
The "Getting Started"/"First Steps with Cargo" page then dives into
instructing the user to "start a new package with Cargo".
Up until this point, the user has not been told what a "package" or a "crate"
is. A new user just poking around Rust might wonder, "What is a package, and
why would I want one? And what does a crate have to do with it?"
The terms in the above list are all well defined elsewhere in the Rust and
Cargo documentation, but a new user encountering them for the first time
should not need to hunt them down.
Since the opening sections of the Cargo book are among the first documents a
new user is likely to encounter, it would be nice to provide a little
cheatsheet at this stage of the essentials. Defining the words in the above
list would give the reader a good foothold to map concepts they may be
familiar with from other languages onto their Rust counterparts (roughly
speaking).
Outstanding Questions
Q: Should we say "a Rust package" or "a Cargo package"?
It seems pretty clear that the concepts of a "module" and a "crate" are baked
into the Rust language, so referring to "a Rust module" or "a Rust crate"
seems appropriate. (Please correct me if that is not correct.)
It also seems pretty clear that the concepts of a "package" and a "workspace"
are higher-level constructs introduced by Cargo. And conceivably, some other
tool could come along one day and replace Cargo packages and modules with some
other organizing construct (though it would likely look pretty close to what
we have today).
With that being the case, is it more correct (or even just desirable) to refer
to "a Rust package" or to "a Cargo package"? There is an equivalent question
for "workspaces", presuming that whatever is decided for "package" will hold
for "workspace", as well.
The text was updated successfully, but these errors were encountered:
[ These notes refer to The Cargo Book, as it exists as of commit 2af662e. ]
Description
The trasition between the "Introduction" and the the "Getting Started"/"First
Steps with Cargo" page could be made more reader-friendly by explaining a
handful of essential terms before they are used in an actionable way. These
terms include:
package
crate
library crate
binary crate
module
workspace
Just knowing that these are "essential terms", knowing roughly what they mean,
and how they relate to one another sets the reader up for success with the
sections that follow.
Motivation
The current reading sequence is as follows:
The "Introduction" mentions that Cargo is Rust's "package manager", and
that it manipulates "packages" (whatever those are).
The "Getting Started" index urges the user to install Cargo (and Rust)
and to set up the user's first crate (whatever that is).
The "Getting Started"/"Installation" page gets the use squared away with
tools installation.
The "Getting Started"/"First Steps with Cargo" page then dives into
instructing the user to "start a new package with Cargo".
Up until this point, the user has not been told what a "package" or a "crate"
is. A new user just poking around Rust might wonder, "What is a package, and
why would I want one? And what does a crate have to do with it?"
The terms in the above list are all well defined elsewhere in the Rust and
Cargo documentation, but a new user encountering them for the first time
should not need to hunt them down.
Since the opening sections of the Cargo book are among the first documents a
new user is likely to encounter, it would be nice to provide a little
cheatsheet at this stage of the essentials. Defining the words in the above
list would give the reader a good foothold to map concepts they may be
familiar with from other languages onto their Rust counterparts (roughly
speaking).
Outstanding Questions
Q: Should we say "a Rust package" or "a Cargo package"?
It seems pretty clear that the concepts of a "module" and a "crate" are baked
into the Rust language, so referring to "a Rust module" or "a Rust crate"
seems appropriate. (Please correct me if that is not correct.)
It also seems pretty clear that the concepts of a "package" and a "workspace"
are higher-level constructs introduced by Cargo. And conceivably, some other
tool could come along one day and replace Cargo packages and modules with some
other organizing construct (though it would likely look pretty close to what
we have today).
With that being the case, is it more correct (or even just desirable) to refer
to "a Rust package" or to "a Cargo package"? There is an equivalent question
for "workspaces", presuming that whatever is decided for "package" will hold
for "workspace", as well.
The text was updated successfully, but these errors were encountered: