mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-09-02 09:45:31 +00:00
812 lines
36 KiB
Text
812 lines
36 KiB
Text
GNU Emacs Installation Guide
|
||
Copyright (C) 1992, 1994, 1996-1997, 2000-2024 Free Software Foundation,
|
||
Inc.
|
||
See the end of the file for license conditions.
|
||
|
||
|
||
This file contains general information on building GNU Emacs. If you
|
||
are building an Emacs release tarball on a Unix or a GNU system, the
|
||
instructions in this file should be sufficient. For other
|
||
configurations, we have additional specialized files:
|
||
|
||
. INSTALL.REPO if you build from a Git checkout
|
||
. nt/INSTALL if you build for MS-Windows
|
||
. nextstep/INSTALL if you build for GNUstep/macOS
|
||
. java/INSTALL if you build for Android
|
||
. msdos/INSTALL if you build for MS-DOS
|
||
|
||
|
||
BASIC INSTALLATION
|
||
|
||
On most Unix systems, you build Emacs by first running the 'configure'
|
||
shell script. This attempts to deduce the correct values for
|
||
various system-dependent variables and features, and find the
|
||
directories where certain system headers and libraries are kept.
|
||
In a few cases, you may need to explicitly tell configure where to
|
||
find some things, or what options to use.
|
||
|
||
'configure' creates a 'Makefile' in several subdirectories, and a
|
||
'src/config.h' file containing system-dependent definitions.
|
||
Running the 'make' utility then builds the package for your system.
|
||
|
||
Building Emacs requires GNU make, <https://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
|
||
some of the steps manually. The more detailed description in the other
|
||
sections of this guide will help you do that, so please refer to those
|
||
sections if you need to.
|
||
|
||
1. Obtain and unpack the Emacs release, with commands like this:
|
||
|
||
wget https://ftp.gnu.org/gnu/emacs/emacs-VERSION.tar.xz
|
||
tar -xf emacs-VERSION.tar.xz
|
||
|
||
where VERSION is the Emacs version number.
|
||
|
||
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.
|
||
|
||
2c. If you don't have write access to the default directory where
|
||
Emacs and its data files will be installed, specify an alternative
|
||
installation directory:
|
||
|
||
./configure --prefix=/SOME/OTHER/DIRECTORY
|
||
|
||
where /SOME/OTHER/DIRECTORY is a directory writable by your user,
|
||
for example, a subdirectory of your home directory.
|
||
|
||
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 may have to pass to 'configure'
|
||
one or more options specifying the explicit machine configuration
|
||
name, where to find various headers and libraries, etc.
|
||
Refer to the section DETAILED BUILDING AND INSTALLATION 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. Invoke the 'make' program:
|
||
|
||
make
|
||
|
||
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
|
||
|
||
To test Emacs further (intended mostly to help developers):
|
||
|
||
make check
|
||
|
||
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:
|
||
|
||
make install
|
||
|
||
You are now ready to use Emacs. If you wish to conserve space,
|
||
you may remove the program binaries and object files from the
|
||
directory where you built Emacs:
|
||
|
||
make clean
|
||
|
||
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, as well as the Info files.
|
||
|
||
You can read a brief summary about common make targets:
|
||
|
||
make help
|
||
|
||
|
||
ADDITIONAL DISTRIBUTION FILES
|
||
|
||
* Complex Text Layout support libraries
|
||
|
||
On GNU and Unix systems, Emacs needs optional libraries to correctly
|
||
display such complex scripts as Indic and Khmer, and also for scripts
|
||
that require Arabic shaping support (Arabic and Farsi). If the
|
||
HarfBuzz library is installed, Emacs will build with it and use it for
|
||
this purpose. HarfBuzz is the preferred shaping engine, both on Posix
|
||
hosts and on MS-Windows, so we recommend installing it before building
|
||
Emacs. The alternative for GNU/Linux and Posix systems is to use the
|
||
"m17n-db", "libm17n-flt", and "libotf" libraries. (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. On MS-Windows, if HarfBuzz is not available, Emacs
|
||
will use the Uniscribe shaping engine that is part of the OS.
|
||
|
||
Note that Emacs cannot support complex scripts on a TTY, unless the
|
||
terminal includes such a support. However, most modern terminal
|
||
emulators, such as xterm, do support such scripts.
|
||
|
||
* 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. See also the Emacs Frequently Asked
|
||
Questions info pages "(efaq) How to add fonts" for installation
|
||
instructions.
|
||
|
||
* Image support libraries
|
||
|
||
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. 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. 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 https://directory.fsf.org/project/Xaw3d
|
||
X libxpm for XPM: https://www.x.org/releases/current/src/lib/
|
||
X libpng for PNG: http://www.libpng.org/
|
||
libz (for PNG): https://www.zlib.net/
|
||
X libjpeg for JPEG: https://www.ijg.org/
|
||
X libtiff for TIFF: http://www.simplesystems.org/libtiff/
|
||
X libgif for GIF: https://giflib.sourceforge.net/
|
||
librsvg2 for SVG: https://wiki.gnome.org/Projects/LibRsvg
|
||
libwebp for WebP: https://developers.google.com/speed/webp/
|
||
|
||
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
|
||
|
||
The Emacs distribution does not include fonts and does not install
|
||
them.
|
||
|
||
On the GNU system, Emacs supports both X fonts and local fonts
|
||
(i.e. fonts managed by the fontconfig library). If you need more
|
||
fonts than your distribution normally provides, you must install them
|
||
yourself. See <https://www.gnu.org/software/freefont/> for a large
|
||
number of free Unicode fonts.
|
||
|
||
* GNU/Linux development packages
|
||
|
||
Many GNU/Linux systems do not come with development packages by default;
|
||
they include the files that you need to run Emacs, but not those you
|
||
need to compile it. For example, to compile Emacs with support for X
|
||
and graphics libraries, you may need to install the X development
|
||
package(s), and development versions of the jpeg, png, etc. packages.
|
||
|
||
The names of the packages that you need vary according to the
|
||
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 emacs' (on older systems, replace 'emacs' with
|
||
e.g. 'emacs25'). On Red Hat-based systems, the corresponding command is
|
||
'dnf builddep emacs' (on older systems, use 'yum-builddep' instead).
|
||
|
||
On FreeBSD, the command is 'pkg install -y `pkg rquery %dn emacs-devel`'.
|
||
|
||
* Alternative window systems
|
||
|
||
If you want to use Emacs on one of the alternative window systems
|
||
available on GNU/Linux and some Unix systems, such as Wayland or
|
||
Broadway, you can build the PGTK ("Pure GTK") port of Emacs, which
|
||
utilizes the GTK+ toolkit to support those window systems. To this
|
||
end, invoke the configure script with the '--with-pgtk' option, like
|
||
this:
|
||
|
||
./configure --with-pgtk
|
||
|
||
This build is only supported with GTK+ version 3, and it is an error
|
||
to specify any other X-specific configuration option when PGTK is
|
||
enabled.
|
||
|
||
If you use exclusively X, do not use the PGTK port. There are a
|
||
number of respects in which the regular --with-x-toolkit=gtk build
|
||
works better. The PGTK port should not be considered a simple upgrade
|
||
from --with-x-toolkit=gtk.
|
||
|
||
With the PGTK build, you will be able to switch between running Emacs
|
||
on X, Wayland and Broadway using the 'GDK_BACKEND' environment
|
||
variable. GTK+ should automatically detect and use the correct value
|
||
for your system, but you can also specify it manually. For example,
|
||
to force GTK+ to run under Broadway, start Emacs like this:
|
||
|
||
GDK_BACKEND=broadway emacs ...
|
||
|
||
(where '...' denotes any further options you may want to pass to Emacs).
|
||
|
||
The GNUstep build also supports the Wayland window system. If that is
|
||
what you want, see nextstep/INSTALL.
|
||
|
||
* Native compilation of Lisp files
|
||
|
||
In addition to byte-compiling files of Lisp code, Emacs can also produce
|
||
"native code", which usually runs several times faster than the
|
||
corresponding byte-compiled code. To build Emacs with this feature,
|
||
your system must have not only GCC (the C compiler) and Binutils (the
|
||
assembler and linker) but also the 'libgccjit' shared library, which is
|
||
part of the GCC distribution. If these components are available,
|
||
building Emacs will automatically produce natively compiled Lisp code.
|
||
|
||
By default, Emacs natively compiles only pre-loaded Lisp files during
|
||
the build process; other Lisp files are natively compiled
|
||
"just-in-time", i.e., the first time they are loaded into the running
|
||
Emacs. If you want Emacs to natively compile all Lisp files during the
|
||
build ("ahead of time"), use the 'configure' option
|
||
'--with-native-compilation=aot'. If you do not want natively compiled
|
||
Lisp code even if your system satisfies the build requirements, use the
|
||
'configure' option '--with-native-compilation=no'.
|
||
|
||
DETAILED BUILDING AND INSTALLATION:
|
||
|
||
(This is for a Unix or Unix-like system. For GNUstep and macOS,
|
||
see nextstep/INSTALL. For non-ancient versions of MS Windows, see
|
||
the file nt/INSTALL. For MS-DOS and MS Windows 3.X, see msdos/INSTALL.)
|
||
|
||
1) See BASIC INSTALLATION above for getting and configuring Emacs.
|
||
|
||
2) In the unlikely event that 'configure' does not detect your system
|
||
type correctly, consult './etc/MACHINES' to see what --host, --build
|
||
options you should pass to 'configure'. That file also offers hints
|
||
for getting around some possible installation problems.
|
||
|
||
3) You can build Emacs in the top-level Emacs source directory
|
||
or in a separate directory.
|
||
|
||
3a) To build in the top-level Emacs source directory, go to that
|
||
directory and run the program 'configure' as follows:
|
||
|
||
./configure [--OPTION[=VALUE]] ...
|
||
|
||
If 'configure' cannot determine your system type, try again
|
||
specifying the proper --build, --host options 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
|
||
system has X, and arrange to use it if present.
|
||
|
||
The '--x-includes=DIR' and '--x-libraries=DIR' options tell the build
|
||
process where the compiler should look for the include files and
|
||
object libraries used with the X Window System. Normally, 'configure'
|
||
is able to find them; these options are necessary if you have your X
|
||
Window System files installed in unusual places. These options also
|
||
accept a list of directories, separated with colons.
|
||
|
||
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'). 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'.
|
||
|
||
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'.
|
||
|
||
To read email via a network protocol like IMAP or POP, you can
|
||
configure Emacs with the option '--with-mailutils', so that it always
|
||
uses the GNU Mailutils 'movemail' program to retrieve mail; this is
|
||
the default if GNU Mailutils is installed. Otherwise the Emacs build
|
||
procedure builds and installs an auxiliary 'movemail' program, a
|
||
limited and insecure substitute; when this happens, there are several
|
||
configure options such as --without-pop that provide fine-grained
|
||
control over Emacs 'movemail' construction.
|
||
|
||
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. While POP3 support is typically enabled,
|
||
whether Emacs actually uses POP3 is controlled by individual users;
|
||
see the Rmail chapter of the Emacs manual. Unless --with-mailutils is
|
||
in effect, it is a good idea to configure without POP3 support so that
|
||
users are less likely to inadvertently read email via insecure
|
||
channels. On native MS-Windows, --with-pop is the default; on other
|
||
platforms, --without-pop is the default.
|
||
|
||
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 "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,
|
||
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
|
||
--without-rsvg for SVG image support
|
||
--without-webp for WebP image support
|
||
|
||
Although ImageMagick support is disabled by default due to security
|
||
and stability concerns, you can enable it with --with-imagemagick.
|
||
|
||
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-xinput2 to disable the use of version 2 of the X Input
|
||
Extension. This disables support for touchscreens, pinch gestures,
|
||
and scroll wheels that report scroll deltas at pixel-level precision.
|
||
|
||
Use --disable-largefile to omit support for files larger than 2GB, and
|
||
--disable-year2038 to omit support for timestamps past the year 2038,
|
||
on systems which allow omitting such support. This may help when
|
||
linking Emacs to a library with an ABI that requires a particular
|
||
width for off_t or for time_t.
|
||
|
||
Use --without-sound to disable sound support.
|
||
|
||
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 D-Bus support and nothing more.
|
||
|
||
Use --with-gnutls=ifavailable to use GnuTLS if available but go ahead
|
||
and build without it if not available. This overrides Emacs's default
|
||
behavior of refusing to build if GnuTLS is absent. When X11 support
|
||
is enabled, the libraries for gif, jpeg, png, tiff, and xpm are in the
|
||
same strongly-recommended category as GnuTLS, and have similar options.
|
||
|
||
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 --with-cairo to compile Emacs with Cairo drawing.
|
||
|
||
Use --with-cairo-xcb to also utilize the Cairo XCB backend on systems
|
||
where it is available. While such a configuration is moderately
|
||
faster when running over X connections with high latency, it is likely
|
||
to crash when a new frame is created on a display connection opened
|
||
after a display connection is closed.
|
||
|
||
Use --with-modules to build Emacs with support for dynamic modules.
|
||
This needs a C compiler that supports '__attribute__ ((cleanup (...)))',
|
||
as in GCC 3.4 and later.
|
||
|
||
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, though you may prefer
|
||
configuring with --enable-gcc-warnings=warn-only so they are not
|
||
treated as errors. The default is --enable-gcc-warnings=warn-only if
|
||
it appears to be a developer build, and is --disable-gcc-warnings
|
||
otherwise.
|
||
|
||
Use --disable-silent-rules to cause 'make' to give more details about
|
||
the commands it executes. This can be helpful when debugging a build
|
||
that goes awry. 'make V=1' also enables the extra chatter.
|
||
|
||
Use --enable-link-time-optimization to enable link-time optimization.
|
||
With GCC, you need GCC 4.5.0 and later, and 'configure' arranges for
|
||
linking to be parallelized if possible. With Clang, you need GNU
|
||
binutils with the gold linker and plugin support, along with the LLVM
|
||
gold plugin <https://llvm.org/docs/GoldPlugin.html>. Link time
|
||
optimization is not the default as it tends to cause crashes and to
|
||
make Emacs slower.
|
||
|
||
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
|
||
(unless the '--exec-prefix' option says otherwise).
|
||
- The architecture-independent files go in PREFIXDIR/share/emacs/VERSION
|
||
(where VERSION is the version number of Emacs, like '23.2').
|
||
- The architecture-dependent files go in
|
||
PREFIXDIR/libexec/emacs/VERSION/CONFIGURATION
|
||
(where CONFIGURATION is the configuration name, like
|
||
i686-pc-linux-gnu), unless the '--exec-prefix' option says otherwise.
|
||
|
||
If you don't have write access to the default '/usr/local' tree, and
|
||
cannot have root access (without which "make install" will fail),
|
||
specify '--prefix=PREFIXDIR' where PREFIXDIR is a directory writable
|
||
by your user, for example your HOME directory or some subdirectory of
|
||
it.
|
||
|
||
The '--exec-prefix=EXECDIR' option allows you to specify a separate
|
||
portion of the directory tree for installing architecture-specific
|
||
files, like executables and utility programs. If specified,
|
||
- Emacs (and the other utilities users run) go in EXECDIR/bin, and
|
||
- The architecture-dependent files go in
|
||
EXECDIR/libexec/emacs/VERSION/CONFIGURATION.
|
||
EXECDIR/bin should be a directory that is normally in users' PATHs.
|
||
|
||
For example, the command
|
||
|
||
./configure --build=i386-linux-gnu --without-sound
|
||
|
||
configures Emacs to build for a 32-bit GNU/Linux distribution,
|
||
without sound support.
|
||
|
||
'configure' doesn't do any compilation or installation itself.
|
||
It just creates the files that influence those things:
|
||
'./Makefile' in the top-level directory and several subdirectories;
|
||
and './src/config.h'.
|
||
|
||
When it is done, 'configure' prints a description of what it did and
|
||
creates a shell script 'config.status' which, when run, recreates the
|
||
same configuration. If 'configure' exits with an error after
|
||
disturbing the status quo, it removes 'config.status'. 'configure'
|
||
also creates a file 'config.cache' that saves the results of its tests
|
||
to make reconfiguring faster, and a file 'config.log' containing compiler
|
||
output (useful mainly for debugging 'configure'). You can give
|
||
'configure' the option '--cache-file=FILE' to use the results of the
|
||
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 features 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, CPP and CC
|
||
before running 'configure'. CPP is the command which invokes the
|
||
preprocessor, CPPFLAGS lists the options passed to it, 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. By default, gcc is used if available.
|
||
|
||
Here's an example of a 'configure' invocation, assuming a Bourne-like
|
||
shell such as Bash, which uses these variables:
|
||
|
||
./configure \
|
||
CPPFLAGS='-I/foo/myinclude' LDFLAGS='-L/bar/mylib' \
|
||
CFLAGS='-Og' LIBS='-lfoo -lbar'
|
||
|
||
(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 -Og optimization
|
||
switch to the compiler, and link against libfoo and libbar
|
||
libraries in addition to the standard ones.
|
||
|
||
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
|
||
PKG_CONFIG_PATH to point to the directories where the .pc-files for
|
||
those libraries are. For example:
|
||
|
||
./configure \
|
||
PKG_CONFIG_PATH='/usr/local/alsa/lib/pkgconfig:/opt/gtk+-2.8/lib/pkgconfig'
|
||
|
||
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.
|
||
|
||
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")
|
||
|
||
is how you would override the default value of the variable
|
||
news-inews-program.
|
||
|
||
Before you override a variable this way, *look at the value* that the
|
||
variable gets by default! Make sure you know what kind of value the
|
||
variable should have. If you don't pay attention to what you are
|
||
doing, you'll make a mistake.
|
||
|
||
The 'site-*.el' files are nonexistent in the distribution. You do not
|
||
need to create them if you have nothing to put in them.
|
||
|
||
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.)
|
||
|
||
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 directories ../lisp,
|
||
../lib-src, ../info, ../native-lisp (if built with support for native
|
||
compilation).
|
||
|
||
If you build Emacs in a directory separate from the source directory
|
||
("out-of-tree"), run 'make' in the build directory. Then you can
|
||
execute the 'src/emacs' file under that directory "in place". However,
|
||
in this case the Emacs executable, while still using the ../lisp and
|
||
../info subdirectories of the source tree, will use the ../lib-src and
|
||
../native-lisp subdirectories from the build tree.
|
||
|
||
Or you can "install" the executable and the other files into their
|
||
installed locations, with 'make install'. By default, Emacs's files
|
||
are installed in the following directories:
|
||
|
||
'/usr/local/bin' holds the executable programs users normally run -
|
||
'emacs', 'etags', 'ctags', 'emacsclient'.
|
||
|
||
'/usr/local/share/emacs/VERSION/lisp' holds the Emacs Lisp library;
|
||
'VERSION' stands for the number of the Emacs version
|
||
you are installing, like '23.1' or '23.2'. Since the
|
||
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; in particular, you don't have to
|
||
make Emacs unavailable while installing a new version.
|
||
|
||
'/usr/local/lib/emacs/VERSION/native-lisp' holds the natively compiled
|
||
pre-loaded Emacs Lisp files. If the build used the
|
||
'configure' option '--with-native-compilation=aot', then
|
||
this directory holds all natively compiled Lisp files.
|
||
|
||
'~/.emacs.d/eln-cache/' holds the just-in-time natively compiled Lisp files.
|
||
|
||
'/usr/local/share/emacs/VERSION/etc' holds the Emacs tutorial, the DOC
|
||
file, and other architecture-independent files Emacs
|
||
might need while running.
|
||
|
||
'/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME' contains executable
|
||
programs used by Emacs that users are not expected to
|
||
run themselves.
|
||
'VERSION' is the number of the Emacs version you are
|
||
installing, and 'CONFIGURATION-NAME' is the value
|
||
deduced by the 'configure' program to identify the
|
||
architecture and operating system of your machine,
|
||
like 'i686-pc-linux-gnu' or 'sparc-sun-sunos'. Since
|
||
these files are specific to the version of Emacs,
|
||
operating system, and architecture in use, including
|
||
the configuration name in the path allows you to have
|
||
several versions of Emacs for any mix of machines and
|
||
operating systems installed at the same time; this is
|
||
useful for sites at which different kinds of machines
|
||
share the file system Emacs is installed on.
|
||
|
||
'/usr/local/share/info' holds the on-line documentation for Emacs,
|
||
known as "info files". Many other GNU programs are
|
||
documented using info files as well, so this directory
|
||
stands apart from the other, Emacs-specific directories.
|
||
|
||
'/usr/local/share/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
|
||
the command. See the section below called 'MAKE VARIABLES' for more
|
||
information on this.
|
||
|
||
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.
|
||
|
||
8) If your system uses lock files to interlock access to mailer inbox files,
|
||
and if --with-mailutils is not in effect, then you might need to
|
||
make the Emacs-specific 'movemail' program setuid or setgid in order
|
||
to enable it to write the lock files. We believe this is safe.
|
||
|
||
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'.
|
||
|
||
|
||
MAKE VARIABLES
|
||
|
||
You can change where the build process installs Emacs and its data
|
||
files by specifying values for 'make' variables as part of the 'make'
|
||
command line. For example, if you type
|
||
|
||
make install bindir=/usr/local/gnubin
|
||
|
||
the 'bindir=/usr/local/gnubin' argument indicates that the Emacs
|
||
executable files should go in '/usr/local/gnubin', not
|
||
'/usr/local/bin'.
|
||
|
||
Here is a complete list of the variables you may want to set.
|
||
|
||
'bindir' indicates where to put executable programs that users can
|
||
run. This defaults to /usr/local/bin.
|
||
|
||
'datadir' indicates where to put the architecture-independent
|
||
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/etc', containing the tutorials, DOC file, etc.
|
||
'VERSION' is the number of the Emacs version you are installing,
|
||
like '23.1' or '23.2'. Since these files vary 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.
|
||
|
||
'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.
|
||
'VERSION' is the number of the Emacs version you are installing,
|
||
and 'CONFIGURATION-NAME' is the value deduced by the
|
||
'configure' program to identify the architecture and operating
|
||
system of your machine, like 'i686-pc-linux-gnu' or 'sparc-sun-sunos'.
|
||
Since these files are specific to the version of Emacs,
|
||
operating system, and architecture in use, including the
|
||
configuration name in the path allows you to have several
|
||
versions of Emacs for any mix of machines and operating
|
||
systems installed at the same time; this is useful for sites
|
||
at which different kinds of machines share the file system
|
||
Emacs is installed on.
|
||
|
||
'infodir' indicates where to put the info files distributed with
|
||
Emacs; it defaults to '/usr/local/share/info'.
|
||
|
||
'mandir' indicates where to put the man pages for Emacs and its
|
||
utilities (like 'etags'); it defaults to
|
||
'/usr/local/share/man/man1'.
|
||
|
||
'prefix' doesn't give a path for any specific part of Emacs; instead,
|
||
its value is used to determine the defaults for all the
|
||
architecture-independent path variables - 'datadir',
|
||
'sharedstatedir', 'infodir', and 'mandir'. Its default value is
|
||
'/usr/local'; the other variables add on 'lib' or 'man' to it
|
||
by default.
|
||
|
||
For example, suppose your site generally places GNU software
|
||
under '/usr/users/software/gnusoft' instead of '/usr/local'.
|
||
By including
|
||
'prefix=/usr/users/software/gnusoft'
|
||
in the arguments to 'make', you can instruct the build process
|
||
to place all of the Emacs data files in the appropriate
|
||
directories under that path.
|
||
|
||
'exec_prefix' serves the same purpose as 'prefix', but instead
|
||
determines the default values for the architecture-dependent
|
||
path variables - 'bindir' and 'libexecdir'.
|
||
|
||
The above variables serve analogous purposes in the makefiles for all
|
||
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
|
||
running. Its default value, based on 'libexecdir' (which
|
||
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
|
||
must provide the same variable settings each time. To make the
|
||
settings persist, you can edit them into the 'Makefile' in the top
|
||
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/epaths.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.
|
||
|
||
|
||
PROBLEMS
|
||
|
||
See the file './etc/PROBLEMS' for a list of various problems sometimes
|
||
encountered, and what to do about them.
|
||
|
||
This file is part of GNU Emacs.
|
||
|
||
GNU Emacs is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
GNU Emacs is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
|