1zcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ] 2zcompile -ca [ -m ] [ -R | -M ] file [ name ... ] 3zcompile -t file [ name ... ] 4 This builtin command can be used to compile functions or 5 scripts, storing the compiled form in a file, and to examine 6 files containing the compiled form. This allows faster 7 autoloading of functions and execution of scripts by avoiding 8 parsing of the text when the files are read. 9 10 The first form (without the -c, -a or -t options) creates a com- 11 piled file. If only the file argument is given, the output file 12 has the name `file.zwc' and will be placed in the same directory 13 as the file. The shell will load the compiled file instead of 14 the normal function file when the function is autoloaded; see 15 the section `Autoloading Functions' in zshmisc(1) for a descrip- 16 tion of how autoloaded functions are searched. The extension 17 .zwc stands for `zsh word code'. 18 19 If there is at least one name argument, all the named files are 20 compiled into the output file given as the first argument. If 21 file does not end in .zwc, this extension is automatically 22 appended. Files containing multiple compiled functions are 23 called `digest' files, and are intended to be used as elements 24 of the FPATH/fpath special array. 25 26 The second form, with the -c or -a options, writes the compiled 27 definitions for all the named functions into file. For -c, the 28 names must be functions currently defined in the shell, not 29 those marked for autoloading. Undefined functions that are 30 marked for autoloading may be written by using the -a option, in 31 which case the fpath is searched and the contents of the defini- 32 tion files for those functions, if found, are compiled into 33 file. If both -c and -a are given, names of both defined func- 34 tions and functions marked for autoloading may be given. In 35 either case, the functions in files written with the -c or -a 36 option will be autoloaded as if the KSH AUTOLOAD option were 37 - 38 unset. 39 40 The reason for handling loaded and not-yet-loaded functions with 41 different options is that some definition files for autoloading 42 define multiple functions, including the function with the same 43 name as the file, and, at the end, call that function. In such 44 cases the output of `zcompile -c' does not include the addi- 45 tional functions defined in the file, and any other initializa- 46 tion code in the file is lost. Using `zcompile -a' captures all 47 this extra information. 48 49 If the -m option is combined with -c or -a, the names are used 50 as patterns and all functions whose names match one of these 51 patterns will be written. If no name is given, the definitions 52 of all functions currently defined or marked as autoloaded will 53 be written. 54 55 The third form, with the -t option, examines an existing com- 56 piled file. Without further arguments, the names of the origi- 57 nal files compiled into it are listed. The first line of output 58 shows the version of the shell which compiled the file and how 59 the file will be used (i.e. by reading it directly or by mapping 60 it into memory). With arguments, nothing is output and the 61 return status is set to zero if definitions for all names were 62 found in the compiled file, and non-zero if the definition for 63 at least one name was not found. 64 65 Other options: 66 67 -U Aliases are not expanded when compiling the named files. 68 69 -R When the compiled file is read, its contents are copied 70 into the shell's memory, rather than memory-mapped (see 71 -M). This happens automatically on systems that do not 72 support memory mapping. 73 74 When compiling scripts instead of autoloadable functions, 75 it is often desirable to use this option; otherwise the 76 whole file, including the code to define functions which 77 have already been defined, will remain mapped, conse- 78 quently wasting memory. 79 80 -M The compiled file is mapped into the shell's memory when 81 read. This is done in such a way that multiple instances 82 of the shell running on the same host will share this 83 mapped file. If neither -R nor -M is given, the zcompile 84 builtin decides what to do based on the size of the com- 85 piled file. 86 87 -k 88 -z These options are used when the compiled file contains 89 functions which are to be autoloaded. If -z is given, the 90 function will be autoloaded as if the KSH AUTOLOAD option 91 - 92 is not set, even if it is set at the time the compiled 93 file is read, while if the -k is given, the function will 94 be loaded as if KSH AUTOLOAD is set. These options also 95 - 96 take precedence over any -k or -z options specified to 97 the autoload builtin. If neither of these options is 98 given, the function will be loaded as determined by the 99 setting of the KSH AUTOLOAD option at the time the com- 100 - 101 piled file is read. 102 103 These options may also appear as many times as necessary 104 between the listed names to specify the loading style of 105 all following functions, up to the next -k or -z. 106 107 The created file always contains two versions of the com- 108 piled format, one for big-endian machines and one for 109 small-endian machines. The upshot of this is that the 110 compiled file is machine independent and if it is read or 111 mapped, only one half of the file is actually used (and 112 mapped). 113