Documentation for cargo vendor use cases
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 15.5k
- Forks
- 3k
- Avg merge
- 23h 30m
- Merged PRs (30d)
- 51
Description
Problem
Cargo vendor has limited docs : https://doc.rust-lang.org/nightly/cargo/commands/cargo-vendor.html . While this describes what cargo vendor does as a tool, it doesn't encompass the larger needs of an opensource project to use vendoring for offline builds in build farms etc.
As a result, while attempting to integrate rust into a project, we have found that certain cases are non-intuitive or may not work.
I would like to ask that cargo vendor be documented with how a project would integrate it into their work flows. Important considerations are:
- We need to ship and provide .cargo/config in our source tree so that developers have consistent relative paths to vendor, and unpacked tar-balls match git trees. We also can't assume paths in offline build tools for various companies
- how to use cargo build/rustc with offline builds and vendored dependencies.
- how to use cargo test with offline builds and vendored dependencies
- how to correctly use cargo vendor to acquire dependencies
- how to perform online builds even in the presence of a source tree .cargo/config for developers who are updating dependencies, or rather, to smooth "on boarding" so we don't need to ask developers to vendor/prepare their environments to do builds.
These are all important aspects that today we have struggled with with cargo vendor, so having these generic workflows documented would really help other projects to adopt cargo with vendoring.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing cargo vendor documentation at the linked cargo-vendor page and review the workflows listed in the issue. Document acquiring dependencies, configuring relative vendor paths, offline cargo build/rustc and test usage, and online builds with a source-tree configuration; done means these use cases are covered for project adopters.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100