fndir introspection, site-packages documentation

fndir introspection, site-packages documentation

[Roman Neuhauser]

hello,

is there a way to get at the value "fndir" ended up having in configure?
this would be useful in function packaging. i know
/usr/local/share/zsh/site-functions is always used (had to dig, it's not
documented!) but that is not going to please Linux distros, which
generally use --prefix=/usr.  i would like to be able to do something
like

  sitefndir=$(zsh -c 'print "$ZSHSITEFNDIR"')

a simple Makefile should be able to do the right thing on any operating
system or exotic configuration without user intervention (in this case).

apropos!

there's a *single* occurrence of "site-functions" in zshall(1), a passing
reference coming from the zsh/newuser description in zshmodules(1) of all
places:

       If none of the start-up files were found, the module then looks
       for the file newuser first in a sitewide directory, usually the
       parent  directory  of the site-functions directory, and if that
       is not found the module searches [...]

the configure-time fndir should be mentioned in the $fpath/$FPATH
description in zshparam(1), and this bullet from NEWS absolutely needs
to be there as well:

- The default $fpath/$FPATH is now designed always to include
  /usr/local/share/zsh/site-functions.  This directory does not need to
  exist.  Sites that set an explicit site directory can put that in
  /etc/zshenv as before.  The intention of the new path element is to
  increase the likelihood that locally added functions can be found with
  the shell running "out of the box", no matter how the shell was
  configured.

-- 
roman

Re: fndir introspection, site-packages documentation

[Bart Schaefer]

On Mar 13, 11:41pm, Roman Neuhauser wrote:
}
} is there a way to get at the value "fndir" ended up having in configure?

Sort of.  The trouble is that if --enable-function-subdirs has been used
for configure, there isn't really a useful scalar value of fndir, you
have to have the whole $fpath array.

If you ignore that complication, you can do

    sitefndir=$(zsh -fc 'case $#fpath in \
	(1) print $fpath;; (2) print $fpath[2];;
	(*) print $fpath[2]:h;; esac')

} apropos!
} 
} there's a *single* occurrence of "site-functions" in zshall(1)

Yes, see complications above ... it's nearly impossible to know what to
refer to in the doc when you allow the packager to relocate things to
anywhere (or a whole list of anywheres) that he wants.

An end user isn't supposed to need to know about site-functions (even the
mention under zsh/newuser is more for the administrator installing the
newuser function than for the user invoking it).  The user just needs
to refer to what shows up in the default $fpath, and know that he can add
his own directories to it.

I suppose ideally we'd have a separate doc section for adminstrative
miscellany.

Re: fndir introspection, site-packages documentation

[Roman Neuhauser]

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

# schaefer@brasslantern.com / 2015-03-13 20:39:04 -0700:
> On Mar 13, 11:41pm, Roman Neuhauser wrote:
> }
> } is there a way to get at the value "fndir" ended up having in configure?
> 
> Sort of.  The trouble is that if --enable-function-subdirs has been used
> for configure, there isn't really a useful scalar value of fndir, you
> have to have the whole $fpath array.

uh, sorry, i meant "sitefndir".  anyway, how about the attached patch?

  ./Src/zsh -fc 'print -l "$ZSH_SITEFNDIR"'     
  /omg/share/zsh/site-functions

-- 
roman

