New Chapter: Creating a library with cargo #292
Conversation
steveklabnik
force-pushed
the
creating-a-library
branch
from
0442be5 to
9d2dfdd
Compare
| - [Organizing your Public API](chXX-02-public-api.md) | ||
| - [Documentation](chXX-03-documentation.md) | ||
| - [Workspaces and Multiple Related Crates](chXX-04-workspaces.md) | ||
|
|
There was a problem hiding this comment.
I think there's still a problem having to do with us changing this file on master since you opened this PR-- this chapter is duplicated 2 chapters below here, in the "Thinking in Rust" quarter. Was that intentional?
There was a problem hiding this comment.
ugh, no i messed up my rebase.
| @@ -0,0 +1,175 @@ | |||
| # Creating a Library with Cargo | |||
There was a problem hiding this comment.
I feel like this chapter could use an intro that talks about why you might want to write a library and publish it, so that people who have no interest in doing so could potentially skip or skim this chapter. This chapter helps with reading and contributing to other peoples' crates, so maybe mention that as well.
| featured tool, and it has a lot to offer. In this chapter, we'll dig more into | ||
| the features of Cargo. | ||
|
|
||
| ## Why does Cargo exist? |
There was a problem hiding this comment.
I feel like a lot of this section is covered in chapter 1, and there isn't much additional detail...
| ## `Cargo.toml` and `Cargo.lock` | ||
|
|
||
| `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk | ||
| about them, here’s a summary: |
There was a problem hiding this comment.
I feel like a lot of this section is covered in chapter 2 when we pull in rand...
| command-line tool or an application, 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.html#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). |
There was a problem hiding this comment.
If we're going to have these sections in this chapter, detail about why you, as a library author, wouldn't want to check in your Cargo.lock is exactly the sort of detail we should be pulling in....
There was a problem hiding this comment.
Stuff like in this post would be awesome here imo: https://www.reddit.com/r/rust/comments/2ipwvx/why_cargolock/
|
|
||
| ## `cargo install` | ||
|
|
||
| ## Extending Cargo with subcommands |
There was a problem hiding this comment.
I'm not sure that cargo install and "Extending Cargo with subcommands" belong in this chapter, since they don't really have anything to do with creating a library. Working on an existing cargo package sounds like it would fit though!
| @@ -0,0 +1,87 @@ | |||
| # Crates.io | |||
|
|
|||
| [crates.io] is the Rust community's central repository that serves | |||
There was a problem hiding this comment.
I was imagining this section talking more about how to publish a crate on crates.io-- what additional info in your Cargo.toml is recommended, how to think about your version numbers, what cargo publish does, etc. Not so much "go to crates.io and click on these things" since that might change, more like "here are the things you should think about when you publish a crate".
| @@ -0,0 +1 @@ | |||
| # Organizing your Public API | |||
There was a problem hiding this comment.
Things I was thinking would be in this section:
pubmeans "these are the ways i expect users to use this library"pub usefor exporting a different structure than your internal structure for user convenience- Consequences of
pub useing something from one of your dependencies (plz don't do it) - How do you know which version number to bump when you make which kinds of changes
| @@ -0,0 +1 @@ | |||
| # Documentation | |||
There was a problem hiding this comment.
Things I was thinking would be in this section:
- Doc comments stuff we cut out of the comments section, and the current book has great stuff too
- How to use rustdoc to generate your crate's html docs
- Convention of providing working examples in the
examplesdir and how to test them
I wouldn't expect it to cover how to hosting docs online.
| @@ -0,0 +1 @@ | |||
| # Workspaces and Multiple Related Crates | |||
There was a problem hiding this comment.
I'd expect this section to talk about why you might want to use workspaces with your project: it's getting big, it's actually multiple separate crates, but they need to be developed and released together. I'd then expect explanation of how to specify workspaces in the various Cargo.tomls and how to structure the directories, basically the info from the crates.io docs. Also how workspaces interact with the cargo commands... looks like for now you have to do each manually?
|
This article has some things that are relevant to this chapter: https://pascalhertleif.de/artikel/good-practices-for-writing-rust-libraries/ |
|
Not happy with this. Starting over. |
This is very early stages, bringing in some stuff from the Cargo guide. Not really ready for review.