GNU Emacs Installation Guide
-Copyright (C) 1992, 1994, 1996-1997, 2000-2013
- Free Software Foundation, Inc.
+Copyright (C) 1992, 1994, 1996-1997, 2000-2014 Free Software Foundation,
+Inc.
See the end of the file for license conditions.
This file contains general information on building GNU Emacs.
For more information specific to the MS-Windows, GNUstep/Mac OS X, and
MS-DOS ports, also read the files nt/INSTALL, nextstep/INSTALL, and
-msdos/INSTALL. For information about building from a Bazaar checkout
-(rather than a release), also read the file INSTALL.BZR.
+msdos/INSTALL. For information about building from a repository checkout
+(rather than a release), also read the file INSTALL.REPO.
BASIC INSTALLATION
`src/config.h' file containing system-dependent definitions.
Running the `make' utility then builds the package for your system.
+Building Emacs requires GNU make, <http://www.gnu.org/software/make/>.
+On most systems that Emacs supports, this is the default `make' program.
+
Here's the procedure to build Emacs using `configure' on systems which
are supported by it. In some cases, if the simplified procedure fails,
you might need to use various non-default options, and maybe perform
SOURCE-DIR/configure
where SOURCE-DIR is the top-level Emacs source directory.
- This may not work unless you use GNU make.
3. When `configure' finishes, it prints several lines of details
about the system configuration. Read those details carefully
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)
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.
-
- % 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".
+you can download the libraries from <http://www.nongnu.org/m17n/>.
Note that Emacs cannot support complex scripts on a TTY, unless the
terminal includes such a support.
* 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/
+ librsvg2 for SVG: http://wiki.gnome.org/action/show/Projects/LibRsvg
+
+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
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 `gtk' (the default), `athena', or `motif' (`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 Gtk or LessTif/Motif,
-if you have the Xaw3d library installed (see "Image support libraries"
-above for Xaw3d availability).
-
-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.6 or newer is required for Emacs.
+`lucid' are synonyms for `athena'). Compiling with 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
+Gtk or Motif, if you have the Xaw3d library installed (see
+"Image support libraries" above for Xaw3d availability).
+
+You can tell configure where to search for GTK by giving it the
+argument PKG_CONFIG='/full/name/of/pkg-config'. 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
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,
--without-tiff for TIFF image support
--without-gif for GIF image support
--without-png for PNG image support
+ --without-rsvg for SVG image support
-Use --without-toolkit-scroll-bars to disable LessTif/Motif or Xaw3d
-scroll bars.
+Use --without-toolkit-scroll-bars to disable 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 --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. 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 --without-all for a smaller executable with fewer dependencies on
+external libraries, at the cost of disabling many features. Although
+--without-all disables libraries not needed for ordinary Emacs
+operation, it does enable X support, 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 --without-x --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
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.
+Use --enable-link-time-optimization to enable link-time optimizer. If
+you're using GNU compiler, this feature is supported since version 4.5.0.
+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.
+
+This option is also supported for clang. You should have GNU binutils
+with `gold' linker and plugin support, and clang with LLVMgold.so plugin.
+Read http://llvm.org/docs/GoldPlugin.html for details. Also note that
+this feature is still experimental, so prepare to build binutils and
+clang from the corresponding source code repositories.
The `--prefix=PREFIXDIR' option specifies where the installation process
should put emacs and its data files. This defaults to `/usr/local'.
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
+ ./configure \
+ CPPFLAGS='-I/foo/myinclude' LDFLAGS='-L/bar/mylib' \
+ CFLAGS='-O3' LIBS='-lfoo -lbar'
-(this is all one long line). This tells `configure' to instruct the
+(this is all one shell command). 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
For some libraries, like Gtk+, fontconfig and ALSA, `configure' uses
pkg-config to find where those libraries are installed.
If you want pkg-config to look in special directories, you have to set
-the environment variable PKG_CONFIG_PATH to point to the directories
-where the .pc-files for those libraries are.
-For example:
+PKG_CONFIG_PATH to point to the directories where the .pc-files for
+those libraries are. For example:
- PKG_CONFIG_PATH='/usr/local/alsa/lib/pkgconfig:/opt/gtk+-2.8/lib/pkgconfig' \
- ./configure
+ ./configure \
+ PKG_CONFIG_PATH='/usr/local/alsa/lib/pkgconfig:/opt/gtk+-2.8/lib/pkgconfig'
The work of `configure' can be done by editing various files in the
distribution, but using `configure' is easier. See the section called
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'.
-
-(Do not try to build in a separate directory by creating many links
-to the real source directory--there is no need, and installation will
-fail.)
+(Do not try to build in a separate directory by creating many links to
+the real source directory--there is no need, and installation will fail.)
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
variable should have. If you don't pay attention to what you are
doing, you'll make a mistake.
-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.
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 program `make-docfile' was used in building Emacs, and is
+ not needed any more.
2) Copy the files in `./info' to the place specified in
`./lisp/site-init.el' or `./lisp/info.el'. Note that if the
HCoop / bpt / emacs.git / blobdiff