call out that cargo install != npm install

[steveklabnik]

I have seen several people assume that cargo install is npm install. Given that JavaScript programmers are one of our big audiences, I think this deserves an explicit call-out above the fold.

[rust-highfive]

r? @matklad

(rust_highfive has picked a reviewer for you, use r? to override)

[ashleygwilliams]

i would also call out in cargo build that's similar ISH to npm install

[ashleygwilliams]

i think this is gonna be very helpful! i know coming from npm i also ran into the muscle memory of wanting to run cargo install all the time and it being the exact wrong thing, heh 😅

[matklad]

Hm, we also have a large audience of non-npm users, for whom this will be confusing :) Could we instead explain what does “install” actually mean in this context?

Perhaps mentioning that it installs the binary into CARGO_HOME would help?

[matklad]

I would think that ‘npm install -g’ is at least partially similar to ‘cargo install’? At least, I use -g to install node utilities for the current user, but I may be missusing this flag :-)

[steveklabnik]

this is a good point, cargo install is lik npm install -g`

[steveklabnik]

Perhaps mentioning that it installs the binary into CARGO_HOME would help?

I added that little bit to the summary because I was reaching for something like this. I think the callout is important, but I also think that the summary line could be improved; maybe this is a good idea.

for whom this will be confusing :)

Wouldn't they see the "if you're an npm user" and just ignore it?

[matklad]

Wouldn't they see the "if you're an npm user" and just ignore it?

Probably, but it still requires some mental processing. To put it other way, this logically can be extended to a sizable table “if npm elif pip elif gradle elif bundler...” and this would certainly be questionable :)

I guess I am just mildly against the idea of singling out npm specifically, but I don’t have any particularly strong feelings, so let’s defer this to someone else:)

r? @alexcrichton

Hm, if we add this to Cargo, can we have “this is completely unrelated to ‘cargo install’” in npm’s help message? 😆

[ghost]

sizable table “if npm elif pip elif gradle elif bundler...” and this would certainly be questionable

Having an actual table with equivalences on the crates.io cargo doc could be an option too. This way, it's a useful reference for everyone coming from another language!

[alexcrichton]

Thanks @steveklabnik! I do sort of share the worry of @matklad though where this may spill over into a very long stream of PRs with "If you're used to X do Y instead"...

Would it not solve the intented problem to put this in the online documentation? Or is this intended for the workflow of doing --help on the command line specifically?

[steveklabnik]

In all of my experiences helping people, it's only been npm users who have been confused. I don't think we need to slippery-slope this.

Or is this intended for the workflow of doing --help on the command line specifically?

Yes, the intention is for people who don't read the documentation, of which there are many.

[alexcrichton]

Could this be perhaps rephrased and placed at the end with the rest of the "explain this command" docs? Something like:

Note that this command may not be the same as other package managers, for example
npm install is more akin to cargo build.

[withoutboats]

I think this is a real problem, but I wonder if there might be a better solution, maybe more complex solution.

Isn't the issue that people are likely to type cargo install when they mean to type cargo build? And doesn't this apply to bundler users also, I recall bundle install being the command?

When you type cargo install, one of two things happens:

1. If you're in a library project, you get error: no packages found with binaries or examples
2. If you're in a binary project, it will attempt to install the binary in ~/.cargo/bin.

Setting aside scenario 2, for the moment, it seems like rather than editing the usage info which you have to explicitly request, we should print an advisory when you run cargo install with no arguments inside a library project. Something like "cargo install is a command which globally installs binaries, did you mean cargo build"?

However, I'm now more worried about scenario 2. Imagine someone creates a little server project, and then tries to build the dependencies with cargo install. Now they have my-example-server in their PATH until they figure out how to uninstall it. This seems like a footgun.

Could we deprecate this behavior of cargo install and instead require an additional flag to install the binary you're in? I only worry that there are scripts making use of the current behaviour. If we could, then just whatever kind of project you're in cargo install prints an error & has an additional note suggesting you may want cargo build.

[steveklabnik]

Isn't the issue that people are likely to type cargo install when they mean to type cargo build? And doesn't this apply to bundler users also, I recall bundle install being the command?

Here's a recent example of this kind of confusion happening: https://www.reddit.com/r/rust/comments/7qc82q/rust_mmxviii_but_like_from_a_casual_perspective/dspte37/?context=10

And yeah:

So, if you do cargo install, then apparently you also need to run cargo build before you can work offline. This was unexpected behavior, and felt it was worth bringing up.

That is, @yoshuawuyts was expecting that cargo install would populate a local cache of various dependencies, and that then a further cargo build/cargo run would use that local cache. Maybe he can expand more if he has some time?

It does seem to me like scenario two is very much the situation here. And what's worse is, that means it's gonna be random if it "works" or not, since you may hit a library project instead of one with binaries.

(And bundle install is cargo build)

[withoutboats]

It does seem to me like scenario two is very much the situation here. And what's worse is, that means it's gonna be random if it "works" or not, since you may hit a library project instead of one with binaries.

Jeez, the fact that it does build the project makes it seem even worse: you might get the idea that its actually right and keep doing it, further compounding your error. When you move to a lib project, you could get the idea that cargo has two different interfaces for building projects depending on if they're libs or bins.

[matklad]

Could we deprecate this behavior of cargo install and instead require an additional flag to install the binary you're in

An excellent idea! We don’t even need a new flag, because —path . should work. However, at least some users want cargo install to work for local crates: #3697

[bors]

☔ The latest upstream changes (presumably #5152) made this pull request unmergeable. Please resolve the merge conflicts.

[matklad]

Tagged 2018 for proposed deprecation in #4943 (comment)

[steveklabnik]

Another instance of this hitting someone on IRC

<nick> I'm trying to compile https://github.com/gimli-rs/gimli/blob/master/examples/dwarfdump.rs...
< nick> I cargo installd a crate it couldn't find; but then it still can't find it:
< nick > rustc dwarfdump.rs -> error[E0463]: can't find crate for `crossbeam` -> cargo install crossbeam -> rustc
             dwarfdump.rs -> error[E0463]: can't find crate for `crossbeam`

[matklad]

At today's meeting we've came to the conclusion that @withoutboats solution is a way to go! So closing this in favor of #5327 :-)

[matklad]

Urgh, I must say that, as an expert user, I now dislike the mandatory --path . Somehow installing local stuff is a somewhat common use-case for me now.

I guess expert users are somewhat more rare and less important (as they can figure the stuff out) than novices here, so the current solution does seem better overall. But still, not being able to just cargo install is a drawback.

[withoutboats]

@matklad you could always add a cargo alias to your config for cargo install --path . :)