rust-lang / rust-lang/cargo

Documentation for cargo vendor use cases

Open
#7,520 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-documenting-cargo-itself C-bug Command-vendor E-medium S-needs-mentor
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.