Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 427 lines (347 sloc) 20.111 kb
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
10
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
11 =====================
12 MAKING AND INSTALLING
13 =====================
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
43 Many of the interesting configuration options can be added after running
c175751b » Tanaka Akira
1999-04-15 Initial revision
44 configure by editing the user configuration section of config.h and the
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
45 top level Makefile. However, see the end of this file for a list of
46 features configurable on the command line.
c175751b » Tanaka Akira
1999-04-15 Initial revision
47
48 Dynamic loading
49 ---------------
50
7ea08d14 » Andrey Borzenkov
2001-05-30 14557: remove obsolete version number
51 Zsh has support for dynamically loadable modules. This is now enabled
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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 ---------------------------
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
49a1ad75 » Peter Stephenson
2000-11-26 13194: change in module configuration system
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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:
49a1ad75 » Peter Stephenson
2000-11-26 13194: change in module configuration system
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.
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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.
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
49a1ad75 » Peter Stephenson
2000-11-26 13194: change in module configuration system
111 compile zle and complete into the base executable by setting their `link'
112 entries in config.modules to `static' as described above.
c175751b » Tanaka Akira
1999-04-15 Initial revision
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:
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
124 CC=c89 ./configure --enable-cflags=-O2 --enable-libs=-lposix
125 This is almost equivalent to
c175751b » Tanaka Akira
1999-04-15 Initial revision
126 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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'.
7102a469 » Peter Stephenson
2000-08-11 12598: configure takes --enable-cflags=... etc. arguments
138
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
151 Also, configure will create a Makefile in the top level directory as well
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
158 After configuring, to build zsh, execute the command:
c175751b » Tanaka Akira
1999-04-15 Initial revision
159 make
160
e4d828b2 » Bart Schaefer
2001-05-29 Document "make check".
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
c175751b » Tanaka Akira
1999-04-15 Initial revision
173 Installing Zsh
174 --------------
175
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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.
c175751b » Tanaka Akira
1999-04-15 Initial revision
179
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
180 Alternatively, you can install the various parts in separate stages. To
181 install the zsh binary, execute the command:
182 make install.bin
c175751b » Tanaka Akira
1999-04-15 Initial revision
183 Any previous copy of zsh will be renamed "zsh.old"
f6797d6f » Peter Stephenson
2003-04-04 18433: package documentation for 4.1.1
184
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
185 To install the dynamically-loadable modules, execute the command:
c175751b » Tanaka Akira
1999-04-15 Initial revision
186 make install.modules
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
187 Note that this is required for the shell to operate properly if dynamic
188 loading is enabled.
c175751b » Tanaka Akira
1999-04-15 Initial revision
189
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
190 To install the zsh man page, execute the command:
c175751b » Tanaka Akira
1999-04-15 Initial revision
191 make install.man
192
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
193 To install all the shell functions which come with the distribution,
194 execute the command:
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
195 make install.fns
c175751b » Tanaka Akira
1999-04-15 Initial revision
196
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
197 To install the zsh info files (this must be done separately), execute the
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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.
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
233
234 =====================
235 CONFIGURATION OPTIONS
236 =====================
237
c175751b » Tanaka Akira
1999-04-15 Initial revision
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
285 --disable-SCRIPTNAME option to "configure". The --disable-etcdir option
f18221fb » Oliver Kiddle
2001-03-12 spelling corrections (13610)
286 disables all startup/shutdown files which are not explicitly enabled.
c175751b » Tanaka Akira
1999-04-15 Initial revision
287
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
caa994e1 » Peter Stephenson
2000-12-04 installfns bits
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='
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
310 entry or delete the rest of the line after it.
caa994e1 » Peter Stephenson
2000-12-04 installfns bits
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
318 are not used by the editor unless you explicitly load them, however.
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
3d7263ff » Sven Wischnowsky
2001-04-02 after-move cleanup
322 directory, i.e. `Base/*' files will be installed into `FNDIR/Base, and so
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
341 CC="cc -Ae" CPPFLAGS="-D_LARGEFILE_SOURCE -D_FILE64" configure \
342 --enable-lfs ...
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
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).
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
351 enabled. Hence --enable-lfs is useful on many 32-bit systems
78526bb0 » Bart Schaefer
2000-08-11 12596: Update INSTALL for module aliasing changes.
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).
c175751b » Tanaka Akira
1999-04-15 Initial revision
361
5138a429 » Peter Stephenson
2004-03-01 19512: --enable-pcre option
362 Searching for `pcre'
363 --------------------
364
365 Zsh has a module which allows the pcre regular expression library to be
366 used via shell builtins. Compiling this library into the shell with
367 dynamic loading (the default where available) produces a dependency on the
368 library libpcre.so. This is a problem on systems where zsh needs to be
369 available at boot before the directory containing libpcre.so (for
370 example /usr/lib or /usr/local/lib) is mounted. For this reason,
371 pcre support will only be searched for if the option --enable-pcre
372 is passed to configure.
373
374 (Future versions of the shell may have a better fix for this problem.)
375
c175751b » Tanaka Akira
1999-04-15 Initial revision
376 Options For Configure
377 ---------------------
378
379 The `configure' program accepts many options, not all of which are useful
380 or relevant to zsh. To get the complete list of configure options, run
381 "./configure --help". The following list should contain most of the
382 options of interest for configuring zsh.
383
384 Configuration:
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
385 --cache-file=FILE # cache test results in FILE
386 --help # print a help message
387 --version # print the version of autoconf that create configure
388 --quiet, --silent # do not print `checking...' messages
389 --no-create # do not create output files
c175751b » Tanaka Akira
1999-04-15 Initial revision
390
391 Directories:
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
392 --prefix=PREFIX # install host independent files in PREFIX [/usr/local]
393 --exec-prefix=EPREFIX # install host dependent files in EPREFIX [PREFIX]
394 --bindir=DIR # install user executables in DIR [EPREFIX/bin]
395 --infodir=DIR # install info documentation in DIR [PREFIX/info]
396 --mandir=DIR # install man documentation in DIR [PREFIX/man]
397 --srcdir=DIR # find the sources in DIR [configure dir or ..]
398 --datadir=DATADIR # install shared files in DATADIR [PREFIX/share]
c175751b » Tanaka Akira
1999-04-15 Initial revision
399
400 Features:
99beeb57 » Peter Stephenson
2001-05-30 Doc changes for 4.0.1
401 --enable-FEATURE # enable use of this feature
402 --disable-FEATURE # disable use of this feature
403
404 Here is the list of FEATURES currently supported. Defaults are shown in
405 brackets, though a value shown as `yes' (equivalent to --enable-FEATURE)
406 will be ignored if your OS doesn't support that feature.
407
408 zsh-debug # compile debugging features into zsh [no]
409 zsh-mem # use zsh's memory allocators [no]
410 zsh-mem-debug # debug zsh's memory allocators [no]
411 zsh-mem-warning # turn on warnings of memory allocation errors [no]
412 zsh-secure-free # turn on memory checking of free() [no]
413 zsh-hash-debug # turn on debugging of internal hash tables [no]
414 etcdir=directory # default directory for global zsh scripts [/etc]
415 zshenv=pathname # the path to the global zshenv script [/etc/zshenv]
416 zshrc=pathname # the path to the global zshrc script [/etc/zshrc]
417 zlogin=pathname # the path to the global zlogin script [/etc/zlogin]
418 zprofile=pathname # the path to the global zprofile script [/etc/zprofile]
419 zlogout=pathname # the path to the global zlogout script [/etc/zlogout]
420 fndir=directory # the directory where shell functions will go
421 # [DATADIR/zsh/VERSION/functions]
422 site-fndir=directory # the directory where site-specific functions can go
423 # [DATADIR/zsh/site-functions]
424 function-subdirs # if functions will be installed into subdirectories [no]
425 dynamic # allow dynamically loaded binary modules [yes]
426 lfs # allow configure check for large files [yes]
427 locale # allow use of locale library [yes]
428
Something went wrong with that request. Please try again.