[-- Attachment #2: 0001-ZSH_SITEFNDIR-exposes-the-path-to-site-functions.patch --]
[-- Type: text/x-diff, Size: 4110 bytes --]

>From e6949cebd4e8d78685071e42e58b0693d5699359 Mon Sep 17 00:00:00 2001
From: Roman Neuhauser <neuhauser@sigpipe.cz>
Date: Sun, 15 Mar 2015 03:18:26 +0100
Subject: [PATCH] $ZSH_SITEFNDIR exposes the path to site-functions

---
 Doc/Zsh/params.yo | 35 +++++++++++++++++++++++++++++++----
 NEWS              |  2 ++
 Src/params.c      | 15 +++++++++++++++
 3 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo
index 2f78920..2ad2489 100644
--- a/Doc/Zsh/params.yo
+++ b/Doc/Zsh/params.yo
@@ -929,6 +929,14 @@ item(tt(zsh_scheduled_events))(
 See ifzman(the section `The zsh/sched Module' in zmanref(zshmodules))\
 ifnzman(noderef(The zsh/sched Module)).
 )
+vindex(ZSH_SITEFNDIR)
+item(tt(ZSH_SITEFNDIR))(
+Installation directory for site-specific, non-version-specific functions.
+Zsh sets it to var(prefix)tt(/share/zsh/site-functions), or
+tt(/usr/local/share/zsh/site-functions) if it was configured with
+tt(--disable-site-fndir).
+Included in tt($fpath)/tt($FPATH).
+)
 vindex(ZSH_SUBSHELL <S>)
 item(tt(ZSH_SUBSHELL))(
 Readonly integer.  Initially zero, incremented each time the shell forks
@@ -1041,10 +1049,29 @@ vindex(fpath)
 vindex(FPATH)
 item(tt(fpath) <S> <Z> (tt(FPATH) <S>))(
 An array (colon separated list)
-of directories specifying the search path for
-function definitions.  This path is searched when a function
-with the tt(-u) attribute is referenced.  If an executable
-file is found, then it is read and executed in the current environment.
+of directories specifying the search path for definitions of autoloaded
+functions.  See the tt(autoload) builtin in
+ifzman(zmanref(zshbuiltins))\
+ifnzman(noderef(Shell Builtin Commands)),
+and
+ifzman(em(Autloading Functions) in zmanref(zshmisc))\
+ifnzman(noderef(Autloading Functions)).
+On startup, zsh sets this to one or more directories depending on
+the way it was configured.
+Default configuration leads to these values:
+tt(/usr/local/share/zsh/site-functions) followed by
+var(prefix)tt(/share/zsh/site-functions)
+(unless var(prefix) is tt(/usr/local)), followed by a list of
+var(prefix)tt(/share/zsh/$ZSH_VERSION/functions) subdirectories.
+Default var(prefix) is tt(/usr/local).
+tt(/usr/local/share/zsh/site-functions) is always included,
+even if it does not exist, and cannot be configured away.
+This is to increase the likelihood that locally added functions
+can be found with the shell running "out of the box", no matter how
+the shell was configured.
+
+If an executable file is found, then it is read and executed
+in the current environment.
 )
 vindex(histchars)
 item(tt(histchars) <S>)(
diff --git a/NEWS b/NEWS
index bf8969b..d1949be 100644
--- a/NEWS
+++ b/NEWS
@@ -114,6 +114,8 @@ Changes since 5.0.0
   Running fn writes "hello" to logfile.  In older versions of the shell
   it would create an empty file at the point of definition.
 
+- $ZSH_SITEFNDIR exposes the path to site-functions.
+
 Changes between 4.2 and 5.0.0
 -----------------------------
 
diff --git a/Src/params.c b/Src/params.c
index e8a9010..2a71e19 100644
--- a/Src/params.c
+++ b/Src/params.c
@@ -30,6 +30,8 @@
 #include "zsh.mdh"
 #include "params.pro"
 
+#include "zshpaths.h"
+
 #include "version.h"
 #ifdef CUSTOM_PATCHLEVEL
 #define ZSH_PATCHLEVEL	CUSTOM_PATCHLEVEL
@@ -684,6 +686,9 @@ createparamtable(void)
     struct utsname unamebuf;
     char *machinebuf;
 #endif
+#if defined(SITEFPATH_DIR) || defined(FIXED_FPATH_DIR)
+    const char *sitefpathdir;
+#endif
 
     paramtab = realparamtab = newparamtable(151, "paramtab");
 
@@ -807,6 +812,16 @@ createparamtable(void)
 #else
     setsparam("CPUTYPE", ztrdup_metafy("unknown"));
 #endif
+
+#if defined(SITEFPATH_DIR) || defined(FIXED_FPATH_DIR)
+# ifdef SITEFPATH_DIR
+    sitefpathdir = ztrdup_metafy(SITEFPATH_DIR);
+# else
+    sitefpathdir = ztrdup_metafy(FIXED_FPATH_DIR);
+# endif
+    setsparam("ZSH_SITEFNDIR", ztrdup_metafy(sitefpathdir));
+#endif
+
     setsparam("MACHTYPE", ztrdup_metafy(MACHTYPE));
     setsparam("OSTYPE", ztrdup_metafy(OSTYPE));
     setsparam("TTY", ztrdup_metafy(ttystrname));
-- 
2.3.2

Re: fndir introspection, site-packages documentation

[Bart Schaefer]

This really doesn't belong on zsh-users any more, in fact it probaby should
have started out on zsh-workers to begin with.  I haven't changed the list
target yet for this reply, but I suggest follow-ups go there.

Aside:  I don't suppose there's any point in again begging people to stop
attaching patches as "text/x-patch" or "text/x-diff" or other silly MIME
types that half my email clients say there is no app for, and the other
half pass to some miscelleneous (wrong) app because of the ".patch" file
extension, which someone seems to think has something to do with setting
up network tunnels.

Grumble.  Text bleeping plain, or just put them in the message body.

I suppose I should also rant about email client authors who don't have
a "text/*" fallback.  Rant rant.  We now return you to your regularly
scheduled curmudgeonry.

On Mar 15,  3:14am, Roman Neuhauser wrote:
}
} uh, sorry, i meant "sitefndir".  anyway, how about the attached patch?

Indeed, I should have gotten that from your example instead of answering
the literal question.

}   ./Src/zsh -fc 'print -l "$ZSH_SITEFNDIR"'     
}   /omg/share/zsh/site-functions

I don't have any strong objection to this although it seems like putting
this value into every shell is overkill for the specialized purpose to
which you propose to use it.  Can anyone give me a situation in which an
oridinary user (i.e., not a software packager) would need this?

If there *is* such a situation, then the parameter name should be a lot
less configure-script-ified, "SITEFNDIR" is rather meaningless in any
other context.

Your doc change mentions

+tt(/usr/local/share/zsh/site-functions) is always included,
+even if it does not exist, and cannot be configured away.

That's not quite correct: --disable-site-fndir turns it off, leaving
only $prefix/share/zsh/$ZSH_VERSION/functions (or subdirs).

Also it's bad form in the doc to use references like var(prefix) when
you haven't mentioned where the value of prefix comes from, which in
turn requires delving into discussion of build configuration, which
is out of scope for end-user doc, which is another reason we haven't
included these details before.

(There are some parts of the doc where we try to actually pull in the
configuration values and embed them, so that we don't have to make
references to configure variables, but that gets ugly.)

Maybe the right thing is to throw all of this into a module (and doc
for that module) that can be loaded by package maintainers to provide
access to zsh's configure settings, but which other users can ignore.
The more I think about it the more I like that idea.

patches format Re: fndir introspection, site-packages documentation

[Daniel Shahaf]

Bart Schaefer wrote on Sun, Mar 15, 2015 at 12:14:47 -0700:
> Aside:  I don't suppose there's any point in again begging people to stop
> attaching patches as "text/x-patch" or "text/x-diff" or other silly MIME
> types that half my email clients say there is no app for, and the other
> half pass to some miscelleneous (wrong) app because of the ".patch" file
> extension, which someone seems to think has something to do with setting
> up network tunnels.
> 
> Grumble.  Text bleeping plain, or just put them in the message body.
> 

I wouldn't advise people to put patches in the body, since most mail
clients auto-wrap and strip leading/trailing whtiespace by default
(which corrupts empty context lines).  Instead, I usually advise people
to attach patches as a file named *.txt.  That filename pattern usually
results in text/plain attachments.

> I suppose I should also rant about email client authors who don't have
> a "text/*" fallback.  Rant rant.  We now return you to your regularly
> scheduled curmudgeonry.

Re: patches format Re: fndir introspection, site-packages documentation

[Peter Stephenson]

On Mon, 16 Mar 2015 09:36:24 +0000
Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> Bart Schaefer wrote on Sun, Mar 15, 2015 at 12:14:47 -0700:
> I wouldn't advise people to put patches in the body, since most mail
> clients auto-wrap and strip leading/trailing whtiespace by default
> (which corrupts empty context lines).  Instead, I usually advise people
> to attach patches as a file named *.txt.  That filename pattern usually
> results in text/plain attachments.

I think it's a question of "know thy mailer".  Some mailers (I use
claws-mail but there are plenty of others) are deliberately designed to
do the least possible to the mail body, and if you want to spend you
life sending patches you can seek out one such.  But if you don't
normally send patches that's good advice.

pws