Installation with Homebrew isn't complete.

[seivan]

Describe the bug
Installing asdf with homebrew should work out of the box, assuming $PATH is properly set up to find the asdf binary.

To Reproduce

Steps to reproduce the behavior:

1. brew install asdf

Expected behavior
It should work.

Actual behavior
It's incomplete and doesn't work.
Throws an error

cat: /usr/local/VERSION: No such file or directory
version: 

cat: /usr/local/help.txt: No such file or directory

"Late but latest"
-- Rajinikanth

Instead, to work around it, you also have to source /usr/local/opt/asdf/asdf.sh which modifies for shims and the asdf executable (again).

In general, $ asdf help and other commands don't work until that's been setup, which is bad.

There are other issues, such as polluting /usr/local/lib and other directories since it's a straight up prefix.install with a glob, something Homebrew advices against.

Related PR(s):
Code
Homebrew/homebrew-core#73173
Documentation
#898

Related
#785
#607
#394
#428

[seivan]

I added a fix to the Homebrew formula Homebrew/homebrew-core#73173
This creates a libexec to the binary bin/asdf so shell script source paths work without worrying about symlinks.
No need to for additional steps as long as /usr/local/bin is in your $PATH.
In other words, you no longer need
echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc which was a bad idea to begin with.

The only concern here is that /asdf.sh isn't being sourced at all.
But isn't necessary if you're using default $ASDF_DATA_DIR and $ASDF_USER_SHIMS.
Since documentation claims $ASDF_DATA_DIR by default is ~/.asdf it just works fine out of the box.

If anyone wants a different directory for $ASDF_DATA_DIR , they can set that themselves.

[jthegedus]

I have left some questions about the migration path in the Homebrew issue. I would really like this change to succeed if it means no more issues being raised about Homebrew install not working. But I am concerned how this change would impact all Homebrew users with the current configuraitons.

which was a bad idea to begin with.

Out of curiosity, why is it you think having users understand their Shell configuration is a bad thing? Especially for a tool that configures Shell behaviour? OMZSH is an entire ecosystem of plugins managed via your Shell config, why is it bad?

More importantly, why isnt /asdf.sh part of the bin/asdf.sh directly?

I don't know the answer to that, @Stratus3D probably does.

[seivan]

@jthegedus

To ask people to source it manually, should be considered a bug.

Disagree with this sentiment, especially when the proposed solution requires manual user intervention anyway.

The manual user intervention is not necessary to make asdf to function correctly!
It's only here if you want shims in $PATH. Even if you were to skip that, asdf itself as a program still functions correctly, meaning you can do $ asdf help or asdf plugin add ruby.

Obviously majority use would like to add them to $PATH, and you can now do that in .zshenv since you no longer rely on calling a ruby program for "$(brew --prefix)". Sure you can hard code the path, but that doesn't take away all the other issues mentioned below.

If the shims where, say under /usr/local/bin then it would be unnecessary, and that could be a new feature for asdf to accept a $ASDF_SHIMS_DIR env variable, for letting people dump the shim in folders that are already under their $PATH, but that's a different topic and not something I am requesting or want, just pointing out as an example.

It's not just the manual intervention I have issues with, it's the fact that the script itself requires to be sourced because of a poor installation process that not only requires you to source a file at an arbitrary location that modifies your $PATH, but also clutters files across the place that don't need to be there using a glob install in Homebrew that distributes files to folders they shouldn't be in.

Homebrew mentions this:

I have left questions regarding this change in Homebrew/homebrew-core#73173

I am hopeful the upgrade path for the proposed solution will be seemless.

Thank you, I'll be taking a look.

[seivan]

@jthegedus

I have left some questions about the migration path in the Homebrew issue. I would really like this change to succeed if it means no more issues being raised about Homebrew install not working. But I am concerned how this change would impact all Homebrew users with the current configuraitons.

There are two changes that are going to happen.
First off, the shims will be invalid because they will point to an invalid path. This is more related to Homebrew versioning its packages, so if your current version is 0.8.0_1 and you install an update, it'll be a different number.
In our case, we aren't installing a new asdf, so the version remains 0.8.0 but a new revision which will be 0.8.0_2

