GNU Emacs Installation Guide
-Copyright (c) 1992, 1994 Free software Foundation, Inc.
+Copyright (c) 1992, 1994, 1996, 1997, 2000, 2001, 2002, 2006
+Free software Foundation, Inc.
+See the end of the file for copying permissions.
- Permission is granted to anyone to make or distribute verbatim copies
- of this document as received, in any medium, provided that the
- copyright notice and permission notice are preserved,
- and that the distributor grants the recipient permission
- for further redistribution as permitted by this notice.
- Permission is granted to distribute modified versions
- of this document, or of portions of it,
- under the above conditions, provided also that they
- carry prominent notices stating who last changed them,
- and that any new or changed statements about the activities
- of the Free Software Foundation are approved by the Foundation.
+BASIC INSTALLATION
+
+The simplest way to build Emacs is to use the `configure' shell script
+which attempts to guess correct values for various system-dependent
+variables and features and find the directories where various system
+headers and libraries are kept. It then creates a `Makefile' in each
+subdirectory and a `config.h' file containing system-dependent
+definitions. Running the `make' utility then builds the package for
+your system.
+
+Here's the procedure to build Emacs using `configure' on systems which
+are supported by it. If this simplified procedure fails, or if you
+are using a platform such as MS-Windows, where `configure' script
+doesn't work, you might need to use various non-default options, and
+maybe perform some of the steps manually. The more detailed
+description in the rest of the sections of this guide will help you do
+that, so please refer to them if the simple procedure does not work.
+
+ 1. Make sure your system has at least 120 MB of free disk space.
+
+ 2a. `cd' to the directory where you unpacked Emacs and invoke the
+ `configure' script:
+
+ ./configure
+
+ 2b. Alternatively, create a separate directory, outside the source
+ directory, where you want to build Emacs, and invoke `configure'
+ from there:
+
+ SOURCE-DIR/configure
+ where SOURCE-DIR is the top-level Emacs source directory. This
+ may not work unless you use GNU make.
-BUILDING AND INSTALLATION:
-(This is for a Unix or Unix-like system. For MSDOS, see below;
-search for MSDOG. For Windows NT, see the file nt/INSTALL.)
+ 3. When `configure' finishes, it prints several lines of details
+ about the system configuration. Read those details carefully
+ looking for anything suspicious, such as wrong CPU and operating
+ system names, wrong places for headers or libraries, missing
+ libraries that you know are installed on your system, etc.
+
+ If you find anything wrong, you will have to pass to `configure'
+ explicit machine configuration name, and one or more options
+ which tell it where to find various headers and libraries; refer
+ to DETAILED BUILDING AND INSTALLATION section below.
+
+ If `configure' didn't find some image support libraries, such as
+ Xpm, jpeg, etc., and you want to use them refer to the subsection
+ "Image support libraries", below.
+
+ If the details printed by `configure' don't make any sense to
+ you, assume that `configure' did its job and proceed.
+
+ 4. If you need to run the `configure' script more than once (e.g.,
+ with some non-default options), always clean the source
+ directories before running `configure' again:
+
+ make distclean
+ ./configure
+
+ 5. Invoke the `make' program:
+
+ make
+
+ 6. If `make' succeeds, it will build an executable program `emacs'
+ in the `src' directory. You can try this program, to make sure
+ it works:
+
+ src/emacs -q
+
+ 7. Assuming that the program `src/emacs' starts and displays its
+ opening screen, you can install the program and its auxiliary
+ files into their installation directories:
+
+ make install
+
+ You are now ready to use Emacs. If you wish to conserve disk space,
+ you may remove the program binaries and object files from the
+ directory where you built Emacs:
+
+ make clean
+
+ You can also save some space by compressing (with `gzip') Info files
+ and installed Lisp source (.el) files which have corresponding .elc
+ versions.
+
+
+ADDITIONAL DISTRIBUTION FILES
+
+* intlfonts-VERSION.tar.gz
+
+The intlfonts distribution contains X11 fonts in various encodings
+that Emacs can use to display international characters. If you see a
+non-ASCII character appear as a hollow box, that means you don't have
+a font for it. You might find one in the intlfonts distribution. If
+you do have a font for a non-ASCII character, but some characters
+don't look right, or appear improperly aligned, a font from the
+intlfonts distribution might look better.
+
+The fonts in the intlfonts distribution are also used by the ps-print
+package for printing international characters. The file
+lisp/ps-mule.el defines the *.bdf font files required for printing
+each character set.
+
+The intlfonts distribution contains its own installation instructions,
+in the intlfonts/README file.
+
+* Image support libraries
+
+Emacs needs optional libraries to be able to display images (with the
+exception of PBM and XBM images whose support is built-in).
+
+On some systems, particularly on GNU/Linux, these libraries may
+already be present or available as additional packages. Note that if
+there is a separate `dev' or `devel' package, for use at compilation
+time rather than run time, you will need that as well as the
+corresponding run time package; typically the dev package will
+contain header files and a library archive. Otherwise, you can
+download and build libraries from sources. None of them are vital for
+running Emacs; however, note that Emacs will not be able to use
+colored icons in the toolbar if XPM support is not compiled in.
+
+Here's the list of these optional libraries, and the URLs where they
+can be found:
+
+ . libXaw3d for fancy 3D-style
+ scroll bars: ftp://ftp.x.org/contrib/widgets/Xaw3d/
+ . libxpm for XPM: ftp://ftp.x.org/contrib/libraries/
+ Get version 3.4k or later, which lets Emacs
+ use its own color allocation functions.
+ . libpng for PNG: ftp://ftp.simplesystems.org/pub/libpng/png/
+ . libz (for PNG): http://www.zlib.net/
+ . libjpeg for JPEG: ftp://ftp.uu.net/graphics/jpeg/
+ Get version 6b -- 6a is reported to fail in
+ Emacs.
+ . libtiff for TIFF: http://www.libtiff.org/
+ . libungif for GIF:
+ http://sourceforge.net/projects/libungif
+ Ensure you get version 4.1.0b1 or higher of libungif -- a bug in
+ 4.1.0 can crash Emacs.
+
+Emacs will configure itself to build with these libraries if the
+`configure' script finds them on your system, unless you supply the
+appropriate --without-LIB option. In some cases, older versions of
+these libraries won't work because some routines are missing, and
+configure should avoid such old versions. If that happens, use the
+--without-LIB options to `configure'. See below for more details.
+
+* Extra fonts
+
+The Emacs distribution does not include fonts and does not install
+them. You must do that yourself.
+
+To take proper advantage of Emacs 21's mule-unicode charsets, you need
+a suitable font. For `Unicode' (ISO 10646) fonts for X, see
+<URL:http://czyborra.com/unifont/> (packaged in Debian),
+<URL:http://openlab.ring.gr.jp/efont/> (packaged in Debian). (In
+recent Debian versions, there is an extensive `misc-fixed' iso10646-1
+in the default X installation.) Perhaps also see
+<URL:http://www.cl.cam.ac.uk/%7Emgk25/ucs-fonts.html>.
+
+<URL:http://czyborra.com/charsets/> has basic fonts for Emacs's
+ISO-8859 charsets.
+
+XFree86 release 4 (from <URL:ftp://ftp.xfree86.org/pub/XFree86/> and mirrors)
+contains font support for most, if not all, of the charsets that Emacs
+currently supports, including iso10646-1 encoded fonts for use with
+the mule-unicode charsets. The font files should also be usable with
+older X releases. Note that XFree 4 contains many iso10646-1 fonts
+with minimal character repertoires, which can cause problems -- see
+etc/PROBLEMS.
+
+BDF Unicode fonts etl-unicode.tar.gz are available from
+<URL:ftp://ftp.x.org/contrib/fonts/> and
+<URL:ftp://ftp.xfree86.org/pub/mirror/X.Org/contrib/fonts/>. These
+fonts can also be used by ps-print and ps-mule to print Unicode
+characters.
+
+Finally, the Web pages <URL:http://www.nongnu.org/freefont/index.html>
+and <URL:http://www.nongnu.org/freefont/resources.html> list a large
+number of free Unicode fonts.
+
+* GNU/Linux development packages
+
+Many GNU/Linux systems do not come with development packages by
+default; they just include the files that you need to run Emacs, but
+not those you need to compile it. For example, to compile Emacs with
+X11 support, you may need to install the special `X11 development'
+package. For example, in April 2003, the package names to install
+were `XFree86-devel' and `Xaw3d-devel' on RedHat. On Debian, the
+packages necessary to build the installed version should be
+sufficient; they can be installed using `apt-get build-dep emacs21' in
+Debian 3 and above.
+
+
+DETAILED BUILDING AND INSTALLATION:
+
+(This is for a Unix or Unix-like system. For MS-DOS and Windows 3.X,
+see below; search for MSDOG. For Windows 9X, Windows ME, Windows NT,
+and Windows 2000, see the file nt/INSTALL. For the Mac, see the file
+mac/INSTALL.)
1) Make sure your system has enough swapping space allocated to handle
-a program whose pure code is 900k bytes and whose data area is at
-least 400k and can reach 8Mb or more. If the swapping space is
+a program whose pure code is 1.5 MB and whose data area is at
+least 2.8 MB and can reach 100 MB or more. If the swapping space is
insufficient, you will get an error in the command `temacs -batch -l
loadup dump', found in `./src/Makefile.in', or possibly when
running the final dumped Emacs.
-
-Building Emacs requires about 70 Mb of disk space (including the Emacs
-sources). Once installed, Emacs occupies about 35 Mb in the file
+
+Building Emacs requires about 140 MB of disk space (including the
+Emacs sources) Once installed, Emacs occupies about 77 MB in the file
system where it is installed; this includes the executable files, Lisp
libraries, miscellaneous data files, and on-line documentation. If
the building and installation take place in different directories,
-then the installation procedure momentarily requires 70+35 Mb.
+then the installation procedure momentarily requires 140+77 MB.
2) Consult `./etc/MACHINES' to see what configuration name you should
give to the `configure' program. That file offers hints for
-getting around some possible installation problems.
+getting around some possible installation problems. The file lists
+many different configurations, but only the part for your machine and
+operating system is relevant. (The list is arranged in alphabetical
+order by the vendor name.)
+
+3) You can build Emacs in the top-level Emacs source directory
+or in a separate directory.
-3) In the top directory of the Emacs distribution, run the program
-`configure' as follows:
+3a) To build in the top-level Emacs source directory, go to that
+directory and run the program `configure' as follows:
- ./configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
+ ./configure [CONFIGURATION-NAME] [--OPTION[=VALUE]] ...
The CONFIGURATION-NAME argument should be a configuration name given
-in `./etc/MACHINES'. If omitted, `configure' will try to guess your
-system type; if it cannot, you must find the appropriate configuration
-name in `./etc/MACHINES' and specify it explicitly.
+in `./etc/MACHINES', with the system version number added at the end.
+
+You should try first omitting CONFIGURATION-NAME. This way,
+`configure' will try to guess your system type. If it cannot guess,
+or if something goes wrong in building or installing Emacs this way,
+try again specifying the proper CONFIGURATION-NAME explicitly.
If you don't want X support, specify `--with-x=no'. If you omit this
option, `configure' will try to figure out for itself whether your
To get more attractive menus, you can specify an X toolkit when you
configure Emacs; use the option `--with-x-toolkit=TOOLKIT', where
-TOOLKIT is `athena' or `motif' (`yes' and `lucid' are synonyms for
-`athena'). On some systems, it does not work to use a toolkit with
-shared libraries.
+TOOLKIT is `athena', `motif' or `gtk' (`yes' and `lucid' are synonyms
+for `athena'). On some systems, it does not work to use a toolkit
+with shared libraries. A free implementation of Motif, called
+LessTif, is available from <http://www.lesstif.org>. Compiling with
+LessTif or Motif causes a standard File Selection Dialog to pop up
+when you invoke file commands with the mouse. You can get fancy
+3D-style scroll bars, even without LessTif/Motif, if you have the
+Xaw3d library installed (see "Image support libraries" above for Xaw3d
+availability).
+
+If `--with-x-toolkit=gtk' is specified, you can tell configure where
+to search for GTK by specifying `--with-pkg-config-prog=PATH' where
+PATH is the pathname to pkg-config. Note that GTK version 2.4 or
+newer is required for Emacs.
The `--with-gcc' option specifies that the build process should
compile Emacs using GCC. If you don't want to use GCC, specify
`--with-gcc=no'. If you omit this option, `configure' will search
for GCC in your path, and use it if present.
-You can build Emacs for several different machine types from a single
-source directory. To do this, you must use a version of `make' that
-supports the `VPATH' variable, such as GNU `make'. Make separate
-build directories for the different configuration types, and in each
-one, run the Emacs `configure' script. `configure' looks for the
-Emacs source code in the directory that `configure' is in.
+The Emacs mail reader RMAIL is configured to be able to read mail from
+a POP3 server by default. Versions of the POP protocol older than
+POP3 are not supported. For Kerberos-authenticated POP add
+`--with-kerberos', for Hesiod support add `--with-hesiod'. While POP3
+is always enabled, whether Emacs actually uses POP is controlled by
+individual users--see the Rmail chapter of the Emacs manual.
+
+For image support you may have to download, build, and install the
+appropriate image support libraries for image types other than XBM and
+PBM, see the list of URLs in "ADDITIONAL DISTRIBUTION FILES" above.
+(Note that PNG support requires libz in addition to libpng.)
+
+To disable individual types of image support in Emacs for some reason,
+even though configure finds the libraries, you can configure with one
+or more of these options:
+
+ --without-xpm for XPM image support
+ --without-jpeg for JPEG image support
+ --without-tiff for TIFF image support
+ --without-gif for GIF image support
+ --without-png for PNG image support
+
+Use --without-toolkit-scroll-bars to disable LessTif/Motif or Xaw3d
+scroll bars.
+
+Use --without-xim to inhibit the default use of X Input Methods. In
+this case, the X resource useXIM can be used to turn on use of XIM.
+
+Use --disable-largefile omits support for files larger than 2GB on
+systems which support that.
+
+Use --without-sound to disable sound support.
The `--prefix=PREFIXDIR' option specifies where the installation process
should put emacs and its data files. This defaults to `/usr/local'.
tests in FILE instead of `config.cache'. Set FILE to `/dev/null' to
disable caching, for debugging `configure'.
+If the description of the system configuration printed by `configure'
+is not right, or if it claims some of the fatures or libraries are not
+available when you know they are, look at the `config.log' file for
+the trace of the failed tests performed by `configure' to check
+whether these features are supported. Typically, some test fails
+because the compiler cannot find some function in the system
+libraries, or some macro-processor definition in the system headers.
+
+Some tests might fail because the compiler should look in special
+directories for some header files, or link against optional
+libraries, or use special compilation options. You can force
+`configure' and the build process which follows it to do that by
+setting the variables CPPFLAGS, CFLAGS, LDFLAGS, LIBS, and CC before
+running `configure'. CPPFLAGS lists the options passed to the
+preprocessor, CFLAGS are compilation options, LDFLAGS are options used
+when linking, LIBS are libraries to link against, and CC is the
+command which invokes the compiler.
+
+Here's an example of a `configure' invocation, assuming a Bourne-like
+shell such as Bash, which uses these variables:
+
+ CPPFLAGS='-I/foo/myinclude' LDFLAGS='-L/bar/mylib' \
+ CFLAGS='-O3' LIBS='-lfoo -lbar' ./configure
+
+(this is all one long line). This tells `configure' to instruct the
+preprocessor to look in the `/foo/myinclude' directory for header
+files (in addition to the standard directories), instruct the linker
+to look in `/bar/mylib' for libraries, pass the -O3 optimization
+switch to the compiler, and link against libfoo.a and libbar.a
+libraries in addition to the standard ones.
+
The work of `configure' can be done by editing various files in the
-distribution, but using `configure' is supposed to be simpler. See
-the section called "CONFIGURATION BY HAND" below if you want to do the
-configuration yourself.
+distribution, but using `configure' is easier. See the section called
+"CONFIGURATION BY HAND" below if you want to do the configuration
+yourself.
+
+3b) To build in a separate directory, go to that directory
+and run the program `configure' as follows:
+
+ SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
+
+SOURCE-DIR refers to the top-level Emacs source directory which is
+where Emacs's configure script is located. `configure' looks for the
+Emacs source code in the directory that `configure' is in.
+
+To build in a separate directory, you must use a version of `make'
+that supports the `VPATH' variable, such as GNU `make'.
+
+3c) Some people try to build in a separate directory by filling
+it full of symlinks to the files in the real source directory.
+If you do that, `make all' does work, but `make install' fails:
+it copies the symbolic links rather than the actual files.
+
+As far as is known, there is no particular reason to use
+a directory full of links rather than use the standard GNU
+facilities to build in a separate directory (see 3b above).
4) Look at `./lisp/paths.el'; if some of those values are not right
for your system, set up the file `./lisp/site-init.el' with Emacs
site-load.el for additional libraries if you arrange for their
documentation strings to be in the etc/DOC file (see
src/Makefile.in if you wish to figure out how to do that). For all
-else, use site-init.el.
+else, use site-init.el. Do not load byte-compiled code which
+was build with a non-nil value of `byte-compile-dynamic'.
If you set load-path to a different value in site-init.el or
site-load.el, Emacs will use *precisely* that value when it starts up
Note that, on some systems, the code you place in site-init.el must
not use expand-file-name or any other function which may look
something up in the system's password and user information database.
-See `./PROBLEMS' for more details on which systems this affects.
+See `./etc/PROBLEMS' for more details on which systems this affects.
The `site-*.el' files are nonexistent in the distribution. You do not
need to create them if you have nothing to put in them.
`/usr/local/share/emacs/VERSION/lisp' holds the Emacs Lisp library;
`VERSION' stands for the number of the Emacs version
you are installing, like `18.59' or `19.27'. Since the
- lisp library changes from one version of Emacs to
+ Lisp library changes from one version of Emacs to
another, including the version number in the path
allows you to have several versions of Emacs installed
- at the same time; this means that you don't have to
- make Emacs unavailable while installing a new
- version.
-
- Emacs searches for its lisp files in
- `/usr/local/share/emacs/site-lisp', then in this
- directory.
+ at the same time; in particular, you don't have to
+ make Emacs unavailable while installing a new version.
`/usr/local/share/emacs/VERSION/etc' holds the Emacs tutorial, the DOC
file, the `yow' database, and other
architecture-independent files Emacs might need while
running. VERSION is as specified for `.../lisp'.
-`/usr/local/com/emacs/lock' contains files indicating who is editing
- what, so Emacs can detect editing clashes between
- users.
-
`/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME' contains executable
programs used by Emacs that users are not expected to
run themselves.
`/usr/local/man/man1' holds the man pages for the programs installed
in `/usr/local/bin'.
+Any version of Emacs, whether installed or not, also looks for Lisp
+files in these directories.
+
+`/usr/local/share/emacs/VERSION/site-lisp' holds the local Emacs Lisp
+ files installed for Emacs version VERSION only.
+
+`/usr/local/share/emacs/site-lisp' holds the local Emacs Lisp
+ files installed for all Emacs versions.
+
+ When Emacs is installed, it searches for its Lisp files
+ in `/usr/local/share/emacs/VERSION/site-lisp', then in
+ `/usr/local/share/emacs/site-lisp', and finally in
+ `/usr/local/share/emacs/VERSION/lisp'.
+
If these directories are not what you want, you can specify where to
install Emacs's libraries and data files or where Emacs should search
-for its lisp files by giving values for `make' variables as part of
+for its Lisp files by giving values for `make' variables as part of
the command. See the section below called `MAKE VARIABLES' for more
information on this.
10) You are done! You can remove executables and object files from
the build directory by typing `make clean'. To also remove the files
that `configure' created (so you can compile Emacs for a different
-configuration), type `make distclean'.
+configuration), type `make distclean'. If you don't need some, or all
+of the input methods from the Leim package, you can remove the
+unneeded files in the leim subdirectories of your site's lisp
+directory (usually /usr/local/share/emacs/VERSION/).
read-only data files that Emacs refers to while it runs; it
defaults to /usr/local/share. We create the following
subdirectories under `datadir':
- - `emacs/VERSION/lisp', containing the Emacs lisp library, and
+ - `emacs/VERSION/lisp', containing the Emacs Lisp library, and
- `emacs/VERSION/etc', containing the Emacs tutorial, the DOC
file, and the `yow' database.
`VERSION' is the number of the Emacs version you are installing,
same time; this means that you don't have to make Emacs
unavailable while installing a new version.
-`sharedstatedir' indicates where to put architecture-independent data files
- that Emacs modifies while it runs; it defaults to
- /usr/local/com. We create the following
- subdirectories under `sharedstatedir':
- - `emacs/lock', containing files indicating who is editing
- what, so Emacs can detect editing clashes between
- users.
-
`libexecdir' indicates where to put architecture-specific data files that
Emacs refers to as it runs; it defaults to `/usr/local/libexec'.
We create the following subdirectories under `libexecdir':
- `emacs/VERSION/CONFIGURATION-NAME', containing executable
programs used by Emacs that users are not expected to run
- themselves.
+ themselves.
`VERSION' is the number of the Emacs version you are installing,
and `CONFIGURATION-NAME' is the argument you gave to the
`configure' program to identify the architecture and operating
path variables - `bindir' and `libexecdir'.
The above variables serve analogous purposes in the makefiles for all
-GNU software; here are some variables specific to Emacs.
-
-`lispdir' indicates where Emacs installs and expects its lisp library.
- Its default value, based on `datadir' (see above), is
- `/usr/local/share/emacs/VERSION/lisp' (where `VERSION' is as
- described above).
-
-`locallisppath' indicates where Emacs should search for lisp files
- specific to your site. It should be a colon-separated list of
- directories; Emacs checks them in order before checking
- `lispdir'. Its default value, based on `datadir' (see above),
- is `/usr/local/share/emacs/site-lisp'.
-
-`lisppath' is the complete list of directories Emacs should search for
- its lisp files; its default value is the concatenation of
- `lispdir' and `locallisppath'. It should be a colon-separated
- list of directories; Emacs checks them in the order they
- appear.
-
-`etcdir' indicates where Emacs should install and expect the rest of
- its architecture-independent data, like the tutorial, DOC
- file, and yow database. Its default value, based on `datadir'
- (which see), is `/usr/local/share/emacs/VERSION/etc'.
-
-`lockdir' indicates the directory where Emacs keeps track of its
- locking information. Its default value, based on
- `sharedstatedir' (which see), is `/usr/local/com/emacs/lock'.
+GNU software; this variable is specific to Emacs.
`archlibdir' indicates where Emacs installs and expects the executable
files and other architecture-dependent data it uses while
directory, but be aware that running the `configure' program erases
`Makefile' and rebuilds it from `Makefile.in'.
+The path for finding Lisp files is specified in src/paths.h,
+a file which is generated by running configure. To change the path,
+you can edit the definition of PATH_LOADSEARCH in that file
+before you run `make'.
+
The top-level Makefile stores the variable settings it used in the
Makefiles for the subdirectories, so you don't have to specify them
when running make in the subdirectories.
just a matter of substitution.
The `configure' script is built from `configure.in' by the `autoconf'
-program. You need version 2.0 or newer of `autoconf' to rebuild `configure'.
+program. You need version 2.51 or newer of `autoconf' to rebuild
+`configure'.
BUILDING GNU EMACS BY HAND
in `./lib-src' to their final destinations, as selected in `./src/paths.h'.
Strictly speaking, not all of the executables in `./lib-src' need be copied.
-- The programs `cvtmail', `emacsserver', `fakemail', `hexl',
+- The programs `cvtmail', `fakemail', `hexl',
`movemail', `profile', `rcs2log', `timer', `vcdiff', `wakeup',
and `yow' are used by Emacs; they do need to be copied.
- The programs `etags', `ctags', `emacsclient', `b2m', and `rcs-checkin'
distribution. Instead, you should make sure that the existing `dir'
file contains an appropriate menu entry for the Emacs info.
-3) Create a directory for Emacs to use for clash detection, named as
-indicated by the PATH_LOCK macro in `./src/paths.h'.
-
-4) Copy `./src/emacs' to `/usr/local/bin', or to some other directory
+3) Copy `./src/emacs' to `/usr/local/bin', or to some other directory
in users' search paths. `./src/emacs' has an alternate name
`./src/emacs-EMACSVERSION'; you may wish to make a symbolic link named
`/usr/local/bin/emacs' pointing to that alternate name, as an easy way
You can delete `./src/temacs'.
-5) Copy the programs `b2m', `emacsclient', `ctags', `etags', and
+4) Copy the programs `b2m', `emacsclient', `ctags', `etags', and
`rcs-checkin' from `./lib-src' to `/usr/local/bin'. These programs are
intended for users to run.
-6) Copy the man pages in `./etc' for emacs, ctags, and etags into the
+5) Copy the man pages in `./etc' for emacs, ctags, and etags into the
appropriate man directories.
-7) The files in the `./src' subdirectory, except for `emacs', are not
+6) The files in the `./src' subdirectory, except for `emacs', are not
used by Emacs once it is built. However, it is very desirable to keep
the source on line for debugging.
PROBLEMS
-See the file PROBLEMS in this directory for a list of various
+See the file PROBLEMS in etc subdirectory for a list of various
problems sometimes encountered, and what to do about them.
Installation on MSDOG (a.k.a. MSDOS)
To install on MSDOG, you need to have the GNU C compiler for MSDOG
-(also known as djgpp version 1), GNU Make, rm, mv, chmod, and sed.
-Version 2 of djgpp (to be released soon) is not yet supported. See the
-remarks in config.bat for more information about locations and versions.
-
-Some users report that running Emacs 19.29 requires dpmi memory
-management. We do not know why this is so, since 19.28 did not need
-it. If we find out what change introduced this requirement, we will
-try to eliminate it. It is possible that this problem happens only
-when there is not enough physical memory on the machine.
-
-You can find out if you have a dpmi host by running go32 (part of
-djgpp) without arguments; it will tell you if it uses dpmi memory.
-For more information about dpmi memory, consult the djgpp FAQ.
-
-To build and install Emacs, type these commands:
+(also known as djgpp), GNU Make, rm, mv, and sed. See the remarks in
+config.bat for more information about locations and versions. The
+file etc/FAQ includes pointers to Internet sites where you can find
+the necessary utilities; search for "MS-DOS". The configuration step
+(see below) will test for these utilities and will refuse to continue
+if any of them isn't found.
+
+Recompiling Lisp files in the `lisp' subdirectory using the various
+targets in the lisp/Makefile file requires additional utilities:
+`find' and `xargs' (from Findutils), `touch' (from Fileutils) GNU
+`echo' and `test' (from Sh-utils), `tr, `sort', and `uniq' (from
+Textutils), and a port of Bash. However, you should not normally need
+to run lisp/Makefile, as all the Lisp files are distributed in
+byte-compiled form as well.
+
+If you are building the MSDOG version of Emacs on an MSDOG-like system
+which supports long file names (e.g. Windows 95), you need to make
+sure that long file names are handled consistently both when you
+unpack the distribution and compile it. If you intend to compile with
+DJGPP v2.0 or later, and long file names support is enabled (LFN=y in
+the environment), you need to unpack Emacs distribution in a way that
+doesn't truncate the original long filenames to the DOS 8.3 namespace;
+the easiest way to do this is to use djtar program which comes with
+DJGPP, since it will note the LFN setting and behave accordingly.
+DJGPP v1 doesn't support long filenames, so you must unpack Emacs with
+a program that truncates the filenames to 8.3 naming as it extracts
+files; again, using djtar after setting LFN=n is the recommended way.
+You can build Emacs with LFN=n even if you use DJGPP v2, if some of
+your tools don't support long file names: just ensure that LFN is set
+to `n' during both unpacking and compiling.
+
+(By the time you read this, you have already unpacked the Emacs
+distribution, but if the explanations above imply that you should have
+done it differently, it's safer to delete the directory tree created
+by the unpacking program and unpack Emacs again, than to risk running
+into problems during the build process.)
+
+It is important to understand that the runtime support of long file
+names by the Emacs binary is NOT affected by the LFN setting during
+compilation; Emacs compiled with DJGPP v2.0 or later will always
+support long file names on Windows 9X no matter what was the setting
+of LFN at compile time. However, if you compiled with LFN disabled
+and want to enable LFN support after Emacs was already built, you need
+to make sure that the support files in the lisp, etc and info
+directories are called by their original long names as found in the
+distribution. You can do this either by renaming the files manually,
+or by extracting them from the original distribution archive with
+djtar after you set LFN=y in the environment.
+
+To unpack Emacs with djtar, type this command:
+
+ djtar -x emacs.tgz
+
+(This assumes that the Emacs distribution is called `emacs.tgz' on
+your system.)
+
+If you want to print international characters, install the intlfonts
+distribution. For this, create a directory called `fonts' under the
+Emacs top-level directory (usually called `emacs-XX.YY') created by
+unpacking emacs.tgz, chdir into the directory emacs-XX.YY/fonts, and
+type this:
+
+ djtar -x intlfonts.tgz
+
+When unpacking is done, a directory called `emacs-XX.YY' will be
+created, where XX.YY is the Emacs version. To build and install
+Emacs, chdir to that directory and type these commands:
config msdos
make install
-You may need to work around a type conflict between gmalloc.c and the
-header file djgppstd.h regarding declarations of memalign and valloc.
-Temporarily deleting those declarations from djgppstd.h while compiling
-Emacs or while compiling gmalloc.c should do it. We found out about this
-problem too late to include a more convenient fix--sorry.
-
-To save disk space, Emacs is built with the idea that you will execute
-it from the same place in the file system where you built it. As the
-/usr/local/ subtree does not exist on most MSDOG systems, the
-executables are placed in /emacs/bin/.
+Running "config msdos" checks for several programs that are required
+to configure and build Emacs; if one of those programs is not found,
+CONFIG.BAT stops and prints an error message. If you have DJGPP
+version 2.0 or 2.01, it will complain about a program called
+DJECHO.EXE. These old versions of DJGPP shipped that program under
+the name ECHO.EXE, so you can simply copy ECHO.EXE to DJECHO.EXE and
+rerun CONFIG.BAT. If you have neither ECHO.EXE nor DJECHO.EXE, you
+should be able to find them in your djdevNNN.zip archive (where NNN is
+the DJGPP version number).
+
+On Windows NT or Windows 2000, running "config msdos" might print an
+error message like "VDM has been already loaded". This is because
+those systems have a program called `redir.exe' which is incompatible
+with a program by the same name supplied with DJGPP, which is used by
+config.bat. To resolve this, move the DJGPP's `bin' subdirectory to
+the front of your PATH environment variable.
+
+To install the international fonts, chdir to the intlfonts-X.Y
+directory created when you unpacked the intlfonts distribution (X.Y is
+the version number of the fonts' distribution), and type the following
+command:
+
+ make bdf INSTALLDIR=..
+
+After Make finishes, you may remove the directory intlfonts-X.Y; the
+fonts are installed into the fonts/bdf subdirectory of the top-level
+Emacs directory, and that is where Emacs will look for them by
+default.
+
+Building Emacs creates executable files in the src and lib-src
+directories. Installing Emacs on MSDOS moves these executables to a
+sibling directory called bin. For example, if you build in directory
+/emacs, installing moves the executables from /emacs/src and
+/emacs/lib-src to the directory /emacs/bin, so you can then delete the
+subdirectories /emacs/src and /emacs/lib-src if you wish. The only
+subdirectories you need to keep are bin, lisp, etc and info. (If you
+installed intlfonts, keep the fonts directory and all its
+subdirectories as well.) The bin subdirectory should be added to your
+PATH. The msdos subdirectory includes a PIF and an icon file for
+Emacs which you might find useful if you run Emacs under MS Windows.
+
+Emacs on MSDOS finds the lisp, etc and info directories by looking in
+../lisp, ../etc and ../info, starting from the directory where the
+Emacs executable was run from. You can override this by setting the
+environment variables EMACSDATA (for the location of `etc' directory),
+EMACSLOADPATH (for the location of `lisp' directory) and INFOPATH (for
+the location of the `info' directory).
MSDOG is a not a multitasking operating system, so Emacs features such
as asynchronous subprocesses that depend on multitasking will not
work. Synchronous subprocesses do work.
+
+Version 2.0 of djgpp has two bugs that affect Emacs. We've included
+corrected versions of two files from djgpp in the msdos subdirectory:
+is_exec.c and sigaction.c. To work around the bugs, compile these
+files and link them into temacs. Djgpp versions 2.01 and later have
+these bugs fixed, so upgrade if you can before building Emacs.
+\f
+COPYING PERMISSIONS
+
+ Permission is granted to anyone to make or distribute verbatim copies
+ of this document as received, in any medium, provided that the
+ copyright notice and permission notice are preserved,
+ and that the distributor grants the recipient permission
+ for further redistribution as permitted by this notice.
+
+ Permission is granted to distribute modified versions
+ of this document, or of portions of it,
+ under the above conditions, provided also that they
+ carry prominent notices stating who last changed them,
+ and that any new or changed statements about the activities
+ of the Free Software Foundation are approved by the Foundation.