Blurb about Cargo inner workings #4159
Conversation
| Cargo is organized as a set of subcommands. All subcommands live in | ||
| `src/bin` directory. However, only `src/bin/cargo.rs` file produces an | ||
| executable, other files inside the `bin` directory are submodules. See | ||
| `src/bin/cargo.rs` for how these subcommands get wired up with the |
There was a problem hiding this comment.
I'd be totally onboard with redoing how these submodules are organized as well! Something like src/bin/subcommands/*.rs instead of src/bin/*.rs if we'd like to remove this clause!
ARCHITECTURE.md
Outdated
| from. Typical sources are crates.io, a git repository or a folder on | ||
| the local hard drive. | ||
|
|
||
| `Resolve` is the representation of a direct acyclic graph of package |
ARCHITECTURE.md
Outdated
|
|
||
| ## Concurrency | ||
|
|
||
| Cargo itself is mostly single hreaded, but it schedules compiler jobs |
ARCHITECTURE.md
Outdated
| in parallel if possible. However there can be several different | ||
| instances of Cargo running concurrently on the system, so Cargo uses | ||
| file locking when accessing potentially shared data like the registry | ||
| or the target directory. |
There was a problem hiding this comment.
It may be worth pointing out a few high-level things here like:
- Concurrent invocations of Cargo are expected to "always work" but need not be "optimally interleaved". If someone holds the lock for way too long that's ok, we just need to guarantee that nothing needs to go too awry.
- Within one invocation of Cargo there's only concurrency (currently) in the backend compiling. Really that's just spawning a bunch of processes in parallel, ideally this'd all be future-ized so we wouldn't have to have threads at all!
It sounded to me like this paragraph is going for the same thing, maybe it's just worth clarifying a little?
There was a problem hiding this comment.
Does Cargo have any system global data (as opposed to per-user global)?
(E.g. can any locking affect multiple users running Cargo from a common system global toolchain?)
There was a problem hiding this comment.
No, I don't think so. All the "global" data live inside $CARGO_HOME, and each user usually have their own $CARGO_HOME, unless you explicitelly configure Cargo otherwise.
|
Reworded the concurrency section slightly, hope it's clearer now! |
|
@bors: r+ |
|
📌 Commit 8495aa3 has been approved by |
Blurb about Cargo inner workings Hi! At today's dev tools meetings we've discussed how we can foster contributions to rust dev tools, and I've complained that some tools are difficult to contribute to because it's difficult to learn how they work because there are no docs, and some other people complained that Cargo is difficult to contribute to because it is rather complex. And, as a member of Cargo team, I thought that I am probably responsible for fixing that :) So, here's my take at making it easier to dive in into Cargo! I've written a small birds eye overview of the current architecture of Cargo (more like a list of things to look at while reading the code actually :) In general, I am skeptical about documenting internals of binaries (docs will become obsolete, and very fast), but such a high level picture should be pretty robust (I deliberately avoided linking to the actual source code), and so pretty low-effort to maintain. We do something similar for IntelliJ Rust: https://github.com/intellij-rust/intellij-rust/blob/master/ARCHITECTURE.md as well. r? @alexcrichton
|
☀️ Test successful - status-appveyor, status-travis |
Hi!
At today's dev tools meetings we've discussed how we can foster contributions to rust dev tools, and I've complained that some tools are difficult to contribute to because it's difficult to learn how they work because there are no docs, and some other people complained that Cargo is difficult to contribute to because it is rather complex. And, as a member of Cargo team, I thought that I am probably responsible for fixing that :)
So, here's my take at making it easier to dive in into Cargo! I've written a small birds eye overview of the current architecture of Cargo (more like a list of things to look at while reading the code actually :)
In general, I am skeptical about documenting internals of binaries (docs will become obsolete, and very fast), but such a high level picture should be pretty robust (I deliberately avoided linking to the actual source code), and so pretty low-effort to maintain. We do something similar for IntelliJ Rust: https://github.com/intellij-rust/intellij-rust/blob/master/ARCHITECTURE.md as well.
r? @alexcrichton