Add a chapter on Cargo

[mark-i-m]

Fix #215

[steveklabnik]

This is a great start!

Where do you want to go from here?

[mark-i-m]

@steveklabnik Thanks :)

I guess the biggest question is what should we include in the cargo chapter?

• Do we want to target consumers of crates only or producers too? This would determine whether we want to add a subsection on cargo publish and crates.io
• Are we including unstable/nightly features? In this case, maybe we might mention
  • Nightly cargo + unstable cargo features
  • cargo bench
  • Integration with other build systems

I'm not sure to what extent anyone learning Rust would need to know about any of these, though. The risk is that we overwhelm beginners with details that aren't that useful to learning the language itself.

Also, I have almost no experience or knowledge of any of them, so I am not sure how qualified I am write about them.

What do you think?

[mark-i-m]

ping @steveklabnik @jbiason @mquandalle @neglectedvalue @arthurprs

Thanks in advance :)

[steveklabnik]

I'm not going to be able to give you a good reply to the broader question for a few days; I'm travelling at the moment. What we have here looks great though :)

[steveklabnik]

I'm back!

I guess the biggest question is what should we include in the cargo chapter?

RBE is mostly about learning the language, so

Do we want to target consumers of crates only or producers too?

We should be targeting consumers, and then saying "hey if you want to make a crate, it's easy! go check out the cargo book."

Are we including unstable/nightly features?

No, we cover stable only.

I'm not sure to what extent anyone learning Rust would need to know about any of these, though. The risk is that we overwhelm beginners with details that aren't that useful to learning the language itself.

Yup, absolutely! So in my mind, it should cover the basics. I'm just going to list stuff out from memory without re-reading your PR:

• cargo build
• basic conventions of the top-level directories
• dependencies
  • crates.io and deps fro it
  • git deps
  • path deps
  • override and patch or whatever the latest way to do this is, I forget which one
• workspaces
• profiles
• the -sys crate convention from a usage perspective, which leads you into:
• build scripts

thoughts?

Also, I have almost no experience or knowledge of any of them, so I am not sure how qualified I am write about them.

I'm happy to take even just the start of things, and we can make issues for the others!

[mark-i-m]

@steveklabnik Thanks for the response!

You pointed out a lot of gaps in my chapter so far, which I will start filling in :)

basic conventions of the top-level directories

Could you elaborate on what you mean by this?

I'm happy to take even just the start of things, and we can make issues for the others!

Yeah, I think that would be good. It might also be nice to have a tracking issue with some sort of checklist. I think I can get most of the points you listed in this PR, but there are a few I still don't know much about (e.g. workspaces, profiles, -sys crates, override/patch/replace).

Thanks again 👍

[steveklabnik]

Could you elaborate on what you mean by this?

yeah like basically this stuff: http://doc.crates.io/book/guide/project-layout.html (this is the upcoming re-organization of cargo's docs into mdbook format)

[mark-i-m]

Oh, got it :)

Just a heads up: Things have gotten rather busy for me lately, so I might be a bit slow on this...

[mark-i-m]

Hi @steveklabnik! I'm back. I think I have covered a coherent subset of the things you listed. I also created a tracking issue for the rest in #978 . I think this initial portion is ready for a final review before merge.

Let me know what you think.

Merry Christmas ⭐

[mark-i-m]

@steveklabnik ping :)

[steveklabnik]

Sorry for taking so long, this is great, thank you :)