Linux Installation Issues and Insights

[flu0r1ne]

I was aiming to setup install hooks to automatically register completion scripts during the pip install. I don't know if there was a design decision to explicitly avoid this pattern. (E.g. this modifies files outside of the purview of pip and should be managed by the distribution or the end user.)

Regardless, I first started with the more basic task of getting global registration to work reliably. I haven't been successful, but I wanted to share some insights:

1. On many Linux distributions installing a package with pip drops it into ~/.local/bin/. Of course, you cannot run activate-global-python-argcomplete as root since it won't be found in the path. (Neither should you since the script will not be able to find the argcomplete module.) Thus, the default instructions will not work for these users:

Installation
------------
::

    pip install argcomplete
    activate-global-python-argcomplete

On Linux, you will need to run the second command with ``sudo``. See `Activating global completion`_ below for details.

Instead, you need to install the package globally or preferentially install it with your system's package manage. I think the recommendation here would be "set up local completion" or "consult your distro's package manager." Some distro's versions are outdated and I couldn't find any documentation regarding potential incompatibilities of versions 2.x and 3.x. Are client programs written for 3.x compatible with the global registration scripts written by the 2.x version?

2. The default install location /etc/bash_completion.d seems to be outdated. Ubuntu seems to have deprecated it. arch did not have it.

Quoting from the bash-completion documentation:

Directory for pre-dynamic loading era (pre-2.0) and other backwards
compatibility completion files that are loaded eagerly from bash_completion
when it is loaded. If unset or null, the default compatibility directories to
use are /etc/bash_completion.d, and bash_completion.d relative to
bash_completion location.

Now, they recommend scripts be installed in /usr/share/bash-completion/bash_completion. I don't know if this is an intentional "early-loading" bypass. If not, it might be best to change the default location. If so, it might be best to add a note to the documentation and create /etc/bash_completion.d if it does not exist.

3. I found the internal tool python -m argcomplete._check_console_script "$(which app)" useful for determining if argcomplete is able to find the PYTHON_ARGCOMPLETE_OK tag. This isn't documented. It seems that python-argcomplete-check-easy-install-script is still installed by default. This is misleading because it seems that the pip replacement for easy install does not insert the EASY-INSTALL-SCRIPT markers. Thus, it produces a false negative.

I would be happy to work with you to update the documentation or install scripts if needed!

[kislyuk]

Thanks for writing this up, you have a lot of good insights and you point out some real ergonomics problems with the package. I agree the docs should be updated to clarify the difference between operating argcomplete as root vs. as the user. The package does not install anything outside its installation directory in the course of initial installation; as you correctly pointed out this is because packages are generally not expected to do this, and violating the "principle of least surprise" in this way can cause a variety of issues, including a failure to install the package and its reverse dependencies altogether.

The pre-dynamic loading bash-completion directory is used because unfortunately, there is no way to hook a complete -D script into the bash-completion 2.0 infrastructure, and that is required for global completion activation. If the directory does not exist, the installation script prints a message asking the user to troubleshoot this, but I agree it could be made clearer that the directory needs to be created. We could, in theory, look into switching targeted argcomplete activation (register-python-argcomplete) to use the bash-completion 2.0 framework.

The internal tool is not documented because it's internal :)

You bring up other good points - this is just to acknowledge and thank you for that and to request patience - it may take me a while longer to get to addressing this. PRs are welcome.

[flu0r1ne]

Sorry for the late follow up - I'm planning to take a look at this tomorrow. Will see what I can do.

[flu0r1ne]

This was a bit of a project. I'm going to treat this as an umbrella issue:

• Missing /etc/bash_completion.d causes bad Linux install #430 Fixes the issue I originally encountered when I posted the message
• ZSH Global Completion Issues on Ubuntu 22.04 #432 Fixes some unrelated issues with global completion on ZSH post-installation

I will follow up with a docs update soon.