Its the kind of customization creep that makes me groan and turn to stack overflow instead whenever I try to read the man pages of any of the standard UNIX utilities: their man pages are an information overload that make it too difficult to learn things.Īn obvious way to help resolve their close similarity is to clarify the differences in the -help output. From the -help output I could not understand how they were different, and I don't think their names indicate that the most material difference between them is that one excludes the intermediate artifacts. I think there's a larger problem here, but these two flags in particular have such similar behavior that keeping them both has unique negative UX consequences aside from the general concern. It was in the process of investigating how the flags to cargo build had proliferated that I noticed these two flags. This surprised and concerned me, so I took statistics of how cargo build -help's output has grown over time: So I noticed a few days ago that when I ran cargo build -help it went beyond the length of my terminal. The higher level commands could be defined in terms of that lower level command, and people writing very bespoke integrations can also build their own build command out of it. I think a preferable approach to what we've done would be to provide some lower level command which takes as many flags as you want and can be used to build up the user-oriented commands like cargo build, cargo run, and cargo test, but with all of the flags to customize the precise nature of its operations. I think hiding these tools from -help unless you pass another flag is a half measure, which improves the situation but is probably not the best solution. However, I think this has a bad UX overall, because it makes the tool overwhelming and ultimately makes all of the flags undiscoverable.
For a long time we've been creeping in the direction of having flags to customize every user visible aspect of the behavior, because this has been how CLI tools traditionally handle users wanting to customize their behavior. I am unhappy with the UX of having all of these flags also. Perhaps we should hide such "useful in very specific circumstances" flags from cargo cmd -help by default? However, this could be said about some other flags as well, like -manifest-path, -message-format, -build-plan, -frozen, -locked. Since target-dir is stable, I'm not sure if there's an available avenue to unify these flags other than just only providing target-dir.Ĭc do agree that for most of the users, interacting with Cargo's CLI, these flags are irrelevant. I'm not certain I agree that either of them should have been added as flags (an argument is made that flags are better than env vars, and while I agree in principle for user oriented APIs, I don't think that build system integration is a user oriented API in the relevant sense), but I'm definitely suspicious of having both of these very similar flags provided. I can't help but notice that these two flags do very similar things! They also seem to have been designed for very similar purposes (build integration, the meson project is mentioned specifically in both of them). out-dir is still unstable, but -target-dir was instantly stabilized (by mistake, I believe). (I'm not 100% certain I've accurately described their behavior in relationship to the profile specific subdirectories.)
a debug build will be built into target-dir/debug).