Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 415 lines (336 sloc) 19.484 kB
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
1 ++++++++++++++
2 INSTALLING ZSH
3 ++++++++++++++
4
5 This file is divided into two parts: making and installing the shell, and
6 a description of various additional configuration options. You should
7 have a look at the items in the second part before following the
8 instructions in the first.
9
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
10
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
11 =====================
12 MAKING AND INSTALLING
13 =====================
c175751 Initial revision
Tanaka Akira authored
14
15 Check MACHINES File
16 -------------------
17
18 Check the file MACHINES in the subdirectory Etc to see the architectures
19 that zsh is known to compile on, as well as any special instructions
20 for your particular architecture. Most architectures will not require any
21 special instructions.
22
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
23 Pre-configuration
24 -----------------
25
26 If you are using a normal source release, skip this section.
27
28 If the `configure' script does not already exist -- e.g., if you've got
29 a snapshot of the bare sources just checked out from a CVS repository
30 -- some things need to be built before the configuration can proceed.
31 Run the script `./Util/preconfig' to do this.
32
c175751 Initial revision
Tanaka Akira authored
33 Configuring Zsh
34 ---------------
35
36 To configure zsh, from the top level directory, do the command:
37 ./configure
38
39 Configure accepts several options (explained below). To display
40 currently available options, do the command:
41 ./configure --help
42
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
43 Many of the interesting configuration options can be added after running
c175751 Initial revision
Tanaka Akira authored
44 configure by editing the user configuration section of config.h and the
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
45 top level Makefile. However, see the end of this file for a list of
46 features configurable on the command line.
c175751 Initial revision
Tanaka Akira authored
47
48 Dynamic loading
49 ---------------
50
7ea08d1 14557: remove obsolete version number
Andrey Borzenkov authored
51 Zsh has support for dynamically loadable modules. This is now enabled
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
52 by default; to disable it, run configure with the --disable-dynamic option.
53 Note that dynamic loading does not work on all systems. On these systems
54 this option will have no effect. When dynamic loading is enabled, major
55 parts of zsh (including the Zsh Line Editor) are compiled into modules and
56 not included into the main zsh binary. Zsh autoloads these modules when
57 they are required. This means that you have to execute make
58 install.modules before you try the newly compiled zsh executable, and hence
59 also the install paths must be correct. The installation path for modules
60 is EPREFIX/lib/zsh/<zsh-version-number>, where EPREFIX defaults to PREFIX
61 unless given explicitly, and PREFIX defaults to /usr/local. See the end of
62 this file for options to configure to change these.
63
64 Adding and removing modules
65 ---------------------------
c175751 Initial revision
Tanaka Akira authored
66
67 The zsh distribution contains several modules, in the Src/Builtins,
68 Src/Modules and Src/Zle directories. If you have any additional zsh
69 modules that you wish to compile for this version of zsh, create another
70 subdirectory of the Src directory and put them there. You can create
49a1ad7 13194: change in module configuration system
Peter Stephenson authored
71 as many extra subdirectories as you need, but currently configure will only
72 search in immediate subdirectories of Src. The subdirectories must be
73 actual directories; symbolic links will not work. You will then need to
74 rerun configure; the easiest way is to run `config.status --recheck' from
75 the top-level build directory which retains the existing configuration as
76 much as possible.
77
78 The key to the module system is the file config.modules, created in the
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
79 configuration process. In the normal case that dynamic loading is
80 available, all modules relevant to your configuration will be compiled and
81 installed as separate files, so unless you want the modules to be loaded by
82 default you don't need to do anything. For a non-dynamic zsh, the default
83 is to compile the complete, compctl, zle, computil, complist, sched,
84 parameter, zleparameter and rlimits modules into the shell, and you will
85 need to edit config.modules to make any other modules available.
86
87 If you wish to change the configuration, here is how config.modules works.
88 Each module has a line in the file. Be careful to retain the (strict)
89 format for lines in the file:
49a1ad7 13194: change in module configuration system
Peter Stephenson authored
90 link - `dynamic', if the module is to be dynamically linked -- meaningless
91 if this is not available on your system.
92 `static' if the module is to be linked directly into the executable.
93 `no' if the module is not to be linked at all. In this case it will
94 not even be compiled.
95 load - `yes' if the module is to be visible to the user. This will make
96 builtins, parameters etc. visible to the user without any need
97 to use the zmodload builtin.
98 `no' if an explicit zmodload command is to be required to load the
99 utilities in the module. Note that this applies both to
100 statically and dynamically linked modules.
101 auto - `yes' if the entry is to be regenerated whenever configure is run.
102 `no' if you wish to retain your hand-edited version.
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
103 Do not edit the entry for the pseudo-module zsh/main (apart from the
104 `functions=' part) as this is the main shell. After you have edited this
105 file, run `make prep' in the Src subdirectory.
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
106
107 Note that the modules depending on zle or complete (e.g.: complist and
108 deltochar) cannot be loaded dynamically on systems which do not allow symbols
109 in one dynamically loaded library to be visible from another; this is true,
110 for example, of version 4 of SunOS. The most convenient workaround is to
49a1ad7 13194: change in module configuration system
Peter Stephenson authored
111 compile zle and complete into the base executable by setting their `link'
112 entries in config.modules to `static' as described above.
c175751 Initial revision
Tanaka Akira authored
113
114 Compiler Options or Using a Different Compiler
115 ----------------------------------------------
116
117 By default, configure will use the "gcc" compiler if found. You can use a
118 different compiler, or add unusual options for compiling or linking that
119 the "configure" script does not know about, by either editing the user
120 configuration section of the top level Makefile (after running configure)
121 or giving "configure" initial values for these variables by setting them
122 in the environment. Using a Bourne-compatible shell (such as sh,ksh,zsh),
123 you can do that on the command line like this:
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
124 CC=c89 ./configure --enable-cflags=-O2 --enable-libs=-lposix
125 This is almost equivalent to
c175751 Initial revision
Tanaka Akira authored
126 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
127 but has the advantage that the CFLAGS and LIBS variables are remembered if
128 the configuration is recreated by means of `config.status --recheck' (this
129 happens automatically if certain configuration files change). You can
130 set the make variables CFLAGS, CPPFLAGS, LDFLAGS and LIBS in this way,
131 however CC must appear as shown. If you are configuring from a csh-derived
132 shell, you may need to use the "env" program:
133 env CC=c89 ./configure --enable-cflags=-O2 --enable-libs=-lposix.
134
135 You can override the variables directly when running `make':
136 make CFLAGS=-g
137 However, these will not be passed down via `config.status --recheck'.
7102a46 12598: configure takes --enable-cflags=... etc. arguments
Peter Stephenson authored
138
c175751 Initial revision
Tanaka Akira authored
139 Check Generated Files
140 ---------------------
141
142 Configure will probe your system and create a "config.h" header file.
143 You should check the user configuration section at the beginning of
144 this include file. You should also examine the values (determined by
145 configure) of HOSTTYPE, OSTYPE, MACHTYPE, and VENDOR to make sure they
146 are correct. The value of these #defines's is used only to initialize
147 the corresponding default shell parameters. Since these shell parameters
148 are only for informational purposes, you can change them to whatever
149 you feel is appropriate.
150
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
151 Also, configure will create a Makefile in the top level directory as well
c175751 Initial revision
Tanaka Akira authored
152 as in the various subdirectories. You should check the user configuration
153 section of the top level Makefile.
154
155 Compiling Zsh
156 -------------
157
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
158 After configuring, to build zsh, execute the command:
c175751 Initial revision
Tanaka Akira authored
159 make
160
e4d828b Document "make check".
Bart Schaefer authored
161 It's then a good idea to check that your build is working properly:
162 make check
163
164 If you have trouble with a particular test, you can run it separately:
165 make TESTNUM=C02 check
166
167 The TESTNUM value can be a single test number, as above, or a letter to
168 run an entire category of tests:
169 make TESTNUM=Y check
170
171 See Test/README for a list of test categories.
172
c175751 Initial revision
Tanaka Akira authored
173 Installing Zsh
174 --------------
175
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
176 If no make/compilation errors occur, then execute the command
177 make install
178 to install all the necessary files except for the info files.
c175751 Initial revision
Tanaka Akira authored
179
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
180 Alternatively, you can install the various parts in separate stages. To
181 install the zsh binary, execute the command:
182 make install.bin
c175751 Initial revision
Tanaka Akira authored
183 Any previous copy of zsh will be renamed "zsh.old"
f6797d6 18433: package documentation for 4.1.1
Peter Stephenson authored
184
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
185 To install the dynamically-loadable modules, execute the command:
c175751 Initial revision
Tanaka Akira authored
186 make install.modules
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
187 Note that this is required for the shell to operate properly if dynamic
188 loading is enabled.
c175751 Initial revision
Tanaka Akira authored
189
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
190 To install the zsh man page, execute the command:
c175751 Initial revision
Tanaka Akira authored
191 make install.man
192
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
193 To install all the shell functions which come with the distribution,
194 execute the command:
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
195 make install.fns
c175751 Initial revision
Tanaka Akira authored
196
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
197 To install the zsh info files (this must be done separately), execute the
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
198 command:
199 make install.info
200 If the programme install-info is available, "make install.info" will
201 insert an entry in the file "dir" in the same directory as the info
202 files. Otherwise you will have to edit the topmost node of the info
203 tree "dir" manually in order to have the zsh info files available to
204 your info reader.
c175751 Initial revision
Tanaka Akira authored
205
206 Building Zsh On Additional Architectures
207 ----------------------------------------
208
209 To build zsh on additional architectures, you can do a "make distclean".
210 This should restore the zsh source distribution back to its original
211 state. You can then configure zsh as above on other architectures in
212 which you wish to build zsh. Or alternatively, you can use a different
213 build directory for each architecture.
214
215 Using A Different Build Directory
216 ---------------------------------
217
218 You can compile the zsh in a different directory from the one containing
219 the source code. Doing so allows you to compile it on more than one
220 architecture at the same time. To do this, you must use a version of
221 "make" that supports the "VPATH" variable, such as GNU "make". "cd" to
222 the directory where you want the object files and executables to go and
223 run the "configure" script. "configure" automatically checks for the
224 source code in the directory that "configure" is in. For example,
225
226 cd /usr/local/SunOS/zsh
227 /usr/local/src/zsh-3.0/configure
228 make
229
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
230 Note that this is mutually exclusive with using the source directories
231 as make can become confused by build files created in the source directories.
232
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
233
234 =====================
235 CONFIGURATION OPTIONS
236 =====================
237
c175751 Initial revision
Tanaka Akira authored
238 Memory Routines
239 ---------------
240
241 Included in this release are alternate malloc and associated functions
242 which reduce memory usage on some systems. To use these, add the option
243 --enable-zsh-mem
244 when invoking "configure".
245
246 You should check Etc/MACHINES to see if there are specific recommendations
247 about using the zsh malloc routines on your particular architecture.
248
249 Debugging Routines
250 ------------------
251
252 You can turn on various debugging options when invoking "configure".
253
254 To turn on some extra checking in the memory management routines, you
255 can use the following options when invoking "configure".
256 --enable-zsh-mem-warning # turn on warnings of memory allocation errors
257 --enable-zsh-secure-free # turn on memory checking of free()
258
259 If you are using zsh's memory allocation routines (--enable-zsh-mem), you
260 can turn on debugging of this code. This enables the builtin "mem".
261 --enable-zsh-mem-debug # debug zsh's memory allocators
262
263 You can turn on some debugging information of zsh's internal hash tables.
264 This enables the builtin "hashinfo".
265 --enable-zsh-hash-debug # turn on debugging of internal hash tables
266
267 To add some sanity checks and generate debugging information for debuggers
268 you can use the following option. This also disables optimization.
269 --enable-zsh-debug # use it if you want to debug zsh
270
271 Startup/shutdown files
272 ----------------------
273
274 Zsh has several startup/shutdown files which are in /etc by default. This
275 can be overriden using one of the options below when invoking "configure".
276
277 --enable-etcdir=directory # default directory for global zsh scripts
278 --enable-zshenv=pathname # the full pathname of the global zshenv script
279 --enable-zshrc=pathname # the full pathname of the global zshrc script
280 --enable-zlogin=pathname # the full pathname of the global zlogin script
281 --enable-zprofile=pathname # the full pathname of the global zprofile script
282 --enable-zlogout=pathname # the full pathname of the global zlogout script
283
284 Any startup/shutdown script can be disabled by giving the
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
285 --disable-SCRIPTNAME option to "configure". The --disable-etcdir option
f18221f spelling corrections (13610)
Oliver Kiddle authored
286 disables all startup/shutdown files which are not explicitly enabled.
c175751 Initial revision
Tanaka Akira authored
287
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
288 Shell functions
289 ---------------
290
291 By default, the shell functions which are installed with `make install' or
292 `make install.fns' go into the directory ${datadir}/zsh/functions, which
293 unless you have specified --datadir is the same as
294 ${prefix}/share/zsh/$ZSH_VERSION/functions ($prefix itself defaults to
295 /usr/local, as described below). This directory will also be compiled into
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
296 the shell as the default directory for the parameters $fpath and
297 $FPATH. You can override it with --enable-fndir=directory; --disable-fndir
298 or --enable-fndir=no will turn off both installation of functions and the
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
299 setting of a default value for $fpath/$FPATH. Note the presence of
300 $ZSH_VERSION (e.g. `3.1.7') to avoid clashes between versions of zsh.
301 If you only run one version of zsh at once, installing into a common
caa994e installfns bits
Peter Stephenson authored
302 directory such as /usr/local/share/zsh/functions is fine --- note, however,
303 that uninstallation is more likely to create problems in this case.
304
305 The functions to be installed are controlled by config.modules. These
306 appear at the end of the line after `functions=': note that the rest of the
307 line is taken verbatim as shell command line text, i.e. no quoting is used
308 around the value as a whole and unquoted wildcards will be expanded. To
309 prevent any functions from being installed, either remove the `functions='
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
310 entry or delete the rest of the line after it.
caa994e installfns bits
Peter Stephenson authored
311
312 Functions not specific to a particular module are listed on the zsh/main
313 line. None of these are crucial to shell operation, so you may choose not
314 to install them. For other modules, the functions will be installed if and
315 only if the module itself is installed. This will usually be what you
316 want; in particular, the zsh/complete and zsh/zftp modules are of much less
317 use without the associated functions. The functions listed with zsh/zle
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
318 are not used by the editor unless you explicitly load them, however.
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
319
320 You can also use the configure option --enable-function-subdirs to allow
321 shell functions to be installed into subdirectories of the function
3d7263f after-move cleanup
Sven Wischnowsky authored
322 directory, i.e. `Base/*' files will be installed into `FNDIR/Base, and so
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
323 on. This also initialises $fpath/$FPATH appropriately.
324
325 The option --enable-site-fndir controls whether to create and initialise
326 $fpath to include a directory for site-specific functions. By default this
327 is created in the location ${datadir}/zsh/site-functions, i.e. parallel to
328 the version-specific functions directory, and inserted at the start of the
329 $fpath array on shell startup. This directory will not be affected by
330 `make uninstall' or `make uninstall.fns', although the version-specific
331 directory and its contents will be deleted.
332
333 Support for large files and integers
334 ------------------------------------
335
336 Some 32-bit systems allow special compilation modes to get around the 2GB
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
337 file size barrier. This is enabled by default; use --disable-lfs to turn
338 it off. Not all systems recognize the test used by zsh (via the getconf
339 command), so flags may need to be set by hand. On HP-UX 10.20, zsh has
340 been successfully compiled with large file support by configuring with
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
341 CC="cc -Ae" CPPFLAGS="-D_LARGEFILE_SOURCE -D_FILE64" configure \
342 --enable-lfs ...
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
343 You can also specify --enable-lfs together with a value, which will be
344 interpreted as the name of a 64-bit integer type, for example
345 --enable-lfs="long long" (although this type is checked for anyway).
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
346
347 Furthermore, use of --enable-lfs will also enable 64-bit arithmetic for
348 shell parameters, and anywhere they are used such as in mathematical
349 formulae. This depends only on the shell finding a suitable 64-bit integer
350 type; it does not require that support for large files is actually
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
351 enabled. Hence --enable-lfs is useful on many 32-bit systems
78526bb 12596: Update INSTALL for module aliasing changes.
Bart Schaefer authored
352 with a suitable compiler such as gcc.
353
354 Also note that if `configure' finds out that either of the types off_t or
355 ino_t are 64-bit quantities, but that long integers are only 32 bits, all
356 the above will be enabled automatically. This is necessary to ensure
357 correct handling of these types.
358
359 None of this is relevant for 64-bit systems; zsh should compile and run
360 without problems if (sizeof(long) == 8).
c175751 Initial revision
Tanaka Akira authored
361
362 Options For Configure
363 ---------------------
364
365 The `configure' program accepts many options, not all of which are useful
366 or relevant to zsh. To get the complete list of configure options, run
367 "./configure --help". The following list should contain most of the
368 options of interest for configuring zsh.
369
370 Configuration:
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
371 --cache-file=FILE # cache test results in FILE
372 --help # print a help message
373 --version # print the version of autoconf that create configure
374 --quiet, --silent # do not print `checking...' messages
375 --no-create # do not create output files
c175751 Initial revision
Tanaka Akira authored
376
377 Directories:
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
378 --prefix=PREFIX # install host independent files in PREFIX [/usr/local]
379 --exec-prefix=EPREFIX # install host dependent files in EPREFIX [PREFIX]
380 --bindir=DIR # install user executables in DIR [EPREFIX/bin]
381 --infodir=DIR # install info documentation in DIR [PREFIX/info]
382 --mandir=DIR # install man documentation in DIR [PREFIX/man]
383 --srcdir=DIR # find the sources in DIR [configure dir or ..]
384 --datadir=DATADIR # install shared files in DATADIR [PREFIX/share]
c175751 Initial revision
Tanaka Akira authored
385
386 Features:
99beeb5 Doc changes for 4.0.1
Peter Stephenson authored
387 --enable-FEATURE # enable use of this feature
388 --disable-FEATURE # disable use of this feature
389
390 Here is the list of FEATURES currently supported. Defaults are shown in
391 brackets, though a value shown as `yes' (equivalent to --enable-FEATURE)
392 will be ignored if your OS doesn't support that feature.
393
394 zsh-debug # compile debugging features into zsh [no]
395 zsh-mem # use zsh's memory allocators [no]
396 zsh-mem-debug # debug zsh's memory allocators [no]
397 zsh-mem-warning # turn on warnings of memory allocation errors [no]
398 zsh-secure-free # turn on memory checking of free() [no]
399 zsh-hash-debug # turn on debugging of internal hash tables [no]
400 etcdir=directory # default directory for global zsh scripts [/etc]
401 zshenv=pathname # the path to the global zshenv script [/etc/zshenv]
402 zshrc=pathname # the path to the global zshrc script [/etc/zshrc]
403 zlogin=pathname # the path to the global zlogin script [/etc/zlogin]
404 zprofile=pathname # the path to the global zprofile script [/etc/zprofile]
405 zlogout=pathname # the path to the global zlogout script [/etc/zlogout]
406 fndir=directory # the directory where shell functions will go
407 # [DATADIR/zsh/VERSION/functions]
408 site-fndir=directory # the directory where site-specific functions can go
409 # [DATADIR/zsh/site-functions]
410 function-subdirs # if functions will be installed into subdirectories [no]
411 dynamic # allow dynamically loaded binary modules [yes]
412 lfs # allow configure check for large files [yes]
413 locale # allow use of locale library [yes]
414
Something went wrong with that request. Please try again.