So my current shims are at

!/usr/bin/env bash
# asdf-plugin: elixir 1.11.3
exec /usr/local/Cellar/asdf/0.8.0_1/libexec/bin/asdf exec "iex" "$@"

But they need to point to

!/usr/bin/env bash
# asdf-plugin: elixir 1.11.3
exec /usr/local/Cellar/asdf/0.8.0_2/libexec/bin/asdf exec "iex" "$@"

So you need to do an asdf reshim, or just do what I did and rm -rf ~/.asdf/shims; asdf reshim

Secondly, if you sourced "$(brew --prefix asdf)/asdf.sh" , you can remove that if /usr/local/bin is already in your $PATH.
If it's not, then you need to change that to "$(brew --prefix asdf)/libexec/asdf.sh" but my suggestion is that people should not do that, and just fix their $PATH. Technically if you're already using Homebrew this should most likely be setup, otherwise this will be the least of your concern, I mean not even Homebrew would work appropriately in that scenario.

which was a bad idea to begin with.

Out of curiosity, why is it you think having users understand their Shell configuration is a bad thing? Especially for a tool that configures Shell behaviour? OMZSH is an entire ecosystem of plugins managed via your Shell config, why is it bad?

That's not what I am saying.

I am saying that it's wrong of asdf to spread its files (or technically symlinks) to various folders under /usr/local/.
It should be a self contained script that's executable under a single binary in /usr/local/bin anything else is just fundamentally wrong and requires hacks such as "$(brew --prefix asdf)/asdf.sh".

Keep in mind that ``"$(brew --prefix asdf)/` actually runs ruby which slows down your shell.
You could hardcode the path, but that just seems unnecessary to me.

brew --prefix asdf --debug
/usr/local/Homebrew/Library/Homebrew/brew.rb (Formulary::FormulaLoader): loading /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/asdf.rb
/usr/local/Homebrew/Library/Homebrew/brew.rb (Formulary::TapLoader): loading /usr/local/Homebrew/Library/Taps/seivan/homebrew-custom/Formula/asdf.rb

If I am installing a program, I expect it to work out of the box if its under my $PATH, there are exception to this, such as databases (postgres) but in general, there is nothing in asdf that would require something like that.

It's not to say you don't need to configure your shell, you obviously do, but just for your package manager, anything else should work.

More importantly, why isnt /asdf.sh part of the bin/asdf.sh directly?

I don't know the answer to that, @Stratus3D probably does.

It seems to me, and I could be wrong that it just modifies $PATH

[seivan]

@jthegedus Just to keep you updated, the current PR no longer has a need for a migration step with current setup.
Though I added a caveat in case you do want to change.

Changes

• Installing under libexec to maintain relative paths for sourcing scripts.
• No longer installing files under lib
• Binary in /usr/local/bin/ will point to /usr/local/opt/asdf/libexec/bin/asdf to keep the shims from breaking on updates.
• Caveat added for new users to:
  • Optionally sourcing asdf/libexec/lib/asdf.sh if needing $ asdf shell <package> <version>
  • Export shims in$PATH since asdf/libexec/lib/asdf.sh does not do that. As opposed to asdf/libexec/asdf.sh
• With changes suggested by @cho-m
  • Existing shims will not break, will instead having a layer of indirection. New shims will not need that.
  • Current sourcing of asdf/asdf.sh will not break as it points to asdf/libexec/asdf.sh
  • Existing users do not need to update their $PATH if they are currently sourcing asdf/asdf.sh as it points to asdf/libexec/asdf.sh

Migration

Existing solutions will work fine
source "$(brew --prefix asdf)/asdf.sh"

But you can also do
source "$(brew --prefix asdf)/libexec/lib/asdf.sh"
And add shim manually to $PATH

Caveat

The caveat currently pending review mentions the "newer" approach

  def caveats
    <<~EOS
      Add shims in $PATH by having the following line your ~/.zshenv or #{shell_profile}:
        export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

      To support package version per session using asdf shell <name> <version>
      Add the following line to your #{shell_profile} file:
         . #{opt_libexec}/lib/asdf.sh
      Restart your terminal for the settings to take effect.
    EOS
  end

