TIL about cargo package

2026-08-26

• #en
• #til
• #rust
• #cargo

While following the Guix Cookbook I had to look into the contents of the crate's tarball. Guix requires one to do so to check that the package is not bundling any sources. While checking the contents of the tarballs, I found of them contained contained files meant for CI or even the crate's website. Turns out the Cargo manifest has exclude and include fields to handle this cases. In absence of any of those fields cargo follows .gitignore. That should take care of not accidentally publishing sensitive credentials to crates.io.

Looking for guidance on what to include in the tarball, I found this thread. The main point of contention was whether to include the test code or not. One reason to include tests is that crater expects the test code to be included. Guix will also run the tests when building the crate by default. This is a practice that dates back to CPAN, but which has fallen out of favor in the more recent language-specific package managed.

It is a good practice to run the tests to run the test suite when building the artifact to package. It will let you catch potential issues with the code being packaged. For example, Debian doesn't use the Cargo.lock file when building rust crates. Running the tests will catch any potential introduced by using different crate versions than upstream. There are some scenarios where it is not feasible to run the test suite, such as when they depend on external services to be present, such as a database, but they can be disabled on a case by case basis.

Another thing I observed is that sometimes authors that set the exclude field, forgot to update it when new files where introduced. Which is why I would recommend using the include field instead. If you forget to include a file will run into build failures, which will help with keeping the include field up to date.

One question that I have is if the README.md shown on crates.io is the one from the tarball. If that is the case, does that means that if we the README.md includes images to we need to include the images in the crate tarball?