Suggestion: Show options before install

[onlyhavecans]

For those who like to jump right into the quick start it would be useful to more openly document the brew options XXX command. Currently the options command is only well documented in the man page, not help or getting started.

A sub suggestion is to also disclose options available before install. While it it would add an extra step it prevents an extra step when you realize that the default doesn't have the feature you need and you have to brew uninstall X && brew remove X && brew install X --option --option2

[Sharpie]

A sub suggestion is to also disclose options available before install. While it it would add an extra step it prevents an extra step

This would be helpful the first time you installed something and excruciatingly annoying every time after that. This would also complicate scripts that automatically install software using Homebrew.

Reading the manual and running brew options <formula> before brew install <formula> seems like a better habit to encourage.

[adamv]

But still, we could make brew options more visible, in an updated or better Homebrew tutorial for instance.

[jeffstyr]

I had a similar thought, since basically you always want to run brew options before a brew install (because you don't have any a priori reason to know if the default is right for you).

One idea would be to have a --default flag to indicate that you want to use the default options, and require passing some flag to brew install foo to indicate what you want (i.e., you pass --default if you are not passing any other flags, otherwise you just get the output of brew options foo).

The idea here is to force an active decision about what you want to install. For me, it's not that I don't know that brew options exists, it's just that it's easy to forget that it does. This approach would turn forgetting into reminding you, rather than turning forgetting into possibly having to redo the install. (And, it would still be easy to script installs.)

Just an idea.

[Sharpie]

I still think an interactive configuration step would be universally loathed by most brew users if they had to deal with it when it is no longer helpful. Adding a --default flag to disable it would break every existing script that wraps Homebrew and force everyone who is familiar with the existing usage to retrain themselves---that adds up to a net negative in the user happiness department.

We could add a --configure flag that one could pass that would trigger the interactive configuration, but then I don't see much difference between training oneself to pass --configure vs training oneself to run brew options before brew install. Add the extra effort required to write, debug and maintain the code backing --configure and I don't really see a viable argument for having it.

Making sure brew options is documented in places that are easier to find sounds like the best thing we can do at the moment.

Remember, "adding more hand holding" is a surefire way to send the usability of a program straight to hell:

➜  ~  brew install cowsay

 _________________________________________ 
/ It looks like you are installing cowsay \
| for the third time. Can I interest you  |
| in another rousing round of 20          |
\ questions?                              /
 ----------------------------------------- 
   \     ___
    \   /   \
     \ /     \
      /       \
    ___       ___
   /___\     /___\
   \*__/     \*__/
     |        |
     | |      | |
     | |      | |
     | |      | |
     |  \    /  |
     |   \__/   |
      \        /
       \      /
        \____/
➜  ~  fuuuuuuuuuuuuuuuuuuuuuuuuuuuuu

[adamv]

Also: Homebrew is already a part of various automated toolchains (chef provider, for instance), so brew install needs to stay non-interactive.

[jacknagel]

Agree w/ everything @Sharpie and @adamv have said here.

[jeffstyr]

I'm not talking about anything interactive (not sure where that impression came from), I'm talking about (roughly): jeffstyr/homebrew@be4143d14371a168f7e41779428c4de2bb6e268c

That approach wouldn't likely break any sort of existing automation, and only calls for clarification when there is something to clarify. (Motivating example: If you brew install subversion, do you assume you'll get the perl bindings or not? Either assumption is reasonable, and you could easily not even think about it and be unpleasantly surprised.) It's not about hand-holding, it's about not arbitrarily defaulting.

[adamv]

The way to solve this issue is not to change the current Homebrew behavior, but to make Homebrew itself even more automatable, so that higher-level user tools are easier to write. Like how Git has plumbing and porcelain.

A GUI for Homebrew that showed what deps would be installed, and allowed setting install options on each dep, would be cool, for instance.

[Sharpie]

I'm talking about (roughly): jeffstyr/homebrew@be4143d

As Adam and I noted we can not change the behavior of brew install <formula>. Adding a requirement for a --default flag would disrupt the habits of every Homebrew user and would require every piece of software that uses Homebrew for automatic provisioning to update their code.

Simply put: the ends don't justify the means. Changing the default action of brew install is not an option that is on the table as a solution to a "problem" that can be rectified by man brew and a healthy habit of paying extra attention to detail when installing software.

[jeffstyr]

As implemented, it would not break automated installs, actually.

Anyway, just an idea. If anyone wants the behavior, they can pull it from my branch.

[Sharpie]

As implemented, it would not break automated installs, actually.

That is true---I didn't read the conditional closely enough. Most automated installs should be fine, but from my experience on this issue tracker I would bet that there is a script out there that could fool the TTY check as I have seen it happen before (e.g. #12779).

I don't mean to belittle the idea---the intent is to reduce chaos and confusion and that is a good thing. However, the scales don't justify the change when weighing the chaos averted against the chaos created by changing the "normal" behavior of our most-used commands.

[jacknagel]

Also "brew install --default" is... not the default.

[jeffstyr]

Are you referring to the flag name? Okay, then --default-options. Not really the important point.

[jacknagel]

I'm referring to the insanity of requiring an option to get the default behavior.

[jeffstyr]

I don't want to belabor the point, but the intent wasn't to mean "execute the default behavior", it was to mean "build with a pre-chosen set of options". Actually, the real point was that in cases where the options are consequential, the idea of most users being happy with some particular pre-chosen set is suspect, and requiring an explicit choice is sensible.

Again, just exploring some ideas.

[jacknagel]

I don't want to belabor the point, but the intent wasn't to mean "execute the default behavior", it was to mean "build with a pre-chosen set of options".

Same difference. Any type of default that requires a switch is not a default of any sort.

