zsh-workers/9947

2 files changed, 66 insertions, 4 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index a46ec0f92..3491c8591 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -1283,6 +1283,55 @@ findex(which)
 item(tt(which) [ tt(-wpams) ] var(name) ...)(
 Equivalent to tt(whence -c).
 )
+findex(zcompile)
+cindex(wordcode, creation)
+cindex(compilation)
+xitem(tt(zcompile) [ tt(-U) ] [ tt(-r) | tt(-m) ] var(file) [ var(function) ... ])
+item(tt(zcompile -t) var(file) [ var(name) ... ])(
+This builtin command can be used to create and display files
+containing the wordcode for functions. In the first form, a wordcode
+file is created. If called with only the var(file) argument, the
+wordcode file has the name `var(file)tt(.zwc)' and will be placed in
+the same directory as the var(file). This will make the wordcode file
+be loaded instead of the normal function file when the function is
+autoloaded (see
+ifzman(\
+the section `Autoloading Functions' in zmanref(zshfunc)
+)\
+ifnzman(\
+noderef(Functions)
+)
+for a description of how autoloaded functions are searched).
+
+If there is at least one var(function) argument, the wordcode for all
+these functions will be put in the created wordcode var(file). Such
+files containing the code for multiple functions are intended to be
+used as elements of the tt(FPATH)/tt(fpath) special array.
+
+If the tt(-U) option is given, aliases in the var(function)s will not
+be expanded. If the tt(-r) option is given, the function(s) in the
+file will be read and copied into the shell's memory when they are
+autoloaded. If the tt(-m) option is given instead, the wordcode file
+will be mapped into the shell's memory. This is done in such a way
+that multiple instances of the shell running on the same host will
+share this mapped function. If neither tt(-r) nor tt(-m) are given,
+the tt(zcompile) builtin decides which style is used based on the size 
+of the resulting wordcode file.
+
+In every case, the created file contains two versions of the wordcode, 
+one for big-endian machines and one for small-endian machines. The
+upshot of this is that the wordcode file is machine independent and if 
+it is read or mapped, only one half of the file will really be used
+(and mapped).
+
+In the second form, with the tt(-t) option, an existing wordcode file is
+tested. Without further arguments, the names of the function files
+used for it are listed. The first line tells the version of the shell
+the file was created with and how the file will be used (mapping or
+reading the file). With arguments, only the return value is set
+to zero if all var(name)s name functiones defined in the file and
+non-zero if at least one var(name) is not contained in the wordcode file.
+)
 findex(zmodload)
 cindex(modules, loading)
 cindex(loading modules)
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index c2462b7dd..43c063f8c 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -33,10 +33,17 @@ cindex(autoloading functions)
 cindex(functions, autoloading)
 A function can be marked as em(undefined) using the tt(autoload) builtin
 (or `tt(functions -u)' or `tt(typeset -fu)').  Such a function has no
-body.  When the function is first executed, the tt(fpath)
-variable will be searched for a file with the same name as the
-function.  The usual alias expansion during reading will be suppressed if
-the tt(autoload) builtin or its equivalent is given the option tt(-U);
+body.  When the function is first executed, each element of the tt(fpath)
+variable will first be searched for a file with the same name as the
+function plus the extension tt(.zwc) and then with the name of the
+function.  The first file will only be used if it was created with the 
+tt(zcompile) builtin command, if it contains the wordcode for the
+function and it is either older than the file with the name of the
+function in the same directory or if such a file does not exist.  The
+usual alias expansion during reading will be suppressed
+if the tt(autoload) builtin or its equivalent is given the option
+tt(-U), for wordcode files this has to be decided when creating the
+file with the tt(-U) option of the tt(zcompile) builtin command;
 this is recommended for the use of functions supplied with the zsh
 distribution.  Thus to define functions for autoloading, a typical sequence
 is:
@@ -44,6 +51,12 @@ is:
 example(fpath=(~/myfuncs $fpath)
 autoload myfunc1 myfunc2 ...)
 
+The elements of the tt(fpath) array may also name wordcode files
+directly. This is mostly useful for wordcode files containing multiple 
+functions, in which case the file is treated like a directory
+containing files for functions and will be searched for the definition 
+of the function.
+
 pindex(KSH_AUTOLOAD, use of)
 If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple
 definition of the function, the file's contents will be