Incorrect file location in suggested zsh autocompletion setup command on Manjaro

[tarlacac]

Apologies in advance, I am not a Go developer so I don't have a great understanding of the implementation details (this is my first time actually looking at code in the language!).

Did you look for related issues?

I did not find anything specifically discussing this, but I found another issue recommending the command that is not working for me (#1165, but the link to the instructions they followed does not exist anymore), a similar issue on an M1 mac (#1589), an issue discussing incorrect zsh configuration inhibiting their completions (#1534), an older issue about a different command for zsh completion (#1529), and a few others that were less relevant about zsh completions.

Describe the bug

The zsh completion generation help message does not work to load completions for every new session on Manjaro Linux (and I'm guessing Arch Linux, too). This appears to be because ${fpath[1]} defaults to /usr/local/share/zsh/site-functions, but that directory does not exist. Instead, /usr/share/zsh/site-functions is being used, which appears to be the default location from inspecting the PKGBUILD files for extra/zsh and extra/zsh-completions, and is the value of ${fpath[2]}.

To Reproduce

Steps to reproduce the behavior:

1. On Manjaro, in a terminal, run a program with the default completion command (I was using fan2go when I found this) to get the instructions:

<program> completion zsh --help

3. Following the instructions for Linux, run <program> completion zsh > "${fpath[1]}/_<program>"
4. See error:

% <program> completion zsh > "${fpath[1]}/_<program>"
zsh: no such file or directory: /usr/local/share/zsh/site-functions/_<program>

5. Verify /usr/local/share/zsh does not exist:

% ls /usr/local/share/zsh
ls: cannot access '/usr/local/share/zsh': No such file or directory

6. Verify /usr/share/zsh exists:

% ls /usr/share/zsh
5.9/	    manjaro-zsh-config	p10k-portable.zsh  plugins/  site-functions/
functions/  manjaro-zsh-prompt	p10k.zsh	   scripts/  zsh-maia-prompt

Expected behavior
My zsh site-functions directory is /usr/share/zsh/site-functions, so I would expect the recommended command to use that directory. Alternatively, it would be nice to have a note warning that the location might be /usr/share/zsh/site-functions instead of /usr/local/share/zsh/site-functions.

Desktop (please complete the following information):

• Distro: Manjaro
• uname -a: Linux <hostname> 6.6.54-2-MANJARO #1 SMP PREEMPT_DYNAMIC Tue Oct 8 03:11:08 UTC 2024 x86_64 GNU/Linux
• zsh --version: zsh 5.9 (x86_64-pc-linux-gnu)

Additional context

I am coming from fan2go, where I submitted an issue and was told this particular help command output was generated by cobra. I do know that they are using the latest version of cobra (v1.8.1 at the time of writing), and I could not find custom code for this subcommand, so I believe the help message was generated by cobra.

As far as I know, I have not done any configuration to zsh except a few p10k configure calls for the theme. From some brief searching, it appears that zsh using either /usr/share or /usr/local/share varies based on Linux distro. It is possible that zsh is misconfigured somewhere as well, but I couldn't find anything configuring fpath to use these defaults on my system.

[marckhouzam]

Thanks @tarlacac for the report.
As you pointed out, cobra mentions to put the zsh completion script under ${fpath[1]}.
The zsh shell looks for completion scripts by looking in the different paths specified by the variable ${fpath} (and it may also look in some default locations, I don’t recall for sure).

The fact that your ${fpath[1]} is incorrect seems to be that your zsh setup is incorrect for Manjaro. You could set that variable yourself in your .zshrc file.

[tarlacac]

Thanks for the quick response @marckhouzam! You're right that this is an easy fix on my end; I actually just ran the suggested command with ${fpath[2]} instead since /usr/share/zsh/site-functions was the value for ${fpath[2]}. I'll probably take your suggestion and apply a fix for the fpath variable in my ~/.zshrc file, too.

After hours of digging through my file system, Manjaro forums, and the zsh manual, I don't think this is a misconfiguration on my part anymore, unfortunately. This seems to be a Manjaro issue, or deeper, since I just downloaded the latest minimal Manjaro Gnome ISO (24.1.2) and the fpath issue I described was present when I booted into that as well. It has been an issue for a few major releases of Manjaro, at least, since it is also present in my older 22.0.4 ISO.

I suppose the purpose of this issue shifts a bit based on that information: The problem is the same, but for now this issue likely should just serve as an informative piece for anyone else encountering the issue. I'll ask over at Manjaro's forums (linking to it here when I do) to see if it is something they are aware of, or if I get punted further down the dependency chain. It may still be worth adding a note about this potential issue in the help command output if this turns out to be a broader issue than just one Linux distro (although my understanding is that Manjaro is one of the most popular distros lately). (See my next message)

As you pointed out, cobra mentions to put the zsh completion script under ${fpath[1]}.

I do have to give a little push-back here on wording. The way I read it, the cobra zsh completion help message doesn't mention to put the completion script under ${fpath[1]}. It instructs the user to run a command that it claims should do it for you when executed. However, the provided Linux command does not work with at least one major distribution, with no hints to the user on how the command may need to be modified on different distributions.

[tarlacac]

Apologies, I realized a place I haven't looked for a solution yet: reading through the compile instructions and source code for zsh. This brought me to their changelog, where I found the default fpath info I've been looking for! I have learned a lot in the last few days through researching this...

Back in 2014 with zsh 5.0.7, it appears that the default fpath was changed so /usr/local/share/zsh/site-functions is always prepended, regardless of whether the path exists, if no explicit site function directory is set. (see https://zsh.sourceforge.io/releases.html, "Changes between versions 5.0.6 and 5.0.7", bullet 2 and https://sourceforge.net/p/zsh/code/ci/master/tree/ChangeLog, search for "33212") Essentially, your recommended command only works for zsh with the default install prefix, or if the modified installation accounts for this by setting a site directory or ensuring that /usr/local/share/zsh/site-functions also exists.

Since zsh explicitly documents that /usr/local/share/zsh/site-functions does not need to exist to be prepended to fpath, I would interpret the current Arch Linux zsh package and any other builds that leave a nonexistant /usr/local/share/zsh/site-functions at the front of fpath to still be proper. I think this moves the issue back here with the recommended help command, where the existence of the directory at ${fpath[1]} cannot be guaranteed, causing an undocumented/unhandled error case. Knowing that this isn't a configuration issue on my end or an issue with zsh, Manjaro, or Arch, I think this is a decent argument for adding a note that ${fpath[1]} may not exist for all zsh installations (maybe recommend ${fpath[2]} if it doesn't exist?), or reconsidering the recommended command (although I still don't know what that would look like). Since the recommended command conflicts with the official Arch Linux zsh package, this issue likely now applies to Arch Linux and all Arch-derived distros, too.