Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix errors in cargo fetch usage guide #9785

Closed
wants to merge 2 commits into from
Closed

Fix errors in cargo fetch usage guide #9785

wants to merge 2 commits into from

Conversation

alerque
Copy link
Contributor

@alerque alerque commented Aug 13, 2021

While working on distro packaging guidelines for Rust software in Arch Linux with another team member (hey @grawlinson) we ran into a disagreement about when and how cargo fetch should be used. After a little bit of clamor it became apparent that one of us was working from fiddling around and testing and the other by reading the documentation. It's unfortunate but in this case the docs seem to be wrong.

See commit messages for further details.

alerque added 2 commits August 13, 2021 15:29
@alerque
Be more clear about when lock files are used
c6de7f2 
Running just `cargo build` after a `cargo fetch` *will* recheck the
dependencies via the network. Running fetch onnly perpares the way for these
other modes to be used withouth needing the network, it doesn't force
subsequent commands to not use the network.
@alerque
Correct default call out for cargo fetch --target
a6e817c 
The description section above this has the actual behaviour correctly
called out:

> If `--target` is not specified, then all target dependencies are fetched.

The options text appears to have been copied from `cargo build` where it
is valid, but the defaults for `cargo fetch` are different.
@rust-highfive
Copy link

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 13, 2021
@ehuss ehuss assigned ehuss and unassigned alexcrichton Aug 13, 2021
@ehuss
Copy link
Contributor

ehuss commented Aug 13, 2021

Thanks for the PR!

I think the original is correct in regards to not accessing the network. Can you say more about why you think it is not the case?

As for the --target flag, yea I think it would be good to fix that. The man pages use a tool to generate all the different formats from a template. The original template source is https://github.com/rust-lang/cargo/blob/master/src/doc/man/cargo-fetch.md, and instructions for running the tool is at https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages. In this case, it uses a general template for --target that is not appropriate for cargo fetch. What I would do is just remove {{> options-target-triple }} and replace it with a simple description customized for cargo fetch.

@grawlinson
Copy link

Glad to see some good come out of our discussion, @alerque 😉

@ehuss ehuss added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 7, 2021
@ehuss
Copy link
Contributor

ehuss commented Oct 23, 2021

I'm going to close due to inactivity, but feel free to follow up if you think the documentation can be clarified.

@ehuss ehuss closed this Oct 23, 2021
@piggynl piggynl mentioned this pull request Feb 17, 2022
Merged
bors added a commit that referenced this pull request Feb 22, 2022
@bors
Auto merge of #10398 - piggynl:cargo-doc-fixes-1, r=weihanglo
c974e35 
Fix errors in `cargo fetch` usage guide

This is a recreation of #9785.

1. By [the doc](https://doc.rust-lang.org/cargo/commands/cargo-build.html#manifest-options), `cargo build` will always access the network unless `--frozen` or `--offline` is present. Instead, `cargo fetch` will fetch dependencies, and which will allow running subsequent Cargo commands in offline mode.

2. A general template was used for `--target` that is not appropriate for `cargo fetch`.
@alerque
Copy link
Contributor Author

alerque commented May 17, 2023

@ehuss I don not believe this should have been closed, the documentation is still wrong on this point.

@ehuss
Copy link
Contributor

ehuss commented May 17, 2023

@alerque This was closed due to inactivity. Did you see the comment above at #9785 (comment)? The --target docs have been fixed in #10398. The other change did not appear to be correct. If you can provide a reproduction, it would be good to open an issue explaining the issue you are running into.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees

@ehuss ehuss

Labels
S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@alerque @rust-highfive @ehuss @grawlinson @alexcrichton