Actually, the real point was that in cases where the options are consequential, the idea of most users being happy with some particular pre-chosen set is suspect, and requiring an explicit choice is sensible.

Part of Homebrew's philosophy is to minimize the number of available options in the first place, so that brew install foo without any options builds what 99% of users want. We try to limit options to exceptional cases.

[jeffstyr]

On Jul 7, 2012, at 9:55 AM, Jack Nagelreply@reply.github.com wrote:

I don't want to belabor the point, but the intent wasn't to mean "execute the default behavior", it was to mean "build with a pre-chosen set of options".

Same difference. Any type of default that requires a switch is not a default of any sort.

That's actually linguistically not true, but I'll drop it.

Actually, the real point was that in cases where the options are consequential, the idea of most users being happy with some particular pre-chosen set is suspect, and requiring an explicit choice is sensible.

Part of Homebrew's philosophy is to minimize the number of available options in the first place, so that brew install foo without any options builds what 99% of users want. We try to limit options to exceptional cases.

Right, and what I'm challenging is the idea that in those exceptional cases there exists a single set of options that 99% of users want. (For example, consider subversion. I doubt that 99% of users want the perl bindings, and I doubt that 99% do not want them. It's likely somewhere in the middle.)

---

Reply to this email directly or view it on GitHub: https://github.com/mxcl/homebrew/issues/13224#issuecomment-6824616

[jeffstyr]

Actually, the fact that it's the exceptional case is significant. Since most of the time there are no options, that trains users not to check. The design challenge is, how to call it to the user's attention when there actually are significant choices.

[jacknagel]

And the solution to a few exceptional cases is not functionality that interferes with every installation.

[jeffstyr]

I agree, I'm brainstorming, I didn't say my idea was perfect. (One correction: the sketch implementation in my referenced commit doesn't interfere with every installation, only those which actually have options, which as you indicated are the exceptional cases.)

Another idea would be to do something along these lines on a per-formula basis (so that formulas with important-to-think-about options could declaratively indicate this), or even better on a per-option basis (there are formulas for which having to explicitly indicate either --with-X11 or --without-X11 would make sense).

But even if you don't like my particular ideas, it's a legitimate issue which deserves some thought.

[2bits]

An install could spit out the available options before it builds.

[2bits]

That wouldn't affect current functionality in any way. It would just be some useful info.

[jacknagel]

An install could spit out the available options before it builds.

I don't like it. All that does is say, "By the way, here are some things you could have chosen. OK on with the install!" and the user has to abort anyway.

I'm all for better documentation, but I really think adding stuff to the install command is the wrong way to solve this.

[2bits]

Ok. I happen to think that more info is better. It only takes a line.

For people who don't know about options because they don't read the man page, this informs them that there are options.

For people who know about options but forgot to check them, this helps to remind them.

For people who know about options and did check them, this shows the correct spelling so they can assure themselves they specified their choice correctly. As it stands now, unrecognized options are ignored.

For people who are installing one formula with ten deps like pygtk using brew install pygtk, they will get to see the options for each dep as it gets installed.

Honestly I don't see the downside. Aborting an install seems harmless, and this is really not trying to solve anything. It just makes it more informative. And while we're discussing things, has it ever been suggested to move brew options into brew info? Informing about the version, location, and options for a formula seems logical.

[jeffstyr]

Regarding info v. options: Another problem with having them separate is that brew info reports the caveats and brew options does not, and sometimes the caveats are about the options. :/

Regarding documentation: This really isn't a documentation issue. It's not a matter of not knowing that brew options exists, it's a matter of not knowing it's relevant for a particular formula.

Here's my characterization of the issue: "Most formulas don't have significant options, so how can the the formulas which do, get called to the users attention?" (Secondary assertion: The very existence of an option implies that a significant chunk of users will care about it--otherwise, it wouldn't even be an option, typically.)

Again, I don't know the perfect solution, but it's more than just a simple matter of documentation.

[2bits]

Well it's not perfect, but it works. I can see the downsides now after thinking about the other comments here, and there are more important issues at hand I'm sure.

[Sharpie]

Honestly I don't see the downside.

I think printing options out during the install decreases the signal-to-noise ratio. For example, listing the options for each install may lead to an increase of issues opened because people didn't bother to read caveats.

It's not a matter of not knowing that brew options exists, it's a matter of not knowing it's relevant for a particular formula.

Honestly, installing software is serious business. Every time I install something that I am not intimately familiar with, I run brew home <formula> and spend a couple of minutes browsing the homepage and skimming the docs. Then I run brew options <formula> to see if the install can be altered in any significant way. Finally, I run brew install <formula>---but only after exercising due diligence by performing a bit of research on the software I am about to run on my computer.

I'm still not seeing a convincing argument for dialing up the verbosity for everyone just because there are a handful of people who don't do their homework.

@mxcl, @mikemcquaid, @mistydemeo

Any thoughts on this one?

[adamv]

The solution is to build higher-level UIs on top of brew.

[MikeMcQuaid]

Agreed with @Sharpie and @adamv.

[jeffstyr]

Plumbing v. porcelain doesn't resolve it, it just rephrases the question as what the primary porcelain should do.

[mistydemeo]

I definitely support improving usability, but I really do think that brew install's default behaviour is more or less the most appropriate for the standard use case. As the standard "install some stuff" command I don't want it to turn into cpan's 20 questions. ;)

It does sound like there would be user support for sort of brew wizard for new users, but I don't think that's best implemented as the default install command.

[bunnyhero]

How about at least showing the 'brew options' command in 'Example usage:' in the output of brew help?

[Sharpie]

@bunnyhero

Good suggestion. Added in 77f0b38.