How does a new software package provide Zsh tab completion scripts to users?

How does a new software package provide Zsh tab completion scripts to users?

[Robert McLay]

[-- Attachment #1: Type: text/plain, Size: 1366 bytes --]

I am the author of a software package and I'd like to provide Zsh tab
completion scripts for users of my package.   In particular my package is
Lmod.  It is updated tool to handle environment modules, similar to but not
exactly the same as the TCL/C based environment modules.  Its main
advantage is that makes dealing with multiple compilers and MPI stacks much
easier along with the dependent libraries and applications.

The problem is that Lmod is typically installed by system administrators
and not by users directly.   There is not a good way to tell the Zsh users
that there is tab completion scripts available.    I also do not think that
I'll get many site to put my zsh scripts in the system location.
Eventually if/when Lmod takes over the world (;->),  my completion scripts
will be in the standard zsh installation but until that day,  I'd like to
know what options are available.

To use Lmod, users must source something that defines a shell function.  In
this file, I could also prepend a directory to FPATH and do

    autoload -U compinit
    compinit -C

to make the Lmod completion available.  However  this seems like a bad
idea.  What if a Zsh user is not using tab completion?


Has this been discussed before?   I did some searching but was unable to
find anything.  I'm not sure what the right phrase would be.

Thanks for any thoughts,
R.

Re: How does a new software package provide Zsh tab completion scripts to users?

[Phil Pennock]

On 2013-04-23 at 16:21 -0500, Robert McLay wrote:
> I am the author of a software package and I'd like to provide Zsh tab
> completion scripts for users of my package.

Option 1: get added to zsh
  Upsides:
    * always available
  Downsides:
    * only available by default with new versions
    * decoupled from the version actually installed
  Summary:
    * works best when API is stable and you're able/willing to let
      others handle maintenance

For the rest of this, I'll assume you don't want to just supply the
completion for inclusion with zsh, but it's probably still the best
option for you.

What should typically happen is that the OS build of zsh uses
`./configure --site-fndir=...` to supply some directory which collects
packages/other scripts, which will result in the default $FPATH/$fpath
in zsh having an extra directory to check.

Option 2: include in a contrib/ or misc/ directory, document
  Upsides:
    * You maintain complete control
    * Can vary incompatibly
  Downsides:
    * Needs you to communicate clearly to packagers that there's a file
      they should drop into the zsh site function directory (perhaps via
      symlink)
    * You need to figure out how far back in zsh terms you want to be
      compatible and write portable zsh; for common features, this
      shouldn't be an issue, but it's worth remembering that you can't
      just use whatever facilities are added to make life easier for
      you, whereas those who get the functions added to zsh can

Eg, on FreeBSD, the portupgrade tool just unilaterally installs the file
share/zsh/site-functions/_pkgtools (relative to the install-base) and if
zsh is installed, before or after, then the extra completions just
become available.

Option 3: user installation, no control of zsh or system install
  Upsides:
    * no coordination with anyone but user
  Downsides:
    * coordination with end users

Tell people to link to the file inside an element of $fpath which they
control and to do so before starting completion configuration.  Tell
them that this won't be necessary with appropriate system configuration,
link to the document explaining how to get the completion set up in
system directories, let the users buy the sysadmins beer until the local
installs are fixed.


A little more seriously: there's a decision tree:

  1: Does user admin their own system?

  1=Yes:
    2: Is user an experienced Unix user?
      2=No: User should be using package management (option 2)
      2=Yes: User should be using package management (option 2)
             but they have a fallback to option 3

  1=No:
    3: Are there sysadmins?
      3=Yes: Option 2 applies, the persuasion mentioned above
      3=No: give up, they're doomed

Re: How does a new software package provide Zsh tab completion scripts to users?

[Peter Stephenson]

On Tue, 23 Apr 2013 16:21:59 -0500
Robert McLay <mclay@tacc.utexas.edu> wrote:
> I am the author of a software package and I'd like to provide Zsh tab
> completion scripts for users of my package.   In particular my package is
> Lmod.  It is updated tool to handle environment modules, similar to but not
> exactly the same as the TCL/C based environment modules.  Its main
> advantage is that makes dealing with multiple compilers and MPI stacks much
> easier along with the dependent libraries and applications.
> 
> The problem is that Lmod is typically installed by system administrators
> and not by users directly.   There is not a good way to tell the Zsh users
> that there is tab completion scripts available.    I also do not think that
> I'll get many site to put my zsh scripts in the system location.
> Eventually if/when Lmod takes over the world (;->),  my completion scripts
> will be in the standard zsh installation but until that day,  I'd like to
> know what options are available.

Phil gave a fairly full answer, but here's a simple reply to that
specific question...  Obviously, the key to avoiding clashes is having a
function name that's as likely to be unique as possible.  To make the
function available, it needs to be somewhere in the function path, and
the site function directory is the obvious one because it's designed to
be a standard place to put functions supplied by the local
administrator.  However, it depends how zsh was configured.  Assuming
it's been configured in a fairly standard manner, and the local
/etc/zshenv isn't doing something it shouldn't, your installation
programme could do:

zshfndir="`zsh -fc 'print -l $fpath' | grep site-functions | head -1`"

and use that directory to install your function.  That does the basics;
then you have to worry about more sophisticated things such as
non-standard zsh configurations, whether you're going to be smart
enough to uninstall it, whether you're going to look for your completion
function elsewhere in the path, and whatever paranoia occurs to you.

Putting the file in the right place should be most of the battle
(apart from what you noted next), since the #comdpef lines for
files in the function path are scanned automatically.

> To use Lmod, users must source something that defines a shell function.  In
> this file, I could also prepend a directory to FPATH and do
> 
>     autoload -U compinit
>     compinit -C
> 
> to make the Lmod completion available.  However  this seems like a bad
> idea.  What if a Zsh user is not using tab completion?

I tend to agree; it can take a while to start up as well, and it hooks
in various shell modules providing parameters in the main name space, so
it's not entirely without side effects.  I think at this level the user
has to make a decision, and you have to tell the user that zsh
completion is available if they want to use it.

> Has this been discussed before?   I did some searching but was unable to
> find anything.  I'm not sure what the right phrase would be.

Things like this have come up, though as you say it's kind of hard to
search for.  I don't think there was any grand conclusion beyond "there
are ways of doing this".

If there's a killer argument for one way of doing it, we could certainly
add support in the shell distribution to make it easier --- though
having said that you'd almost certainly want something that worked
with older versions of the shell.

-- 
Peter Stephenson <p.stephenson@samsung.com>       Principal Software
Engineer Tel: +44 (0)1223 434724              Samsung Cambridge
Solution Centre St John's House, St John's Innovation Park,
Cowley Road, Cambridge, CB4 0DS, UK

Re: How does a new software package provide Zsh tab completion scripts to users?

[Valodim Skywalker]

[-- Attachment #1: Type: text/plain, Size: 497 bytes --]

Option 3.5, very low overhead but user-dependent:
Submit your completion to https://github.com/zsh-users/zsh-completions

Like the others, this is not an optimal solutoin, but a lot of
frameworks include this repository in their fpath, and a lot of users do
as well, so this will get pretty much everyone with a configuration more
complex than zsh-newuser-install.

To cover a maximum number of use cases, you could always go for multiple
options, 1+3.5 sounds like a good candidate to me.

 - V


[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]