Documentation: Which files should you include in your package?

[e00E]

The cargo book writes about the Manifest options include and exclude here and about publishing here. I find it confusing that the book does not explain which files you should include in the package. Obviously, you need to include the files that you need to build the package. That would usually be Cargo.toml and src/. But what about files that that Cargo includes by default but are not needed to build the package? For example, examples, integration tests, documentation. These files are only relevant to development. I would like the cargo book to explain this.

[epage]

A lot of this is "it depends". Might be helpful to know why you are interested in this, what your underlying concern is for making a decision about this.

For most people, the defaults are probably good enough. The main reason to be concerned is if the size becomes too large. e.g. if large documentation or test assets are included.

Before Cargo 1.80, if you had a [[test]], [[example]], etc in your Cargo.toml and didn't include it, cargo publish would fail. So everything had to be included to be safe. Now, its just a warning and those sections will be stripped.

crater is a part of rust-lang/rust's CI that runs tests across github and across crates.io. Including tests is helpful for that. However, Cargo strips all dev-dependencies without a version which will prevent crater from running tests. The stripping is important for breaking normal/dev dep cycles. In some cases, tests can also be big. So whether to include tests depends.

For a while, examples didn't do much. However, now there is an unstable cargo doc feature to scrape the examples for what parts of your API they use and adds the examples to your API items (example). docs.rs enables this feature for packages automatically.

[e00E]

Thank you for the explanation! I was just curious about this when reading the cargo book. I have some packages and I felt it was correct to minimize them as much as possible. This is from the perspective that the purpose of crates.io is to host the files needed to build libraries and binaries so that consumers can depend on them or install them. I felt there was no need to include files irrelevant to building. But then I was confused that by default cargo adds more than that. I feel it is a reasonable stance that the cargo defaults are fine but I also feel the book could contain the reasoning you just wrote about.