Homebrew-core: Hard to understand what keg-only means

[ericandrewlewis]

When I attempt to install [email protected], I get the following output

==> Downloading https://download.elastic.co/elasticsearch/elasticsearch/elasticsearch-1.7.6.tar.gz
######################################################################## 100.0%
==> Caveats
Data:    /usr/local/var/elasticsearch/elasticsearch_ericlewis/
Logs:    /usr/local/var/log/elasticsearch/elasticsearch_ericlewis.log
Plugins: /usr/local/var/lib/elasticsearch/plugins/
Config:  /usr/local/etc/elasticsearch/

This formula is keg-only, which means it was not symlinked into /usr/local.

This is an alternate version of another formula.

If you need to have this software first in your PATH run:
  echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.bash_profile


To have launchd start [email protected] now and restart at login:
  brew services start [email protected]
Or, if you don't want/need a background service you can just run:
  elasticsearch --config=/usr/local/opt/[email protected]/config/elasticsearch.yml
==> Summary
🍺  /usr/local/Cellar/[email protected]/1.7.6_1: 38 files, 29.7MB, built in 15 seconds

I wonder if we could give a bit more context to users here, as it took me a few minutes to understand why Homebrew did what it did and what I should do.

Someone might be able to explain this better, but as I understand the reason that [email protected] is keg-only is because it would conflict with the elasticsearch package, so it is installed under /usr/local/opt/ in case a user wants to install elasticsearch later and not have problems. Maybe we could describe this in the runtime output a bit more?

[ericandrewlewis]

Related: https://github.com/Homebrew/brew/pull/1902

[ilovezfs]

All formulae are installed in the Cellar.
Examples:

/usr/local/Cellar/elasticsearch/5.2.2
/usr/local/Cellar/[email protected]/1.7.6_1

All formulae are opt-linked.
Examples:

/usr/local/opt/elasticsearch -> ../Cellar/elasticsearch/5.2.2
/usr/local/opt/[email protected] -> ../Cellar/[email protected]/1.7.6_1

Only non-keg-only formulae are symlinked into the Homebrew prefix.
Example:

/usr/local/bin/elasticsearch -> ../Cellar/elasticsearch/5.2.2/bin/elasticsearch

By default /usr/local/bin is in your PATH but the following are not in your PATH

(a) /usr/local/opt/elasticsearch/bin
(b) /usr/local/opt/[email protected]/bin

In the case of (a), that's not a problem since /usr/local/bin is already in your PATH and so just running elasticsearch will execute /usr/local/bin/elasticsearch, which is pointing to /usr/local/Cellar/elasticsearch/5.2.2/bin/elasticsearch.

In the case of (b), it can be a problem because /usr/local/Cellar/[email protected]/1.7.6_1/bin/elasticsearch is not symlinked in /usr/local/bin, so you either have to invoke the full path to the file, or you have to prepend /usr/local/opt/[email protected]/bin to your PATH.

The reason to prepend /usr/local/opt/[email protected]/bin instead of prepending /usr/local/Cellar/[email protected]/1.7.6_1/bin is that it will continue to work even if we bump the revision to 2 (1.7.6_2) or if we upgrade the version (1.7.7), whereas the Cellar path would stop working until you updated it to reflect the new version.

Note that using opt paths for non-keg-only formulae is valid too, but is usually just not necessary because non-keg-only formulae are symlinked into /usr/local, which is already in your PATH anyway. However, if you brew unlink a non-keg-only formula, then it behaves like a keg-only formula, and prepending the opt path will let you use it even though it's unlinked, which is useful if you need to install two conflicting non-keg-only formulae, which means at least one of them must be unlinked.

[MikeMcQuaid]

If we can find a phrase (not brew linkd or something) that's unambiguously clearer than keg-only I'm up for changing it but unfortunately I've been unsuccessful in previous attempts to do so.

[chdiza]

Maybe if the caveats also emit a link to the glossary portion of the docs that explain "keg-only", that would at least tell people how to figure out what it means. (Assuming such a page still exists.)

[ilovezfs]

It's in the FAQ http://docs.brew.sh/FAQ.html

[chdiza]

It's in the FAQ http://docs.brew.sh/FAQ.html

Probably then the caveats should include that link, or at least handwave at the FAQ.

[MikeMcQuaid]

I think really we should just come up with a better explanation.

[dpwildboar]

I agree with Mike. this is probably the most confusing and least explained as to what your options are.

for example, postgres defaults to version 10 now even though, at least for me, most of the installations that I have to support are back in the version 9.x world, so keeping my development environment in sync with the deployed versions is more desirable then getting the latest version.

brew install [email protected] (or what ever other version) is not really clear about what one needs to do. making it so that there is some concrete example on what to do I think would also be rather helpful. handwaving at brew link just doesn't seem to cut it for me.