macOS dotnet CLI path for global tools is bad - Installer issue

[jrdodds]

Describe the bug

On macOS when a .Net tool is installed globally, it will not be found in the PATH.

The dotnet installer does attempt to make the directory for globally installed tools part of the PATH, but the mechanism the installer is relying on doesn't work as the installer apparently expects.

To Reproduce

1. Install dotnet on macOS using the Microsoft Installer from https://dotnet.microsoft.com/en-us/download.
2. Install a tool globally, e.g. dotnet tool install -g Microsoft.dotnet-httprepl
3. Assuming zsh which is the default shell on macOS (Catalina and newer), run the command which httprepl
4. The output of the which command will be "httprepl not found" indicating that the httprepl tool can’t be found in the PATH.

Further technical details

Why does this happen?

macOS has a mechanism for adding paths to the PATH environment variable. The files in /etc/paths.d are used by the path_helper tool to build up the PATH environment variable.

The installer for dotnet is adding two files for paths:

• /etc/paths.d/dotnet
• /etc/paths.d/dotnet-cli-tools

The dotnet file contains

/usr/local/share/dotnet

The dotnet-cli-tools file contains

~/.dotnet/tools

However, paths in these files should be literal. The tilde (~) is not expanded to be the current user home directory. Environment variable references are also not expanded.

bash

The default standard shell on macOS Catalina (released in 2019) and newer is zsh. Prior to Catalina the default standard shell was bash. The bash shell appears to expand the tilde at a later point for an interactive shell so this issue may not manifest for bash users. However, the files created in /etc/paths.d by the dotnet installer need to support all shells.

Can't Specify the Current User Home Directory

The tilde can't be expected to be expanded to be the current user home directory. ${HOME} also can’t be used. There is not a way to specify the current user home directory in a file in /etc/paths.d.

I don’t know if not supporting the current user home directory is by design or is an omission.

Given the current functionality, the dotnet installer should not create the /etc/paths.d/dotnet-cli-tools file at all.

Workaround for Individual Users

In the .profile file, the user can either add the following line to add the needed path:

# dotnet-cli-tools
export PATH=$PATH:~/.dotnet/tools

or, assuming the bad path exists in the PATH, add the following ‘fix-up’ to replace any tildes in the PATH (equivalent to bash):

export PATH=${PATH//\~/$HOME}

The .zprofile may be set to source the .profile file with the following line:

[[ -e ~/.profile ]] && emulate sh -c 'source ~/.profile'

[jrdodds]

see also
#22588
#22214

[baronfel]

Thanks @jrdodds, this is the definitive summary of the MacOS issues.

I agree that we should not set any paths on /etc/paths.d that are user-specific.

If we want to maintain automatic PATH modification, then I agree that the best path for the installer going forward would be to add a $HOME-based path, but I after reading this post I think modifying the user's .zshrc is the appropriate place for it. And then there are other concerns we'll need to tackle as well - what if the user has set another shell? We'll need to have a fallback that informs the user that the dotnet tools path isn't in PATH, and that fallback sounds like modifications to the dotnet CLI's output to me.

[jrdodds]

Hi @baronfel, The installer should ask before modifying the user's .zshrc file or any of the other shell configuration files. It's very bad etiquette to silently modify any of these files. (That's part of the reason for the path_helper.)

The post that you reference leaves out the $HOME/.zprofile file which is read before the .zshrc file. (See Order of execution and purpose of .profile vs .zshrc)

The installer could test for the running shell (by checking the $SHELL env var) and could modify the appropriate .*profile file (or .*rc file). That doesn't solve the case where the user switches shells or where the user is interactively running one shell and writing shell scripts in another shell. For lowest common denominator compatibility, scripts are often written to use the Bourne shell (sh).

The .profile file is for the Bourne shell and it's common to share across shells via the .profile file but that is behavior that must be configured.

You might consider the example of HomeBrew. The brew command has a shellenv argument. A dotnet shellenv that is eval'd could return an export line to add the tools directory to the PATH if ~/.dotnet/tools is not already in the PATH. If the eval command is added to multiple shell configuration files that are read in the same session, the directory won't be duplicated in PATH.

Thanks

[baronfel]

You might consider the example of HomeBrew. The brew command has a shellenv argument. A dotnet shellenv that is eval'd could return an export line to add the tools directory to the PATH if ~/.dotnet/tools is not already in the PATH. If the eval command is added to multiple shell configuration files that are read in the same session, the directory won't be duplicated in PATH.

This is my preferred solution, and what I was meaning by a reference to new work in the CLI. Thanks for the additional links about the order of execution, I'll check them out 👍

[kazo0]

Just a bump, I am still experiencing this issue

[cicorias]

be great to get an update as just had a team of folks run through this on their Macs.

[ssbarnea]

I am amazed how this ended up being implemented because it is well known that user of tilde (~) is invalid inside PATH environments. While most shells will accept and expand the ~, many tools will break. Tilde should never be part of PATH.

[cert01]

This "~" was causing all manner of mischief for me by simply existing in my $PATH.
Rather than add the "export PATH=${PATH//~/$HOME}" to the user .zshrc, I Modified the /etc/paths.d/dotnet-cli-tools file to fix it until package resolution comes down the pipeline.

# MACOS zsh  >
brew info dotnet-sdk
#    ==> dotnet-sdk: 7.0.101,ea9de698-864c-4ddb-8ff3-1bf068c6b1a7,cf5d147f2c167317394058deb4d4b0a7
#    https://www.microsoft.com/net/core#macos
#    /opt/homebrew/Caskroom/dotnet-sdk/7.0.101,ea9de698-864c-4ddb-8ff3-1bf068c6b1a7,cf5d147f2c167317394058deb4d4b0a7 (179.1MB)
#    From: https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/dotnet-sdk.rb
#    ==> Name
#    .NET SDK
#    ==> Description
#    Developer platform
#    ==> Artifacts
#    dotnet-sdk-7.0.101-osx-arm64.pkg (Pkg)
#    /usr/local/share/dotnet/dotnet (Binary)
#    ==> Analytics
#    install: 2,069 (30 days), 6,115 (90 days), 23,319 (365 days)
# MACOS zsh  >
sw_vers
#    ProductName:		macOS
#    ProductVersion:		13.0.1
#    BuildVersion:		22A400
#  MACOS zsh  >
cat /etc/paths.d/dotnet-cli-tools
~/.dotnet/tools%

Note: the % shows unterminated line in file

# MACOS zsh  >
[[ $PATH = *~/.dotnet/tool* ]] && export PATH=${PATH//\~/$HOME}
echo "\$HOME/.dotnet/tools" | sudo tee /etc/paths.d/dotnet-cli-tools