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.

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

Hard to understand what keg-only means #11091

Closed
ericandrewlewis opened this issue Mar 15, 2017 · 8 comments

Comments

@ericandrewlewis
Copy link

commented Mar 15, 2017

When I attempt to install elasticsearch@1.7, 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/elasticsearch@1.7/bin:$PATH"' >> ~/.bash_profile


To have launchd start elasticsearch@1.7 now and restart at login:
  brew services start elasticsearch@1.7
Or, if you don't want/need a background service you can just run:
  elasticsearch --config=/usr/local/opt/elasticsearch@1.7/config/elasticsearch.yml
==> Summary
🍺  /usr/local/Cellar/elasticsearch@1.7/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 elasticsearch@1.7 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

This comment has been minimized.

Copy link
Author

commented Mar 15, 2017

@ilovezfs

This comment has been minimized.

Copy link
Contributor

commented Mar 15, 2017

All formulae are installed in the Cellar.
Examples:

/usr/local/Cellar/elasticsearch/5.2.2
/usr/local/Cellar/elasticsearch@1.7/1.7.6_1

All formulae are opt-linked.
Examples:

/usr/local/opt/elasticsearch -> ../Cellar/elasticsearch/5.2.2
/usr/local/opt/elasticsearch@1.7 -> ../Cellar/elasticsearch@1.7/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/elasticsearch@1.7/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/elasticsearch@1.7/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/elasticsearch@1.7/bin to your PATH.

The reason to prepend /usr/local/opt/elasticsearch@1.7/bin instead of prepending /usr/local/Cellar/elasticsearch@1.7/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

This comment has been minimized.

Copy link
Member

commented Mar 15, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Mar 16, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Mar 16, 2017

@chdiza

This comment has been minimized.

Copy link
Contributor

commented Mar 16, 2017

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

This comment has been minimized.

Copy link
Member

commented Mar 16, 2017

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

@dpwildboar

This comment has been minimized.

Copy link

commented Dec 22, 2017

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 postgresql@9.6 (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.

@Homebrew Homebrew locked and limited conversation to collaborators May 4, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
5 participants
You can’t perform that action at this time.