1 GNU Emacs Installation Guide
2 Copyright (c) 1992, 1994, 1996, 1997, 2000 Free software Foundation, Inc.
4 Permission is granted to anyone to make or distribute verbatim copies
5 of this document as received, in any medium, provided that the
6 copyright notice and permission notice are preserved,
7 and that the distributor grants the recipient permission
8 for further redistribution as permitted by this notice.
10 Permission is granted to distribute modified versions
11 of this document, or of portions of it,
12 under the above conditions, provided also that they
13 carry prominent notices stating who last changed them,
14 and that any new or changed statements about the activities
15 of the Free Software Foundation are approved by the Foundation.
19 The simplest way to build Emacs is to use the `configure' shell script
20 which attempts to guess correct values for various system-dependent
21 variables and features and find the directories where various system
22 headers and libraries are kept. It then creates a `Makefile' in each
23 subdirectory and a `config.h' file containing system-dependent
24 definitions. Running the Make utility then builds the package for
27 Here's the procedure to build Emacs using `configure' on systems which
28 are supported by it. If this simplified procedure fails, or if you
29 are using a platform such as MS-Windows where `configure' script
30 doesn't work, you might need to use various non-default options, and
31 maybe perform some of the steps manually. The more detailed
32 description in the rest of the sections of this guide will help you do
33 that, so please refer to them if the simple procedure does not work.
35 1. If you want to be able to input international characters which
36 your keyboard doesn't support directly (i.e., you cannot type
37 them at the shell prompt), download the leim-M.N.tar.gz
38 distribution and unpack it into the same directory where you have
39 unpacked the main Emacs distribution. See ADDITIONAL
40 DISTRIBUTION FILES, below, for more about this.
42 2. Make sure your system has at least 120 MB of free disk space.
44 3a. `cd' to the directory where you unpacked Emacs and invoke the
49 3b. Alternatively, create a separate directory, outside the source
50 directory, where you want to build Emacs, and invoke `configure'
55 where SOURCE-DIR is the top-level Emacs source directory.
57 4. When `configure' finishes, it prints several lines of details
58 about the system configuration. Read those details carefully
59 looking for anything suspicious, such as wrong CPU and operating
60 system names, wrong places for headers or libraries, missing
61 libraries that you know are installed on your system, etc.
63 If you find anything wrong, you will have to pass to `configure'
64 explicit machine configuration name, and one or more options
65 which tell it where to find various headers and libraries; refer
66 to DETAILED BUILDING AND INSTALLATION section below.
68 If `configure' didn't find some image support libraries, such as
69 Xpm, jpeg, etc., refer to the subsection "Image support
72 If the details printed by `configure' don't make any sense to
73 you, assume that `configure' did its job and proceed.
75 5. If you need to run the `configure' script more than once (e.g.,
76 with some non-default options), always clean the source
77 directories before running `configure' again:
82 6. Invoke the Make program:
86 7. If Make succeeds, it will build an executable program `emacs' in
87 the `src' directory. You can try this program, to make sure it
92 8. Assuming that the program `src/emacs' starts and displays its
93 opening screen, you can install the program and its auxiliary
94 files into their installation directories:
98 You are now ready to use Emacs. If you wish to conserve disk space,
99 you may remove the program binaries and object files from the
100 directory where you built Emacs:
105 ADDITIONAL DISTRIBUTION FILES
109 The Emacs Lisp code for input methods for various international
110 character scripts allows you to input characters in scripts which are
111 not directly supported by your keyboard. It is distributed in a
112 separate tar file because it amounts to a significant fraction of the
113 size of the distribution. This tar file is called leim-M.N.tar.gz,
114 with the same version number as Emacs, and it unpacks into the
115 directory emacs-M.N/leim.
117 You should unpack leim-M.N.tar.gz into the same directory where you
118 have previously unpacked the main Emacs distribution. It fills in the
119 contents of one subdirectory, which is present in the main Emacs
120 distribution only in dummy form.
122 Once you have unpacked the Leim tar file into the Emacs source tree,
123 building and installing Emacs automatically installs the input method
124 support as well. If you have built Emacs without unpacking Leim
125 first, just unpack Leim, build Emacs again, and install it again.
127 * intlfonts-VERSION.tar.gz
129 The intlfonts distribution contains X11 fonts that Emacs needs in
130 order to display international characters. If you see a non-ASCII
131 character appear as a hollow box, that means you don't have a font for
132 it. You might find a font in the intlfonts distribution. If you do
133 have a font for a non-ASCII character, but some characters don't look
134 right, or appear improperly aligned, a font from the intlfonts
135 distribution might look better.
137 The fonts in the intlfonts distribution are also used by the ps-print
138 package for printing international characters. The file
139 lisp/ps-mule.el defines the *.bdf font files required for printing
142 The intlfonts distribution contains its own installation instructions,
143 in the intlfonts/README file.
145 * elisp-manual-M.N.tar.gz
147 This distribution contains the Emacs Lisp Reference Manual which
148 complements the Emacs Manual. (The Emacs Manual is accessible from
149 within the editor by typing "C-h i", then selecting the "Emacs" item
150 from the menu, or by clicking "Help" in the menu bar and selecting
151 "Read Emacs Manual".) It is a good idea to install the Emacs Lisp
152 Reference Manual after installing Emacs, to complete the on-line
153 documentation of Emacs in Info.
155 If you have installed Texinfo, you can install the Emacs Lisp
156 Reference Manual this way (after unpacking the elisp-manual-M.N.tar.gz
160 ./configure --prefix=PREFIXDIR
163 Otherwise, you can install it manually. Just copy the files elisp and
164 elisp-* from the elisp-manual-M.N directory to your site's info
165 directory (see the description of `infodir', below), and make sure
166 that file `dir' in this directory contains an entry like this:
168 * Elisp: (elisp). The Emacs Lisp Reference Manual.
170 * Image support libraries
172 Emacs needs optional libraries to be able to display images (with the
173 exception of PBM and XBM images whose support is built-in).
175 On some systems, particularly on GNU/Linux, these libraries may
176 already be present or available as additional packages. If not, you
177 can download and build them from sources. None of them are vital for
178 running Emacs; however, note that Emacs will not be able to use color
179 icons in the toolbar if the XPM support is not available.
181 Here's the list of these optional libraries, and the URLs where they
184 . libXaw3d for fancy 3D-style
185 scroll bars: ftp://ftp.x.org/contrib/widgets/Xaw3d/
186 . libxpm for XPM: ftp://ftp.x.org/contrib/libraries/
187 . libpng for PNG: ftp://www.libpng.org/pub/png/
188 . libz (for PNG): http://www.info-zip.org/pub/infozip/zlib/
189 . libjpeg for JPEG: ftp://ftp.uu.net/graphics/jpeg/
190 . libtiff for TIFF: http://www.libtiff.org/
192 http://prtr-13.ucsc.edu/~badger/software/libungif/index.shtml
194 Emacs will configure itself to build with these libraries if the
195 `configure' script finds them on your system, unless you supply the
196 appropriate --without-LIB option. In some cases, older versions of
197 these libraries won't work because some routines are missing, and
198 configure should avoid such old versions. If that happens, use the
199 --without-LIB options to `configure'. See below for more details.
202 DETAILED BUILDING AND INSTALLATION:
204 (This is for a Unix or Unix-like system. For MS-DOS and Windows 3.X,
205 see below; search for MSDOG. For Windows 9X, Windows ME, Windows NT,
206 and Windows 2000, see the file nt/INSTALL. For the Mac, see the file
209 1) Make sure your system has enough swapping space allocated to handle
210 a program whose pure code is 1.5 MB and whose data area is at
211 least 2.5 MB and can reach 80 MB or more. If the swapping space is
212 insufficient, you will get an error in the command `temacs -batch -l
213 loadup dump', found in `./src/Makefile.in', or possibly when
214 running the final dumped Emacs.
216 Building Emacs requires about 95 MB of disk space (including the Emacs
217 sources), or 130 MB if Leim is used. Once installed, Emacs occupies
218 about 60 MB (70 MB with Leim) in the file system where it is
219 installed; this includes the executable files, Lisp libraries,
220 miscellaneous data files, and on-line documentation. If the building
221 and installation take place in different directories, then the
222 installation procedure momentarily requires 95+60 MB (130+70 MB).
224 2) Consult `./etc/MACHINES' to see what configuration name you should
225 give to the `configure' program. That file offers hints for
226 getting around some possible installation problems. The file lists
227 many different configurations, but only the part for your machine and
228 operating system is relevant. (The list is arranged in alphabetical
229 order by the vendor name.)
231 3) You can build Emacs in the top-level Emacs source directory
232 or in a separate directory.
234 3a) To build in the top-level Emacs source directory, go to that
235 directory and run the program `configure' as follows:
237 ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...
239 The CONFIGURATION-NAME argument should be a configuration name given
240 in `./etc/MACHINES', with the system version number added at the end.
242 You should try first omitting CONFIGURATION-NAME. This way,
243 `configure' will try to guess your system type. If it cannot guess,
244 or if something goes wrong in building or installing Emacs this way,
245 try again specifying the proper CONFIGURATION-NAME explicitly.
247 If you don't want X support, specify `--with-x=no'. If you omit this
248 option, `configure' will try to figure out for itself whether your
249 system has X, and arrange to use it if present.
251 The `--x-includes=DIR' and `--x-libraries=DIR' options tell the build
252 process where the compiler should look for the include files and
253 object libraries used with the X Window System. Normally, `configure'
254 is able to find them; these options are necessary if you have your X
255 Window System files installed in unusual places. These options also
256 accept a list of directories, separated with colons.
258 To get more attractive menus, you can specify an X toolkit when you
259 configure Emacs; use the option `--with-x-toolkit=TOOLKIT', where
260 TOOLKIT is `athena' or `motif' (`yes' and `lucid' are synonyms for
261 `athena'). On some systems, it does not work to use a toolkit with
262 shared libraries. A free implementation of Motif, called LessTif, is
263 available ftom <http://www.lesstif.org>. You can get fancy 3D-style
264 scroll bars, even without LessTif/Motif, if you have the Xaw3d library
265 installed (see "Image support libraries" above for Xaw3d
268 The `--with-gcc' option specifies that the build process should
269 compile Emacs using GCC. If you don't want to use GCC, specify
270 `--with-gcc=no'. If you omit this option, `configure' will search
271 for GCC in your path, and use it if present.
273 The Emacs mail reader RMAIL is configured to be able to read mail from
274 a POP3 server by default. Versions of the POP protocol older than
275 POP3 are not supported. For Kerberos-authenticated POP add
276 `--with-kerberos', for Hesiod support add `--with-hesiod'. While POP3
277 is always enabled, whether Emacs actually uses POP is controlled by
278 individual users--see the Rmail chapter of the Emacs manual.
280 For image support you may have to download, build, and install the
281 appropriate image support libraries for image types other than XBM and
282 PBM, see the list of URLs in "ADDITIONAL DISTRIBUTION FILES" above.
283 (Note that PNG support requires libz in addition to libpng.)
285 To disable individual types of image support in Emacs for some reason,
286 even though configure finds the libraries, you can configure with one
287 or more of these options:
289 --without-xpm for XPM image support
290 --without-jpeg for JPEG image support
291 --without-tiff for TIFF image support
292 --without-gif for GIF image support
293 --without-png for PNG image support
295 Use --without-toolkit-scroll-bars to disable LessTif/Motif or Xaw3d
296 scroll bars. --without-xim disables the use of X Input Methods, and
297 --disable-largefile omits support for files larger than 2GB on systems
300 The `--prefix=PREFIXDIR' option specifies where the installation process
301 should put emacs and its data files. This defaults to `/usr/local'.
302 - Emacs (and the other utilities users run) go in PREFIXDIR/bin
303 (unless the `--exec-prefix' option says otherwise).
304 - The architecture-independent files go in PREFIXDIR/share/emacs/VERSION
305 (where VERSION is the version number of Emacs, like `19.27').
306 - The architecture-dependent files go in
307 PREFIXDIR/libexec/emacs/VERSION/CONFIGURATION
308 (where CONFIGURATION is the configuration name, like mips-dec-ultrix4.2),
309 unless the `--exec-prefix' option says otherwise.
311 The `--exec-prefix=EXECDIR' option allows you to specify a separate
312 portion of the directory tree for installing architecture-specific
313 files, like executables and utility programs. If specified,
314 - Emacs (and the other utilities users run) go in EXECDIR/bin, and
315 - The architecture-dependent files go in
316 EXECDIR/libexec/emacs/VERSION/CONFIGURATION.
317 EXECDIR/bin should be a directory that is normally in users' PATHs.
319 For example, the command
321 ./configure mips-dec-ultrix --with-x11
323 configures Emacs to build for a DECstation running Ultrix, with
324 support for the X11 window system.
326 `configure' doesn't do any compilation or installation
327 itself. It just creates the files that influence those things:
328 `./Makefile', `lib-src/Makefile', `oldXMenu/Makefile',
329 `lwlib/Makefile', `src/Makefile', and `./src/config.h'. For details
330 on exactly what it does, see the section called `CONFIGURATION BY
333 When it is done, `configure' prints a description of what it did and
334 creates a shell script `config.status' which, when run, recreates the
335 same configuration. If `configure' exits with an error after
336 disturbing the status quo, it removes `config.status'. `configure'
337 also creates a file `config.cache' that saves the results of its tests
338 to make reconfiguring faster, and a file `config.log' containing compiler
339 output (useful mainly for debugging `configure'). You can give
340 `configure' the option `--cache-file=FILE' to use the results of the
341 tests in FILE instead of `config.cache'. Set FILE to `/dev/null' to
342 disable caching, for debugging `configure'.
344 If the description of the system configuration printed by `configure'
345 is not right, or if it claims some of the fatures or libraries are not
346 available when you know they are, look at the `config.log' file for
347 the trace of the failed tests performed by `configure' to check
348 whether these features are supported. Typically, some test fails
349 because the compiler cannot find some function in the system
350 libraries, or some macro-processor definition in the system headers.
352 Some tests might fail because the compiler should look in special
353 directories for some header files, or link against optional
354 directories, or use special compilation options. You can force
355 `configure' and the build process which follows it to do that by
356 setting the variables CPPFLAGS, CFLAGS, LDFLAGS, LIBS, and CC before
357 running `configure'. CPPFLAGS lists the options passed to the
358 preprocessor, CFLAGS are compilation options, LDFLAGS are options used
359 when linking, LIBS are libraries to link against, and CC is the
360 command which invokes the compiler.
362 Here's an example of a `configure' invocation which uses these
365 CPPFLAGS='-I/foo/myinclude' LDFLAGS='-L/bar/mylib' \
366 CFLAGS='-O3' LIBS='-lfoo -lbar' ./configure
368 (this is all one long line). This tells `configure' to instruct the
369 preprocessor to look in the `/foo/myinclude' directory for header
370 files (in addition to the standard directories), instruct the linker
371 to look in `/bar/mylib' for libraries, pass the -O3 optimization
372 switch to the compiler, and link against libfoo.a and libbar.a
373 libraries in addition to the standard ones.
375 The work of `configure' can be done by editing various files in the
376 distribution, but using `configure' is easier. See the section called
377 "CONFIGURATION BY HAND" below if you want to do the configuration
380 3b) To build in a separate directory, go to that directory
381 and run the program `configure' as follows:
383 SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
385 SOURCE-DIR refers to the top-level Emacs source directory which is
386 where Emacs's configure script is located. `configure' looks for the
387 Emacs source code in the directory that `configure' is in.
389 To build in a separate directory, you must use a version of `make'
390 that supports the `VPATH' variable, such as GNU `make'.
392 3c) Some people try to build in a separate directory by filling
393 it full of symlinks to the files in the real source directory.
394 If you do that, `make all' does work, but `make install' fails:
395 it copies the symbolic links rather than the actual files.
397 As far as is known, there is no particular reason to use
398 a directory full of links rather than use the standard GNU
399 facilities to build in a separate directory (see 3b above).
401 4) Look at `./lisp/paths.el'; if some of those values are not right
402 for your system, set up the file `./lisp/site-init.el' with Emacs
403 Lisp code to override them; it is not a good idea to edit paths.el
404 itself. YOU MUST USE THE LISP FUNCTION `setq' TO ASSIGN VALUES,
405 rather than `defvar', as used by `./lisp/paths.el'. For example,
407 (setq news-inews-program "/usr/bin/inews")
409 is how you would override the default value of the variable
410 news-inews-program (which is "/usr/local/inews").
412 Before you override a variable this way, *look at the value* that the
413 variable gets by default! Make sure you know what kind of value the
414 variable should have. If you don't pay attention to what you are
415 doing, you'll make a mistake.
417 5) Put into `./lisp/site-init.el' or `./lisp/site-load.el' any Emacs
418 Lisp code you want Emacs to load before it is dumped out. Use
419 site-load.el for additional libraries if you arrange for their
420 documentation strings to be in the etc/DOC file (see
421 src/Makefile.in if you wish to figure out how to do that). For all
422 else, use site-init.el. Do not load byte-compiled code which
423 was build with a non-nil value of `byte-compile-dynamic'.
425 If you set load-path to a different value in site-init.el or
426 site-load.el, Emacs will use *precisely* that value when it starts up
427 again. If you do this, you are on your own!
429 Note that, on some systems, the code you place in site-init.el must
430 not use expand-file-name or any other function which may look
431 something up in the system's password and user information database.
432 See `./etc/PROBLEMS' for more details on which systems this affects.
434 The `site-*.el' files are nonexistent in the distribution. You do not
435 need to create them if you have nothing to put in them.
437 6) Refer to the file `./etc/TERMS' for information on fields you may
438 wish to add to various termcap entries. The files `./etc/termcap.ucb'
439 and `./etc/termcap.dat' may already contain appropriately-modified
442 7) Run `make' in the top directory of the Emacs distribution to finish
443 building Emacs in the standard way. The final executable file is
444 named `src/emacs'. You can execute this file "in place" without
445 copying it, if you wish; then it automatically uses the sibling
446 directories ../lisp, ../lib-src, ../info.
448 Or you can "install" the executable and the other Emacs into their
449 installed locations, with `make install'. By default, Emacs's files
450 are installed in the following directories:
452 `/usr/local/bin' holds the executable programs users normally run -
453 `emacs', `etags', `ctags', `b2m', `emacsclient',
456 `/usr/local/share/emacs/VERSION/lisp' holds the Emacs Lisp library;
457 `VERSION' stands for the number of the Emacs version
458 you are installing, like `18.59' or `19.27'. Since the
459 Lisp library changes from one version of Emacs to
460 another, including the version number in the path
461 allows you to have several versions of Emacs installed
462 at the same time; in particular, you don't have to
463 make Emacs unavailable while installing a new version.
465 `/usr/local/share/emacs/VERSION/site-lisp' holds the local Emacs Lisp
466 files installed for Emacs version VERSION only.
468 `/usr/local/share/emacs/site-lisp' holds the local Emacs Lisp
469 files installed for all Emacs versions.
471 When Emacs is installed, it searches for its Lisp files
472 in `/usr/local/share/emacs/VERSION/site-lisp', then in
473 `/usr/local/share/emacs/site-lisp', and finally in
474 `/usr/local/share/emacs/VERSION/lisp'.
476 `/usr/local/share/emacs/VERSION/etc' holds the Emacs tutorial, the DOC
477 file, the `yow' database, and other
478 architecture-independent files Emacs might need while
479 running. VERSION is as specified for `.../lisp'.
481 `/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME' contains executable
482 programs used by Emacs that users are not expected to
484 `VERSION' is the number of the Emacs version you are
485 installing, and `CONFIGURATION-NAME' is the argument
486 you gave to the `configure' program to identify the
487 architecture and operating system of your machine,
488 like `mips-dec-ultrix' or `sparc-sun-sunos'. Since
489 these files are specific to the version of Emacs,
490 operating system, and architecture in use, including
491 the configuration name in the path allows you to have
492 several versions of Emacs for any mix of machines and
493 operating systems installed at the same time; this is
494 useful for sites at which different kinds of machines
495 share the file system Emacs is installed on.
497 `/usr/local/info' holds the on-line documentation for Emacs, known as
498 "info files". Many other GNU programs are documented
499 using info files as well, so this directory stands
500 apart from the other, Emacs-specific directories.
502 `/usr/local/man/man1' holds the man pages for the programs installed
505 If these directories are not what you want, you can specify where to
506 install Emacs's libraries and data files or where Emacs should search
507 for its Lisp files by giving values for `make' variables as part of
508 the command. See the section below called `MAKE VARIABLES' for more
511 8) Check the file `dir' in your site's info directory (usually
512 /usr/local/info) to make sure that it has a menu entry for the Emacs
515 9) If your system uses lock files to interlock access to mailer inbox files,
516 then you might need to make the movemail program setuid or setgid
517 to enable it to write the lock files. We believe this is safe.
519 10) You are done! You can remove executables and object files from
520 the build directory by typing `make clean'. To also remove the files
521 that `configure' created (so you can compile Emacs for a different
522 configuration), type `make distclean'. If you don't need some, or all
523 of the input methods from the Leim package, you can remove the
524 unneeded files in the leim/quail, leim/skk, and leim/skk-dic
525 subdirectories of your site's lisp directory (usually
526 /usr/local/share/emacs/VERSION/).
532 You can change where the build process installs Emacs and its data
533 files by specifying values for `make' variables as part of the `make'
534 command line. For example, if you type
536 make install bindir=/usr/local/gnubin
538 the `bindir=/usr/local/gnubin' argument indicates that the Emacs
539 executable files should go in `/usr/local/gnubin', not
542 Here is a complete list of the variables you may want to set.
544 `bindir' indicates where to put executable programs that users can
545 run. This defaults to /usr/local/bin.
547 `datadir' indicates where to put the architecture-independent
548 read-only data files that Emacs refers to while it runs; it
549 defaults to /usr/local/share. We create the following
550 subdirectories under `datadir':
551 - `emacs/VERSION/lisp', containing the Emacs Lisp library, and
552 - `emacs/VERSION/etc', containing the Emacs tutorial, the DOC
553 file, and the `yow' database.
554 `VERSION' is the number of the Emacs version you are installing,
555 like `18.59' or `19.0'. Since these files vary from one version
556 of Emacs to another, including the version number in the path
557 allows you to have several versions of Emacs installed at the
558 same time; this means that you don't have to make Emacs
559 unavailable while installing a new version.
561 `libexecdir' indicates where to put architecture-specific data files that
562 Emacs refers to as it runs; it defaults to `/usr/local/libexec'.
563 We create the following subdirectories under `libexecdir':
564 - `emacs/VERSION/CONFIGURATION-NAME', containing executable
565 programs used by Emacs that users are not expected to run
567 `VERSION' is the number of the Emacs version you are installing,
568 and `CONFIGURATION-NAME' is the argument you gave to the
569 `configure' program to identify the architecture and operating
570 system of your machine, like `mips-dec-ultrix' or
571 `sparc-sun-sunos'. Since these files are specific to the version
572 of Emacs, operating system, and architecture in use, including
573 the configuration name in the path allows you to have several
574 versions of Emacs for any mix of machines and operating systems
575 installed at the same time; this is useful for sites at which
576 different kinds of machines share the file system Emacs is
579 `infodir' indicates where to put the info files distributed with
580 Emacs; it defaults to `/usr/local/info'.
582 `mandir' indicates where to put the man pages for Emacs and its
583 utilities (like `etags'); it defaults to
584 `/usr/local/man/man1'.
586 `manext' gives the extension the man pages should be installed with.
587 It should contain a period, followed by the appropriate
588 digit. It defaults to `.1'. For example given the default
589 values for `mandir' and `manext', the Emacs man page would be
590 installed as `/usr/local/man/man1/emacs.1'.
592 `prefix' doesn't give a path for any specific part of Emacs; instead,
593 its value is used to determine the defaults for all the
594 architecture-independent path variables - `datadir',
595 `sharedstatedir', `infodir', and `mandir'. Its default value is
596 `/usr/local'; the other variables add on `lib' or `man' to it
599 For example, suppose your site generally places GNU software
600 under `/usr/users/software/gnusoft' instead of `/usr/local'.
602 `prefix=/usr/users/software/gnusoft'
603 in the arguments to `make', you can instruct the build process
604 to place all of the Emacs data files in the appropriate
605 directories under that path.
607 `exec_prefix' serves the same purpose as `prefix', but instead
608 determines the default values for the architecture-dependent
609 path variables - `bindir' and `libexecdir'.
611 The above variables serve analogous purposes in the makefiles for all
612 GNU software; this variable is specific to Emacs.
614 `archlibdir' indicates where Emacs installs and expects the executable
615 files and other architecture-dependent data it uses while
616 running. Its default value, based on `libexecdir' (which
617 see), is `/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME'
618 (where VERSION and CONFIGURATION-NAME are as described above).
620 Remember that you must specify any variable values you need each time
621 you run `make' in the top directory. If you run `make' once to build
622 emacs, test it, and then run `make' again to install the files, you
623 must provide the same variable settings each time. To make the
624 settings persist, you can edit them into the `Makefile' in the top
625 directory, but be aware that running the `configure' program erases
626 `Makefile' and rebuilds it from `Makefile.in'.
628 The path for finding Lisp files is specified in src/paths.h,
629 a file which is generated by running configure. To change the path,
630 you can edit the definition of PATH_LOADSEARCH in that file
631 before you run `make'.
633 The top-level Makefile stores the variable settings it used in the
634 Makefiles for the subdirectories, so you don't have to specify them
635 when running make in the subdirectories.
638 CONFIGURATION BY HAND
640 Instead of running the `configure' program, you have to perform the
643 1) Copy `./src/config.in' to `./src/config.h'.
645 2) Consult `./etc/MACHINES' to see what configuration name you should
646 use for your system. Look at the code of the `configure' script to
647 see which operating system and architecture description files from
648 `src/s' and `src/m' should be used for that configuration name. Edit
649 `src/config.h', and change the two `#include' directives to include
650 the appropriate system and architecture description files.
652 2) Edit `./src/config.h' to set the right options for your system. If
653 you need to override any of the definitions in the s/*.h and m/*.h
654 files for your system and machine, do so by editing config.h, not by
655 changing the s/*.h and m/*.h files. Occasionally you may need to
656 redefine parameters used in `./lib-src/movemail.c'.
658 3) Create src/Makefile and lib-src/Makefile from the corresponding
659 `Makefile.in' files. First copy `Makefile.in' to `Makefile.c',
660 then edit in appropriate substitutions for the @...@ constructs,
661 and then copy the shell commands near the end of `configure'
662 that run cpp to construct `Makefile'.
664 4) Create `Makefile' files in various other directories
665 from the corresponding `Makefile.in' files. This isn't so hard,
666 just a matter of substitution.
668 The `configure' script is built from `configure.in' by the `autoconf'
669 program. You need version 2.0 or newer of `autoconf' to rebuild `configure'.
671 BUILDING GNU EMACS BY HAND
673 Once Emacs is configured, running `make' in the top directory performs
676 1) Run `make src/paths.h' in the top directory. This produces
677 `./src/paths.h' from the template file `./src/paths.in', changing
678 the paths to the values specified in `./Makefile'.
680 2) Go to directory `./lib-src' and run `make'. This creates
681 executables named `ctags' and `etags' and `wakeup' and `make-docfile'
682 and `digest-doc' and `test-distrib'. And others.
684 3) Go to directory `./src' and Run `make'. This refers to files in
685 the `./lisp' and `./lib-src' subdirectories using names `../lisp' and
688 This creates a file `./src/emacs' which is the runnable Emacs,
689 which has another name that contains a version number.
690 Each time you do this, that version number increments in the last place.
692 It also creates a file in `./etc' whose name is `DOC' followed by the
693 current Emacs version. This file contains documentation strings for
694 all the functions in Emacs. Each time you run make to make a new
695 emacs, a new DOC file with a new name is made. You must keep the DOC
696 file for an Emacs version as long as you keep using that Emacs
702 The steps below are done by running `make install' in the main
703 directory of the Emacs distribution.
705 1) Copy `./lisp' and its subdirectories, `./etc', and the executables
706 in `./lib-src' to their final destinations, as selected in `./src/paths.h'.
708 Strictly speaking, not all of the executables in `./lib-src' need be copied.
709 - The programs `cvtmail', `emacsserver', `fakemail', `hexl',
710 `movemail', `profile', `rcs2log', `timer', `vcdiff', `wakeup',
711 and `yow' are used by Emacs; they do need to be copied.
712 - The programs `etags', `ctags', `emacsclient', `b2m', and `rcs-checkin'
713 are intended to be run by users; they are handled below.
714 - The programs `make-docfile' and `test-distrib' were
715 used in building Emacs, and are not needed any more.
716 - The programs `digest-doc' and `sorted-doc' convert a `DOC' file into
717 a file for users to read. There is no important reason to move them.
719 2) Copy the files in `./info' to the place specified in
720 `./lisp/site-init.el' or `./lisp/paths.el'. Note that if the
721 destination directory already contains a file named `dir', you
722 probably don't want to replace it with the `dir' file in the Emacs
723 distribution. Instead, you should make sure that the existing `dir'
724 file contains an appropriate menu entry for the Emacs info.
726 3) Copy `./src/emacs' to `/usr/local/bin', or to some other directory
727 in users' search paths. `./src/emacs' has an alternate name
728 `./src/emacs-EMACSVERSION'; you may wish to make a symbolic link named
729 `/usr/local/bin/emacs' pointing to that alternate name, as an easy way
730 of installing different versions.
732 You can delete `./src/temacs'.
734 4) Copy the programs `b2m', `emacsclient', `ctags', `etags', and
735 `rcs-checkin' from `./lib-src' to `/usr/local/bin'. These programs are
736 intended for users to run.
738 5) Copy the man pages in `./etc' for emacs, ctags, and etags into the
739 appropriate man directories.
741 6) The files in the `./src' subdirectory, except for `emacs', are not
742 used by Emacs once it is built. However, it is very desirable to keep
743 the source on line for debugging.
748 See the file PROBLEMS in etc subdirectory for a list of various
749 problems sometimes encountered, and what to do about them.
752 Installation on MSDOG (a.k.a. MSDOS)
754 To install on MSDOG, you need to have the GNU C compiler for MSDOG
755 (also known as djgpp), GNU Make, rm, mv, and sed. See the remarks in
756 config.bat for more information about locations and versions. The
757 file etc/FAQ includes pointers to Internet sites where you can find
758 the necessary utilities; search for "MS-DOS". The configuration step
759 (see below) will test for these utilities and will refuse to continue
760 if any of them isn't found.
762 If you are building the MSDOG version of Emacs on an MSDOG-like system
763 which supports long file names (e.g. Windows 95), you need to make
764 sure that long file names are handled consistently both when you
765 unpack the distribution and compile it. If you intend to compile with
766 DJGPP v2.0 or later, and long file names support is enabled (LFN=y in
767 the environment), you need to unpack Emacs distribution in a way that
768 doesn't truncate the original long filenames to the DOS 8.3 namespace;
769 the easiest way to do this is to use djtar program which comes with
770 DJGPP, since it will note the LFN setting and behave accordingly.
771 DJGPP v1 doesn't support long filenames, so you must unpack Emacs with
772 a program that truncates the filenames to 8.3 naming as it extracts
773 files; again, using djtar after setting LFN=n is the recommended way.
774 You can build Emacs with LFN=n even if you use DJGPP v2, if some of
775 your tools don't support long file names: just ensure that LFN is set
776 to `n' during both unpacking and compiling.
778 (By the time you read this, you have already unpacked the Emacs
779 distribution, but if the explanations above imply that you should have
780 done it differently, it's safer to delete the directory tree created
781 by the unpacking program and unpack Emacs again, than to risk running
782 into problems during the build process.)
784 It is important to understand that the runtime support of long file
785 names by the Emacs binary is NOT affected by the LFN setting during
786 compilation; Emacs compiled with DJGPP v2.0 or later will always
787 support long file names on Windows 9X no matter what was the setting
788 of LFN at compile time. However, if you compiled with LFN disabled
789 and want to enable LFN support after Emacs was already built, you need
790 to make sure that the support files in the lisp, etc and info
791 directories are called by their original long names as found in the
792 distribution. You can do this either by renaming the files manually,
793 or by extracting them from the original distribution archive with
794 djtar after you set LFN=y in the environment.
796 To unpack Emacs with djtar, type this command:
800 (This assumes that the Emacs distribution is called `emacs.tgz' on
803 If you need to type international characters, you will need to unpack
804 the Leim distribution (see the description near the beginning of this
805 file). You unpack it from the same directory where you unpacked
806 Emacs. To unpack Leim with djtar, assuming the Leim distribution is
807 called `leim.tgz', type this command:
811 If you want to print international characters, install the intlfonts
812 distribution. For this, create a directory called `fonts' under the
813 Emacs top-level directory (usually called `emacs-XX.YY') created by
814 unpacking emacs.tgz, chdir into the directory emacs-XX.YY/fonts, and
817 djtar -x intlfonts.tgz
819 When unpacking is done, a directory called `emacs-XX.YY' will be
820 created, where XX.YY is the Emacs version. To build and install
821 Emacs, chdir to that directory and type these commands:
826 Running "config msdos" checks for several programs that are required
827 to configure and build Emacs; if one of those programs is not found,
828 CONFIG.BAT stops and prints an error message. If you have DJGPP
829 version 2.0 or 2.01, it will complain about a program called
830 DJECHO.EXE. These old versions of DJGPP shipped that program under
831 the name ECHO.EXE, so you can simply copy ECHO.EXE to DJECHO.EXE and
832 rerun CONFIG.BAT. If you have neither ECHO.EXE nor DJECHO.EXE, you
833 should be able to find them in your djdevNNN.zip archive (where NNN is
834 the DJGPP version number).
836 To install the international fonts, chdir to the intlfonts-X.Y
837 directory created when you unpacked the intlfonts distribution (X.Y is
838 the version number of the fonts' distribution), and type the following
841 make bdf INSTALLDIR=..
843 After Make finishes, you may remove the directory intlfonts-X.Y; the
844 fonts are installed into the fonts/bdf subdirectory of the top-level
845 Emacs directory, and that is where Emacs will look for them by
848 Building Emacs creates executable files in the src and lib-src
849 directories. Installing Emacs on MSDOS moves these executables to a
850 sibling directory called bin. For example, if you build in directory
851 /emacs, installing moves the executables from /emacs/src and
852 /emacs/lib-src to the directory /emacs/bin, so you can then delete the
853 subdirectories /emacs/src and /emacs/lib-src if you wish. The only
854 subdirectories you need to keep are bin, lisp, etc and info. (If you
855 installed Leim, keep the leim subdirectory, and if you installed
856 intlfonts, keep the fonts directory and all its sibdirectories as well.)
857 The bin subdirectory should be added to your PATH. The msdos
858 subdirectory includes a PIF and an icon file for Emacs which you might
859 find useful if you run Emacs under MS Windows.
861 Emacs on MSDOS finds the lisp, etc and info directories by looking in
862 ../lisp, ../etc and ../info, starting from the directory where the
863 Emacs executable was run from. You can override this by setting the
864 environment variables EMACSDATA (for the location of `etc' directory),
865 EMACSLOADPATH (for the location of `lisp' directory) and INFOPATH (for
866 the location of the `info' directory).
868 MSDOG is a not a multitasking operating system, so Emacs features such
869 as asynchronous subprocesses that depend on multitasking will not
870 work. Synchronous subprocesses do work.
872 Version 2.0 of djgpp has two bugs that affect Emacs. We've included
873 corrected versions of two files from djgpp in the msdos subdirectory:
874 is_exec.c and sigaction.c. To work around the bugs, compile these
875 files and link them into temacs. Djgpp versions 2.01 and later have
876 these bugs fixed, so upgrade if you can before building Emacs.