GNU Emacs Installation Guide
-Copyright (C) 1992, 1994, 1996, 1997, 2000, 2001, 2002, 2003, 2004,
- 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
+Copyright (C) 1992, 1994, 1996-1997, 2000-2013
Free Software Foundation, Inc.
See the end of the file for license conditions.
sections of this guide will help you do that, so please refer to those
sections if you need to.
- 1. Unpacking the Emacs 23.2 release requires about 170 MB of free
- disk space. Building Emacs uses about another 60 MB of space.
- The final installed Emacs uses about 120 MB of disk space.
+ 1. Unpacking the Emacs 24.1 release requires about 180 MB of free
+ disk space. Building Emacs uses about another 70 MB of space.
+ The final installed Emacs uses about 110 MB of disk space.
This includes the space-saving that comes from automatically
compressing the Lisp source files on installation.
name, where to find various headers and libraries, etc.
Refer to the section DETAILED BUILDING AND INSTALLATION below.
- If `configure' didn't find some (optional) image support libraries,
- such as Xpm, jpeg, etc., and you want to use them, refer to the
- subsection "Image support libraries" below.
+ If `configure' didn't find some image support libraries, such as
+ Xpm and jpeg, refer to "Image support libraries" below.
If the details printed by `configure' don't make any sense to
you, but there are no obvious errors, 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:
+ 4. Invoke the `make' program:
make
- 6. If `make' succeeds, it will build an executable program `emacs'
+ 5. 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
+ 6. 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:
You can delete the entire build directory if you do not plan to
build Emacs again, but it can be useful to keep for debugging.
+ If you want to build Emacs again with different configure options,
+ first clean the source directories:
+
+ make distclean
Note that the install automatically saves space by compressing
(provided you have the `gzip' program) those installed Lisp source (.el)
- files that have corresponding .elc versions. You may also wish
- to compress the installed Info files.
+ files that have corresponding .elc versions, as well as the Info files.
ADDITIONAL DISTRIBUTION FILES
* Complex Text Layout support libraries
-Emacs needs the optional libraries "m17n-db", "libm17n-flt", "libotf"
-to correctly display such complex scripts as Indic and Khmer.
-On some systems, particularly GNU/Linux, these libraries may be
-already 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.
-
-The sources of these libraries are available by anonymous CVS from
-cvs.m17n.org.
+On GNU and Unix systems, Emacs needs the optional libraries "m17n-db",
+"libm17n-flt", "libotf" to correctly display such complex scripts as
+Indic and Khmer, and also for scripts that require Arabic shaping
+support (Arabic and Farsi). On some systems, particularly GNU/Linux,
+these libraries may be already 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 the libraries from <http://www.nongnu.org/m17n/>.
- % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n login
- % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co m17n-db
- % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co m17n-lib
- % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co libotf
-
-For m17n-lib, if you have problems with making the whole package
-because you lack some other packages on which m17n-lib depends, try to
-configure it with the option "--without-gui".
+Note that Emacs cannot support complex scripts on a TTY, unless the
+terminal includes such a support.
* intlfonts-VERSION.tar.gz
* 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).
+Emacs needs libraries 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
+already be present or available as additional packages. 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 some of these optional libraries, and the URLs
-where they can be found (in the unlikely event that your distribution
-does not provide them):
-
- . libXaw3d http://directory.fsf.org/project/xaw3d/
- . libxpm for XPM: http://www.x.org/releases/current/src/lib/
- . libpng for PNG: http://www.libpng.org/
- . libz (for PNG): http://www.zlib.net/
- . libjpeg for JPEG: http://www.ijg.org/
- . libtiff for TIFF: http://www.libtiff.org/
- . libgif for GIF: http://sourceforge.net/projects/giflib/
-
-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', if you need to.
+download and build libraries from sources. Although none of them are
+essential for running Emacs, some are important enough that
+'configure' will report an error if they are absent from a system that
+has X11 support, unless 'configure' is specifically told to omit them.
+
+Here's a list of some of these libraries, and the URLs where they
+can be found (in the unlikely event that your distribution does not
+provide them). By default, libraries marked with an X are required if
+X11 is being used.
+
+ libXaw3d http://directory.fsf.org/project/xaw3d/
+ X libxpm for XPM: http://www.x.org/releases/current/src/lib/
+ X libpng for PNG: http://www.libpng.org/
+ libz (for PNG): http://www.zlib.net/
+ X libjpeg for JPEG: http://www.ijg.org/
+ X libtiff for TIFF: http://www.remotesensing.org/libtiff/
+ X libgif for GIF: http://sourceforge.net/projects/giflib/
+
+If you supply the appropriate --without-LIB option, 'configure' will
+omit the corresponding library from Emacs, even if that makes for a
+less-pleasant user interface. Otherwise, Emacs will configure itself
+to build with these libraries if 'configure' finds them on your
+system, and 'configure' will complain and exit if a library marked 'X'
+is not found on a system that uses X11. Use --without-LIB if your
+version of a library won't work because some routines are missing.
* Extra fonts
GNU/Linux distribution that you use, and the options that you want to
configure Emacs with. On Debian-based systems, you can install all the
packages needed to build the installed version of Emacs with a command
-like `apt-get build-dep emacs23'.
+like `apt-get build-dep emacs24'. On Red Hat systems, the
+corresponding command is `yum-builddep emacs'.
DETAILED BUILDING AND INSTALLATION:
`--with-pkg-config-prog=PATH' where PATH is the pathname to
pkg-config. Note that GTK version 2.6 or newer is required for Emacs.
+Emacs will autolaunch a D-Bus session bus, when the environment
+variable DISPLAY is set, but no session bus is running. This might be
+inconvenient for Emacs when running as daemon or running via a remote
+ssh connection. In order to completely prevent the use of D-Bus, configure
+Emacs with the options `--without-dbus --without-gconf --without-gsettings'.
+
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
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.
+PBM, see the list of URLs in "Image support libraries" above.
(Note that PNG support requires libz in addition to libpng.)
To disable individual types of image support in Emacs for some reason,
Use --without-sound to disable sound support.
+Use --without-all if you want to build a small executable with the minimal
+dependencies on external libraries, at the cost of disabling most of the
+features that are normally enabled by default. Using --without-all is
+equivalent to --without-sound --without-dbus --without-libotf
+--without-selinux --without-xft --without-gsettings --without-gnutls
+--without-rsvg --without-xml2 --without-gconf --without-imagemagick
+--without-m17n-flt --without-jpeg --without-tiff --without-gif
+--without-png --without-gpm --without-file-notification. Note that
+--without-all leaves X support enabled, and using the GTK2 or GTK3
+toolkit creates a lot of library dependencies. So if you want to
+build a small executable with very basic X support, use --without-all
+--with-x-toolkit=no. For the smallest possible executable without X,
+use --without-all --without-x. If you want to build with just a few
+features enabled, you can combine --without-all with --with-FEATURE.
+For example, you can use --without-all --with-dbus to build with DBus
+support and nothing more.
+
+Use --with-wide-int to implement Emacs values with the type 'long long',
+even on hosts where a narrower type would do. With this option, on a
+typical 32-bit host, Emacs integers have 62 bits instead of 30.
+
+Use --enable-gcc-warnings to enable compile-time checks that warn
+about possibly-questionable C code. This is intended for developers
+and is useful with GNU-compatible compilers. On a recent GNU system
+there should be no warnings; on older and on non-GNU systems the
+generated warnings may still be useful.
+
+Use --enable-link-time-optimization to enable link-time optimizer, which
+is available in GNU compiler since version 4.5.0. If your compiler is not
+GNU or older than version 4.5.0, this option does nothing. If `configure'
+can determine number of online CPUS on your system, final link-time
+optimization and code generation is executed in parallel using one job
+per each available online CPU.
+
The `--prefix=PREFIXDIR' option specifies where the installation process
should put emacs and its data files. This defaults to `/usr/local'.
- Emacs (and the other utilities users run) go in PREFIXDIR/bin
to the real source directory--there is no need, and installation will
fail.)
-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
-Lisp code to override them; it is not a good idea to edit paths.el
-itself. YOU MUST USE THE LISP FUNCTION `setq' TO ASSIGN VALUES,
-rather than `defvar', as used by `./lisp/paths.el'. For example,
+4) Put into `./lisp/site-init.el' or `./lisp/site-load.el' any Emacs
+Lisp code you want Emacs to load before it is dumped out. Use
+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. Do not load byte-compiled code which
+was built with a non-nil value of `byte-compile-dynamic'.
+
+It is not a good idea to edit the normal .el files that come with Emacs.
+Instead, use a file like site-init.el to change settings.
+
+To change the value of a variable that is already defined in Emacs,
+you should use the Lisp function `setq', not `defvar'. For example,
(setq news-inews-program "/usr/bin/inews")
variable should have. If you don't pay attention to what you are
doing, you'll make a mistake.
-5) Put into `./lisp/site-init.el' or `./lisp/site-load.el' any Emacs
-Lisp code you want Emacs to load before it is dumped out. Use
-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. Do not load byte-compiled code which
-was built 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
-again. If you do this, you are on your own!
-
The `site-*.el' files are nonexistent in the distribution. You do not
need to create them if you have nothing to put in them.
-6) Refer to the file `./etc/TERMS' for information on fields you may
+5) Refer to the file `./etc/TERMS' for information on fields you may
wish to add to various termcap entries. (This is unlikely to be necessary.)
-7) Run `make' in the top directory of the Emacs distribution to finish
+6) Run `make' in the top directory of the Emacs distribution to finish
building Emacs in the standard way. The final executable file is
named `src/emacs'. You can execute this file "in place" without
copying it, if you wish; then it automatically uses the sibling
are installed in the following directories:
`/usr/local/bin' holds the executable programs users normally run -
- `emacs', `etags', `ctags', `b2m', `emacsclient',
- `grep-changelog', and `rcs-checkin'.
+ `emacs', `etags', `ctags', `emacsclient', and
+ `grep-changelog'.
`/usr/local/share/emacs/VERSION/lisp' holds the Emacs Lisp library;
`VERSION' stands for the number of the Emacs version
the command. See the section below called `MAKE VARIABLES' for more
information on this.
-8) Check the file `dir' in your site's info directory (usually
+7) Check the file `dir' in your site's info directory (usually
/usr/local/share/info) to make sure that it has a menu entry for the
Emacs info files.
-9) If your system uses lock files to interlock access to mailer inbox files,
+8) If your system uses lock files to interlock access to mailer inbox files,
then you might need to make the movemail program setuid or setgid
to enable it to write the lock files. We believe this is safe.
-10) You are done! You can remove executables and object files from
+9) 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'. If you don't need some, or all
path variables - `bindir' and `libexecdir'.
The above variables serve analogous purposes in the makefiles for all
-GNU software; the following variable is specific to Emacs.
+GNU software; the following variables are specific to Emacs.
`archlibdir' indicates where Emacs installs and expects the executable
files and other architecture-dependent data it uses while
see), is `/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME'
(where VERSION and CONFIGURATION-NAME are as described above).
+`GZIP_PROG' is the name of the executable that compresses installed info,
+ manual, and .el files. It defaults to gzip. Setting it to
+ the empty string suppresses compression.
+
Remember that you must specify any variable values you need each time
you run `make' in the top directory. If you run `make' once to build
emacs, test it, and then run `make' again to install the files, you
1) Copy `./src/config.in' to `./src/config.h'.
-2) Consult `./etc/MACHINES' to see what configuration name you should
-use for your system. Look at the code of the `configure' script to
-see which operating system and architecture description files from
-`src/s' and `src/m' should be used for that configuration name. Edit
-`src/config.h', and change the two `#include' directives to include
-the appropriate system and architecture description files.
-
-2) Edit `./src/config.h' to set the right options for your system. If
-you need to override any of the definitions in the s/*.h and m/*.h
-files for your system and machine, do so by editing config.h, not by
-changing the s/*.h and m/*.h files.
-
-3) Create src/Makefile and lib-src/Makefile from the corresponding
-`Makefile.in' files. First copy `Makefile.in' to `Makefile.c',
-then edit in appropriate substitutions for the @...@ constructs,
-and then copy the shell commands near the end of `configure'
-that run cpp to construct `Makefile'.
-
-4) Create `Makefile' files in various other directories from the
+2) Edit `./src/config.h' to set the right options for your system.
+
+3) Create `Makefile' files in various directories from the
corresponding `Makefile.in' files. This isn't so hard, just a matter
of editing in appropriate substitutions for the @...@ constructs.
-The `configure' script is built from `configure.in' by the `autoconf'
-program. You need at least the version of autoconf specified in the
-AC_PREREQ(...) command to rebuild `configure' from `configure.in'.
+The `configure' script is built from `configure.ac' by the
+`autogen.sh' script, which checks that `autoconf' and other build
+tools are sufficiently up to date and then runs the build tools.
BUILDING GNU EMACS BY HAND
`./src/epaths.h' from the template file `./src/epaths.in', changing
the paths to the values specified in `./Makefile'.
-2) Go to directory `./lib-src' and run `make'. This creates
-executables named `ctags' and `etags' and `make-docfile' and
-`digest-doc' and `test-distrib'. And others.
+2) Go to directory `./lib' and run `make'. This creates include files
+and libraries used in later steps.
+
+3) Go to directory `./lib-src' and run `make'. This creates
+executables named `etags', `make-docfile', and others.
-3) Go to directory `./src' and run `make'. This refers to files in
-the `./lisp' and `./lib-src' subdirectories using names `../lisp' and
-`../lib-src'.
+4) Go to directory `./src' and run `make'. This refers to files in
+the `./lisp', `./lib', and `./lib-src' subdirectories using names
+`../lisp', `../lib', and `../lib-src'.
This creates a file `./src/emacs' which is the runnable Emacs,
which has another name that contains a version number.
in `./lib-src' to their final destinations, as selected in `./src/epaths.h'.
Strictly speaking, not all of the executables in `./lib-src' need be copied.
-- The programs `fakemail', `hexl', `movemail', `profile', `rcs2log',
- and `vcdiff' are used by Emacs; they do need to be copied.
-- The programs `etags', `ctags', `emacsclient', `b2m', and `rcs-checkin'
- are intended to be run by users; they are handled below.
+- The programs `hexl', `movemail', `profile', and `rcs2log'
+ are used by Emacs; they do need to be copied.
+- The programs `etags', `ctags', and `emacsclient' are intended to be
+ run by users; they are handled below.
- The programs `make-docfile' and `test-distrib' were
used in building Emacs, and are not needed any more.
-- The programs `digest-doc' and `sorted-doc' convert a `DOC' file into
- a file for users to read. There is no important reason to move them.
2) Copy the files in `./info' to the place specified in
-`./lisp/site-init.el' or `./lisp/paths.el'. Note that if the
+`./lisp/site-init.el' or `./lisp/info.el'. Note that if the
destination directory already contains a file named `dir', you
probably don't want to replace it with the `dir' file in the Emacs
distribution. Instead, you should make sure that the existing `dir'
You can delete `./src/temacs'.
-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.
+4) Copy the programs `emacsclient', `ctags', and `etags' from `./lib-src'
+to `/usr/local/bin'. These programs are intended for users to run.
5) Copy the man pages in `./doc/man' into the appropriate man directory.
HCoop / bpt / emacs.git / blobdiff