[DanielKehoe]

The installation instructions say "Add asdf.sh to your ~/.zshrc with...". However, the Homebrew post-installation message for asdf doesn't mention this. I see there is a PR here to change the Homebrew asdf formula. Perhaps, if the PR is still under discussion, the Homebrew post-installation message can be changed in the meantime to instruct the user to update the .zshrc (or equivalent bash or fish) file.

Note that adding asdf to the shell configuration is necessary for Apple Silicon (where Homebrew installs packages to /opt/homebrew/). Perhaps it isn't necessary for Mac Intel (where Homebrew installs packages to /usr/local/).

[jthegedus]

@DanielKehoe

Perhaps, if the PR is still under discussion, the Homebrew post-installation message can be changed in the meantime to instruct the user to update the .zshrc (or equivalent bash or fish) file.

I appreciate that others think this is a good idea, unfortunately I have pursued that idea without any luck on the Homebrew side.

[DanielKehoe]

@jthegedus May I see the PR or issue you submitted to Homebrew?

I wonder if anything has changed since Apple released M1 and Homebrew is moving to use its own /opt/homebrew installation directory. On Apple Silicon, there's a need for clear instructions as part of the installation.

[jthegedus]

@DanielKehoe This current issue is tracking the work to be done to resolve the suggestion that came out of the conversation after the one you're asking for... there's a lot of prior conversation on this.

• Initial Homebrew core PR - asdf: add install instructions to caveats Homebrew/homebrew-core#54315
• Further discussion here - Common Homebrew issues 🍻 #785
• which led to this issue you're on

Note the conversaton in #785 as some of it is from a Homebrew contributor.

---

I cannot speak for Intel vs Apple Silicon differences. I have yet to get to reviewing the work the OP has done to rectify the initial issues.

[DanielKehoe]

Thank you for the helpful reply. I understand the obstacle now. I see a Homebrew maintainer said, "Anything that is definable in documentation is not supposed to be in caveats. Those are only for homebrew specific quirks or issues."

I've updated my guide Install Asdf Version Manager for Ruby users that will provide the details in case users don't check the asdf documentation.

Thanks for all your efforts on development and maintenance! It's a great project but I'm sure it can be frustrating at times :-)

[jthegedus]

@seivan I still intend to look at your improvements for Homebrew

[Stratus3D]

Sorry for the late response here, but to answer a question from a while back in this thread:

More importantly, why isnt /asdf.sh part of the bin/asdf.sh directly?

I don't know the answer to that, @Stratus3D probably does.

It seems to me, and I could be wrong that it just modifies $PATH

Yes, the reason that code can't live in bin/asdf is because it needs to be sourced in the shell and not executed as a command because it needs to add shims and the asdf bin path to $PATH.

[jthegedus]

As an update, there's an alternate Homebrew asdf update going on in Homebrew/homebrew-core#81664 whereby the author disagress with the solution proposed in Homebrew/homebrew-core#73173 which this is paired with. See my comments there.

[Dentrax]

Getting same issue after brew upgrade:

$ asdf

cat: /usr/local/VERSION: No such file or directory
version:

cat: /usr/local/help.txt: No such file or directory

"Late but latest"
-- Rajinikanth

[carlocab]

I think Homebrew/homebrew-core#81664 is ready to merge, but I'd appreciate more feedback from asdf users.

I don't think there should be any breaking changes, but the asdf docs could probably be updated.

CC @seivan @DanielKehoe @Dentrax

[dakhipp]

Thanks to @seivan, I was able to get things to work again. Here are the steps it took in case anyone else finds it useful.

I used brew to update asdf from v0.10.^ to v0.11.^, after which I was getting an error about $(brew --prefix asdf)/asdf.sh not existing (this comes from a line in my ~/.bash_profile). I found that I had to update to $(brew --prefix asdf)/libexec/asdf.sh. (Note the /libexec/ change)

After that, I was getting a lot of errors mentioning files not existing in ~/.asdf. They mentioned my previous version of asdf v0.10.^. Finally, I ran this from @seivan's comment rm -rf ~/.asdf/shims; asdf reshim. Now things work as expected again.