Add indexes for elisp manual.
[emacs.git] / INSTALL
blob262928e63ac09e1880860f24567e303f6e19fdd8
1 GNU Emacs Installation Guide
2 Copyright (C) 1992, 1994, 1996-1997, 2000-2013
3   Free Software Foundation, Inc.
4 See the end of the file for license conditions.
7 This file contains general information on building GNU Emacs.
8 For more information specific to the MS-Windows, GNUstep/Mac OS X, and
9 MS-DOS ports, also read the files nt/INSTALL, nextstep/INSTALL, and
10 msdos/INSTALL.  For information about building from a Bazaar checkout
11 (rather than a release), also read the file INSTALL.BZR.
14 BASIC INSTALLATION
16 On most Unix systems, you build Emacs by first running the `configure'
17 shell script.  This attempts to deduce the correct values for
18 various system-dependent variables and features, and find the
19 directories where certain system headers and libraries are kept.
20 In a few cases, you may need to explicitly tell configure where to
21 find some things, or what options to use.
23 `configure' creates a `Makefile' in several subdirectories, and a
24 `src/config.h' file containing system-dependent definitions.
25 Running the `make' utility then builds the package for your system.
27 Here's the procedure to build Emacs using `configure' on systems which
28 are supported by it.  In some cases, if the simplified procedure fails,
29 you might need to use various non-default options, and maybe perform
30 some of the steps manually.  The more detailed description in the other
31 sections of this guide will help you do that, so please refer to those
32 sections if you need to.
34   1. Unpacking the Emacs 24.1 release requires about 180 MB of free
35   disk space.  Building Emacs uses about another 70 MB of space.
36   The final installed Emacs uses about 110 MB of disk space.
37   This includes the space-saving that comes from automatically
38   compressing the Lisp source files on installation.
40   2a. `cd' to the directory where you unpacked Emacs and invoke the
41       `configure' script:
43                  ./configure
45   2b. Alternatively, create a separate directory, outside the source
46       directory, where you want to build Emacs, and invoke `configure'
47       from there:
49                  SOURCE-DIR/configure
51       where SOURCE-DIR is the top-level Emacs source directory.
52       This may not work unless you use GNU make.
54   3. When `configure' finishes, it prints several lines of details
55      about the system configuration.  Read those details carefully
56      looking for anything suspicious, such as wrong CPU and operating
57      system names, wrong places for headers or libraries, missing
58      libraries that you know are installed on your system, etc.
60      If you find anything wrong, you may have to pass to `configure'
61      one or more options specifying the explicit machine configuration
62      name, where to find various headers and libraries, etc.
63      Refer to the section DETAILED BUILDING AND INSTALLATION below.
65      If `configure' didn't find some (optional) image support libraries,
66      such as Xpm, jpeg, etc., and you want to use them, refer to the
67      subsection "Image support libraries" below.
69      If the details printed by `configure' don't make any sense to
70      you, but there are no obvious errors, assume that `configure' did
71      its job and proceed.
73   4. Invoke the `make' program:
75                  make
77   5. If `make' succeeds, it will build an executable program `emacs'
78      in the `src' directory.  You can try this program, to make sure
79      it works:
81                  src/emacs -Q
83   6. Assuming that the program `src/emacs' starts and displays its
84      opening screen, you can install the program and its auxiliary
85      files into their installation directories:
87                  make install
89   You are now ready to use Emacs.  If you wish to conserve disk space,
90   you may remove the program binaries and object files from the
91   directory where you built Emacs:
93                  make clean
95   You can delete the entire build directory if you do not plan to
96   build Emacs again, but it can be useful to keep for debugging.
97   If you want to build Emacs again with different configure options,
98   first clean the source directories:
100                 make distclean
102   Note that the install automatically saves space by compressing
103   (provided you have the `gzip' program) those installed Lisp source (.el)
104   files that have corresponding .elc versions, as well as the Info files.
107 ADDITIONAL DISTRIBUTION FILES
109 * Complex Text Layout support libraries
111 On GNU and Unix systems, Emacs needs the optional libraries "m17n-db",
112 "libm17n-flt", "libotf" to correctly display such complex scripts as
113 Indic and Khmer, and also for scripts that require Arabic shaping
114 support (Arabic and Farsi).  On some systems, particularly GNU/Linux,
115 these libraries may be already present or available as additional
116 packages.  Note that if there is a separate `dev' or `devel' package,
117 for use at compilation time rather than run time, you will need that
118 as well as the corresponding run time package; typically the dev
119 package will contain header files and a library archive.  Otherwise,
120 you can download and build libraries from sources.
122 The sources of these libraries are available by anonymous CVS from
123 cvs.m17n.org.
125     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n login
126     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co m17n-db
127     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co m17n-lib
128     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/m17n co libotf
130 For m17n-lib, if you have problems with making the whole package
131 because you lack some other packages on which m17n-lib depends, try to
132 configure it with the option "--without-gui".
134 Note that Emacs cannot support complex scripts on a TTY, unless the
135 terminal includes such a support.
137 * intlfonts-VERSION.tar.gz
139 The intlfonts distribution contains X11 fonts in various encodings
140 that Emacs can use to display international characters.  If you see a
141 non-ASCII character appear as a hollow box, that means you don't have
142 a font for it.  You might find one in the intlfonts distribution.  If
143 you do have a font for a non-ASCII character, but some characters
144 don't look right, or appear improperly aligned, a font from the
145 intlfonts distribution might look better.
147 The fonts in the intlfonts distribution are also used by the ps-print
148 package for printing international characters.  The file
149 lisp/ps-mule.el defines the *.bdf font files required for printing
150 each character set.
152 The intlfonts distribution contains its own installation instructions,
153 in the intlfonts/README file.
155 * Image support libraries
157 Emacs needs optional libraries to be able to display images (with the
158 exception of PBM and XBM images whose support is built-in).
160 On some systems, particularly on GNU/Linux, these libraries may
161 already be present or available as additional packages.  Note that if
162 there is a separate `dev' or `devel' package, for use at compilation
163 time rather than run time, you will need that as well as the
164 corresponding run time package; typically the dev package will
165 contain header files and a library archive.  Otherwise, you can
166 download and build libraries from sources.  None of them are vital for
167 running Emacs; however, note that Emacs will not be able to use
168 colored icons in the toolbar if XPM support is not compiled in.
170 Here's the list of some of these optional libraries, and the URLs
171 where they can be found (in the unlikely event that your distribution
172 does not provide them):
174   . libXaw3d          http://directory.fsf.org/project/xaw3d/
175   . libxpm for XPM:   http://www.x.org/releases/current/src/lib/
176   . libpng for PNG:   http://www.libpng.org/
177   . libz (for PNG):   http://www.zlib.net/
178   . libjpeg for JPEG: http://www.ijg.org/
179   . libtiff for TIFF: http://www.libtiff.org/
180   . libgif for GIF:   http://sourceforge.net/projects/giflib/
182 Emacs will configure itself to build with these libraries if the
183 `configure' script finds them on your system, unless you supply the
184 appropriate --without-LIB option.  In some cases, older versions of
185 these libraries won't work because some routines are missing, and
186 configure should avoid such old versions.  If that happens, use the
187 --without-LIB options to `configure', if you need to.
189 * Extra fonts
191 The Emacs distribution does not include fonts and does not install
192 them.
194 On the GNU system, Emacs supports both X fonts and local fonts
195 (i.e. fonts managed by the fontconfig library).  If you need more
196 fonts than your distribution normally provides, you must install them
197 yourself.  See <URL:http://www.gnu.org/software/freefont/> for a large
198 number of free Unicode fonts.
200 * GNU/Linux development packages
202 Many GNU/Linux systems do not come with development packages by default;
203 they include the files that you need to run Emacs, but not those you
204 need to compile it.  For example, to compile Emacs with support for X
205 and graphics libraries, you may need to install the `X development'
206 package(s), and development versions of the jpeg, png, etc. packages.
208 The names of the packages that you need varies according to the
209 GNU/Linux distribution that you use, and the options that you want to
210 configure Emacs with.  On Debian-based systems, you can install all the
211 packages needed to build the installed version of Emacs with a command
212 like `apt-get build-dep emacs24'.  On Red Hat systems, the
213 corresponding command is `yum-builddep emacs'.
216 DETAILED BUILDING AND INSTALLATION:
218 (This is for a Unix or Unix-like system.  For MS-DOS and MS Windows 3.X,
219 see msdos/INSTALL.  For later versions of MS Windows, see the file
220 nt/INSTALL.  For GNUstep and Mac OS X, see nextstep/INSTALL.)
222 1) Make sure your system has enough swapping space allocated to handle
223 a program whose pure code is 1.5 MB and whose data area is at
224 least 2.8 MB and can reach 100 MB or more.  If the swapping space is
225 insufficient, you will get an error in the command `temacs -batch -l
226 loadup dump', found in `./src/Makefile.in', or possibly when
227 running the final dumped Emacs.  (This should not be an issue
228 on any recent system.)
230 Building Emacs requires about 230 MB of disk space (including the
231 Emacs sources).  Once installed, Emacs occupies about 120 MB in the file
232 system where it is installed; this includes the executable files, Lisp
233 libraries, miscellaneous data files, and on-line documentation.  If
234 the building and installation take place in different directories,
235 then the installation procedure momentarily requires 230+120 MB.
237 2) In the unlikely event that `configure' does not detect your system
238 type correctly, consult `./etc/MACHINES' to see what --host, --build
239 options you should pass to `configure'.  That file also offers hints
240 for getting around some possible installation problems.
242 3) You can build Emacs in the top-level Emacs source directory
243 or in a separate directory.
245 3a) To build in the top-level Emacs source directory, go to that
246 directory and run the program `configure' as follows:
248     ./configure [--OPTION[=VALUE]] ...
250 If `configure' cannot determine your system type, try again
251 specifying the proper --build, --host options explicitly.
253 If you don't want X support, specify `--with-x=no'.  If you omit this
254 option, `configure' will try to figure out for itself whether your
255 system has X, and arrange to use it if present.
257 The `--x-includes=DIR' and `--x-libraries=DIR' options tell the build
258 process where the compiler should look for the include files and
259 object libraries used with the X Window System.  Normally, `configure'
260 is able to find them; these options are necessary if you have your X
261 Window System files installed in unusual places.  These options also
262 accept a list of directories, separated with colons.
264 To get more attractive menus, you can specify an X toolkit when you
265 configure Emacs; use the option `--with-x-toolkit=TOOLKIT', where
266 TOOLKIT is `gtk' (the default), `athena', or `motif' (`yes' and
267 `lucid' are synonyms for `athena').  On some systems, it does not work
268 to use a toolkit with shared libraries.  A free implementation of
269 Motif, called LessTif, is available from <http://www.lesstif.org>.
270 Compiling with LessTif or Motif causes a standard File Selection
271 Dialog to pop up when you invoke file commands with the mouse.  You
272 can get fancy 3D-style scroll bars, even without Gtk or LessTif/Motif,
273 if you have the Xaw3d library installed (see "Image support libraries"
274 above for Xaw3d availability).
276 You can tell configure where to search for GTK by specifying
277 `--with-pkg-config-prog=PATH' where PATH is the pathname to
278 pkg-config.  Note that GTK version 2.6 or newer is required for Emacs.
280 Emacs will autolaunch a D-Bus session bus, when the environment
281 variable DISPLAY is set, but no session bus is running.  This might be
282 inconvenient for Emacs when running as daemon or running via a remote
283 ssh connection.  In order to completely prevent the use of D-Bus, configure
284 Emacs with the options `--without-dbus --without-gconf --without-gsettings'.
286 The Emacs mail reader RMAIL is configured to be able to read mail from
287 a POP3 server by default.  Versions of the POP protocol older than
288 POP3 are not supported.  For Kerberos-authenticated POP add
289 `--with-kerberos', for Hesiod support add `--with-hesiod'.  While POP3
290 is always enabled, whether Emacs actually uses POP is controlled by
291 individual users--see the Rmail chapter of the Emacs manual.
293 For image support you may have to download, build, and install the
294 appropriate image support libraries for image types other than XBM and
295 PBM, see the list of URLs in "ADDITIONAL DISTRIBUTION FILES" above.
296 (Note that PNG support requires libz in addition to libpng.)
298 To disable individual types of image support in Emacs for some reason,
299 even though configure finds the libraries, you can configure with one
300 or more of these options:
302   --without-xpm        for XPM image support
303   --without-jpeg       for JPEG image support
304   --without-tiff       for TIFF image support
305   --without-gif        for GIF image support
306   --without-png        for PNG image support
308 Use --without-toolkit-scroll-bars to disable LessTif/Motif or Xaw3d
309 scroll bars.
311 Use --without-xim to inhibit the default use of X Input Methods.
312 In this case, the X resource useXIM can be used to turn on use of XIM.
314 Use --disable-largefile to omit support for files larger than 2GB on
315 systems which support that.
317 Use --without-sound to disable sound support.
319 Use --without-all if you want to build a small executable with the minimal
320 dependencies on external libraries, at the cost of disabling most of the
321 features that are normally enabled by default.  Using --without-all is
322 equivalent to --without-sound --without-dbus --without-libotf
323 --without-selinux --without-xft --without-gsettings --without-gnutls
324 --without-rsvg --without-xml2 --without-gconf --without-imagemagick
325 --without-m17n-flt --without-jpeg --without-tiff --without-gif
326 --without-png --without-gpm --without-file-notification.  Note that
327 --without-all leaves X support enabled, and using the GTK2 or GTK3
328 toolkit creates a lot of library dependencies.  So if you want to
329 build a small executable with very basic X support, use --without-all
330 --with-x-toolkit=no.  For the smallest possible executable without X,
331 use --without-all --without-x.  If you want to build with just a few
332 features enabled, you can combine --without-all with --with-FEATURE.
333 For example, you can use --without-all --with-dbus to build with DBus
334 support and nothing more.
336 Use --with-wide-int to implement Emacs values with the type 'long long',
337 even on hosts where a narrower type would do.  With this option, on a
338 typical 32-bit host, Emacs integers have 62 bits instead of 30.
340 Use --enable-gcc-warnings to enable compile-time checks that warn
341 about possibly-questionable C code.  This is intended for developers
342 and is useful with GNU-compatible compilers.  On a recent GNU system
343 there should be no warnings; on older and on non-GNU systems the
344 generated warnings may still be useful.
346 Use --enable-link-time-optimization to enable link-time optimizer, which
347 is available in GNU compiler since version 4.5.0.  If your compiler is not
348 GNU or older than version 4.5.0, this option does nothing.  If `configure'
349 can determine number of online CPUS on your system, final link-time
350 optimization and code generation is executed in parallel using one job
351 per each available online CPU.
353 The `--prefix=PREFIXDIR' option specifies where the installation process
354 should put emacs and its data files.  This defaults to `/usr/local'.
355 - Emacs (and the other utilities users run) go in PREFIXDIR/bin
356   (unless the `--exec-prefix' option says otherwise).
357 - The architecture-independent files go in PREFIXDIR/share/emacs/VERSION
358   (where VERSION is the version number of Emacs, like `23.2').
359 - The architecture-dependent files go in
360   PREFIXDIR/libexec/emacs/VERSION/CONFIGURATION
361   (where CONFIGURATION is the configuration name, like
362   i686-pc-linux-gnu), unless the `--exec-prefix' option says otherwise.
364 The `--exec-prefix=EXECDIR' option allows you to specify a separate
365 portion of the directory tree for installing architecture-specific
366 files, like executables and utility programs.  If specified,
367 - Emacs (and the other utilities users run) go in EXECDIR/bin, and
368 - The architecture-dependent files go in
369   EXECDIR/libexec/emacs/VERSION/CONFIGURATION.
370 EXECDIR/bin should be a directory that is normally in users' PATHs.
372 For example, the command
374     ./configure --build=i386-linux-gnu --without-sound
376 configures Emacs to build for a 32-bit GNU/Linux distribution,
377 without sound support.
379 `configure' doesn't do any compilation or installation itself.
380 It just creates the files that influence those things:
381 `./Makefile' in the top-level directory and several subdirectories;
382 and `./src/config.h'.  For details on exactly what it does, see the
383 section called `CONFIGURATION BY HAND', below.
385 When it is done, `configure' prints a description of what it did and
386 creates a shell script `config.status' which, when run, recreates the
387 same configuration.  If `configure' exits with an error after
388 disturbing the status quo, it removes `config.status'.  `configure'
389 also creates a file `config.cache' that saves the results of its tests
390 to make reconfiguring faster, and a file `config.log' containing compiler
391 output (useful mainly for debugging `configure').  You can give
392 `configure' the option `--cache-file=FILE' to use the results of the
393 tests in FILE instead of `config.cache'.  Set FILE to `/dev/null' to
394 disable caching, for debugging `configure'.
396 If the description of the system configuration printed by `configure'
397 is not right, or if it claims some of the features or libraries are not
398 available when you know they are, look at the `config.log' file for
399 the trace of the failed tests performed by `configure' to check
400 whether these features are supported.  Typically, some test fails
401 because the compiler cannot find some function in the system
402 libraries, or some macro-processor definition in the system headers.
404 Some tests might fail because the compiler should look in special
405 directories for some header files, or link against optional
406 libraries, or use special compilation options.  You can force
407 `configure' and the build process which follows it to do that by
408 setting the variables CPPFLAGS, CFLAGS, LDFLAGS, LIBS, CPP and CC
409 before running `configure'.  CPP is the command which invokes the
410 preprocessor, CPPFLAGS lists the options passed to it, CFLAGS are
411 compilation options, LDFLAGS are options used when linking, LIBS are
412 libraries to link against, and CC is the command which invokes the
413 compiler.  By default, gcc is used if available.
415 Here's an example of a `configure' invocation, assuming a Bourne-like
416 shell such as Bash, which uses these variables:
418  CPPFLAGS='-I/foo/myinclude' LDFLAGS='-L/bar/mylib' \
419   CFLAGS='-O3' LIBS='-lfoo -lbar' ./configure
421 (this is all one long line).  This tells `configure' to instruct the
422 preprocessor to look in the `/foo/myinclude' directory for header
423 files (in addition to the standard directories), instruct the linker
424 to look in `/bar/mylib' for libraries, pass the -O3 optimization
425 switch to the compiler, and link against libfoo and libbar
426 libraries in addition to the standard ones.
428 For some libraries, like Gtk+, fontconfig and ALSA, `configure' uses
429 pkg-config to find where those libraries are installed.
430 If you want pkg-config to look in special directories, you have to set
431 the environment variable PKG_CONFIG_PATH to point to the directories
432 where the .pc-files for those libraries are.
433 For example:
435  PKG_CONFIG_PATH='/usr/local/alsa/lib/pkgconfig:/opt/gtk+-2.8/lib/pkgconfig' \
436    ./configure
438 The work of `configure' can be done by editing various files in the
439 distribution, but using `configure' is easier.  See the section called
440 "CONFIGURATION BY HAND" below if you want to do the configuration
441 yourself.
443 3b) To build in a separate directory, go to that directory
444 and run the program `configure' as follows:
446     SOURCE-DIR/configure CONFIGURATION-NAME [--OPTION[=VALUE]] ...
448 SOURCE-DIR refers to the top-level Emacs source directory which is
449 where Emacs's configure script is located.  `configure' looks for the
450 Emacs source code in the directory that `configure' is in.
452 To build in a separate directory, you must use a version of `make'
453 that supports the `VPATH' variable, such as GNU `make'.
455 (Do not try to build in a separate directory by creating many links
456 to the real source directory--there is no need, and installation will
457 fail.)
459 4) Put into `./lisp/site-init.el' or `./lisp/site-load.el' any Emacs
460 Lisp code you want Emacs to load before it is dumped out.  Use
461 site-load.el for additional libraries if you arrange for their
462 documentation strings to be in the etc/DOC file (see
463 src/Makefile.in if you wish to figure out how to do that).  For all
464 else, use site-init.el.  Do not load byte-compiled code which
465 was built with a non-nil value of `byte-compile-dynamic'.
467 It is not a good idea to edit the normal .el files that come with Emacs.
468 Instead, use a file like site-init.el to change settings.
470 To change the value of a variable that is already defined in Emacs,
471 you should use the Lisp function `setq', not `defvar'.  For example,
473      (setq news-inews-program "/usr/bin/inews")
475 is how you would override the default value of the variable
476 news-inews-program.
478 Before you override a variable this way, *look at the value* that the
479 variable gets by default!  Make sure you know what kind of value the
480 variable should have.  If you don't pay attention to what you are
481 doing, you'll make a mistake.
483 If you set load-path to a different value in site-init.el or
484 site-load.el, Emacs will use *precisely* that value when it starts up
485 again.  If you do this, you are on your own!
487 The `site-*.el' files are nonexistent in the distribution.  You do not
488 need to create them if you have nothing to put in them.
490 5) Refer to the file `./etc/TERMS' for information on fields you may
491 wish to add to various termcap entries.  (This is unlikely to be necessary.)
493 6) Run `make' in the top directory of the Emacs distribution to finish
494 building Emacs in the standard way.  The final executable file is
495 named `src/emacs'.  You can execute this file "in place" without
496 copying it, if you wish; then it automatically uses the sibling
497 directories ../lisp, ../lib-src, ../info.
499 Or you can "install" the executable and the other files into their
500 installed locations, with `make install'.  By default, Emacs's files
501 are installed in the following directories:
503 `/usr/local/bin' holds the executable programs users normally run -
504                 `emacs', `etags', `ctags', `emacsclient', and
505                 `grep-changelog'.
507 `/usr/local/share/emacs/VERSION/lisp' holds the Emacs Lisp library;
508                 `VERSION' stands for the number of the Emacs version
509                 you are installing, like `23.1' or `23.2'.  Since the
510                 Lisp library changes from one version of Emacs to
511                 another, including the version number in the path
512                 allows you to have several versions of Emacs installed
513                 at the same time; in particular, you don't have to
514                 make Emacs unavailable while installing a new version.
516 `/usr/local/share/emacs/VERSION/etc' holds the Emacs tutorial, the DOC
517                 file, and other architecture-independent files Emacs
518                 might need while running.
520 `/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME' contains executable
521                 programs used by Emacs that users are not expected to
522                 run themselves.
523                 `VERSION' is the number of the Emacs version you are
524                 installing, and `CONFIGURATION-NAME' is the value
525                 deduced by the `configure' program to identify the
526                 architecture and operating system of your machine,
527                 like `i686-pc-linux-gnu' or `sparc-sun-sunos'.  Since
528                 these files are specific to the version of Emacs,
529                 operating system, and architecture in use, including
530                 the configuration name in the path allows you to have
531                 several versions of Emacs for any mix of machines and
532                 operating systems installed at the same time; this is
533                 useful for sites at which different kinds of machines
534                 share the file system Emacs is installed on.
536 `/usr/local/share/info' holds the on-line documentation for Emacs,
537                 known as "info files".  Many other GNU programs are
538                 documented using info files as well, so this directory
539                 stands apart from the other, Emacs-specific directories.
541 `/usr/local/share/man/man1' holds the man pages for the programs installed
542                 in `/usr/local/bin'.
544 Any version of Emacs, whether installed or not, also looks for Lisp
545 files in these directories.
547 `/usr/local/share/emacs/VERSION/site-lisp' holds the local Emacs Lisp
548                 files installed for Emacs version VERSION only.
550 `/usr/local/share/emacs/site-lisp' holds the local Emacs Lisp
551                 files installed for all Emacs versions.
553                 When Emacs is installed, it searches for its Lisp files
554                 in `/usr/local/share/emacs/VERSION/site-lisp', then in
555                 `/usr/local/share/emacs/site-lisp', and finally in
556                 `/usr/local/share/emacs/VERSION/lisp'.
558 If these directories are not what you want, you can specify where to
559 install Emacs's libraries and data files or where Emacs should search
560 for its Lisp files by giving values for `make' variables as part of
561 the command.  See the section below called `MAKE VARIABLES' for more
562 information on this.
564 7) Check the file `dir' in your site's info directory (usually
565 /usr/local/share/info) to make sure that it has a menu entry for the
566 Emacs info files.
568 8) If your system uses lock files to interlock access to mailer inbox files,
569 then you might need to make the movemail program setuid or setgid
570 to enable it to write the lock files.  We believe this is safe.
572 9) You are done!  You can remove executables and object files from
573 the build directory by typing `make clean'.  To also remove the files
574 that `configure' created (so you can compile Emacs for a different
575 configuration), type `make distclean'.  If you don't need some, or all
576 of the input methods from the Leim package, you can remove the
577 unneeded files in the leim subdirectories of your site's lisp
578 directory (usually /usr/local/share/emacs/VERSION/).
582 MAKE VARIABLES
584 You can change where the build process installs Emacs and its data
585 files by specifying values for `make' variables as part of the `make'
586 command line.  For example, if you type
588     make install bindir=/usr/local/gnubin
590 the `bindir=/usr/local/gnubin' argument indicates that the Emacs
591 executable files should go in `/usr/local/gnubin', not
592 `/usr/local/bin'.
594 Here is a complete list of the variables you may want to set.
596 `bindir' indicates where to put executable programs that users can
597         run.  This defaults to /usr/local/bin.
599 `datadir' indicates where to put the architecture-independent
600         read-only data files that Emacs refers to while it runs; it
601         defaults to /usr/local/share.  We create the following
602         subdirectories under `datadir':
603         - `emacs/VERSION/lisp', containing the Emacs Lisp library, and
604         - `emacs/VERSION/etc', containing the tutorials, DOC file, etc.
605         `VERSION' is the number of the Emacs version you are installing,
606         like `23.1' or `23.2'.  Since these files vary from one version
607         of Emacs to another, including the version number in the path
608         allows you to have several versions of Emacs installed at the
609         same time; this means that you don't have to make Emacs
610         unavailable while installing a new version.
612 `libexecdir' indicates where to put architecture-specific data files that
613         Emacs refers to as it runs; it defaults to `/usr/local/libexec'.
614         We create the following subdirectories under `libexecdir':
615         - `emacs/VERSION/CONFIGURATION-NAME', containing executable
616                 programs used by Emacs that users are not expected to run
617                 themselves.
618         `VERSION' is the number of the Emacs version you are installing,
619         and `CONFIGURATION-NAME' is the value deduced by the
620         `configure' program to identify the architecture and operating
621         system of your machine, like `i686-pc-linux-gnu' or `sparc-sun-sunos'.
622         Since these files are specific to the version of Emacs,
623         operating system, and architecture in use, including the
624         configuration name in the path allows you to have several
625         versions of Emacs for any mix of machines and operating
626         systems installed at the same time; this is useful for sites
627         at which different kinds of machines share the file system
628         Emacs is installed on.
630 `infodir' indicates where to put the info files distributed with
631         Emacs; it defaults to `/usr/local/share/info'.
633 `mandir' indicates where to put the man pages for Emacs and its
634         utilities (like `etags'); it defaults to
635         `/usr/local/share/man/man1'.
637 `prefix' doesn't give a path for any specific part of Emacs; instead,
638         its value is used to determine the defaults for all the
639         architecture-independent path variables - `datadir',
640         `sharedstatedir', `infodir', and `mandir'.  Its default value is
641         `/usr/local'; the other variables add on `lib' or `man' to it
642         by default.
644         For example, suppose your site generally places GNU software
645         under `/usr/users/software/gnusoft' instead of `/usr/local'.
646         By including
647             `prefix=/usr/users/software/gnusoft'
648         in the arguments to `make', you can instruct the build process
649         to place all of the Emacs data files in the appropriate
650         directories under that path.
652 `exec_prefix' serves the same purpose as `prefix', but instead
653         determines the default values for the architecture-dependent
654         path variables - `bindir' and `libexecdir'.
656 The above variables serve analogous purposes in the makefiles for all
657 GNU software; the following variables are specific to Emacs.
659 `archlibdir' indicates where Emacs installs and expects the executable
660         files and other architecture-dependent data it uses while
661         running.  Its default value, based on `libexecdir' (which
662         see), is `/usr/local/libexec/emacs/VERSION/CONFIGURATION-NAME'
663         (where VERSION and CONFIGURATION-NAME are as described above).
665 `GZIP_PROG' is the name of the executable that compresses installed info,
666         manual, and .el files.  It defaults to gzip.  Setting it to
667         the empty string suppresses compression.
669 Remember that you must specify any variable values you need each time
670 you run `make' in the top directory.  If you run `make' once to build
671 emacs, test it, and then run `make' again to install the files, you
672 must provide the same variable settings each time.  To make the
673 settings persist, you can edit them into the `Makefile' in the top
674 directory, but be aware that running the `configure' program erases
675 `Makefile' and rebuilds it from `Makefile.in'.
677 The path for finding Lisp files is specified in src/epaths.h,
678 a file which is generated by running configure.  To change the path,
679 you can edit the definition of PATH_LOADSEARCH in that file
680 before you run `make'.
682 The top-level Makefile stores the variable settings it used in the
683 Makefiles for the subdirectories, so you don't have to specify them
684 when running make in the subdirectories.
687 CONFIGURATION BY HAND
689 This should not be necessary and is not recommended.  Instead of
690 running the `configure' program, you have to perform the following steps.
692 1) Copy `./src/config.in' to `./src/config.h'.
694 2) Edit `./src/config.h' to set the right options for your system.
696 3) Create `Makefile' files in various directories from the
697 corresponding `Makefile.in' files.  This isn't so hard, just a matter
698 of editing in appropriate substitutions for the @...@ constructs.
700 The `configure' script is built from `configure.ac' by the
701 `autogen.sh' script, which checks that `autoconf' and other build
702 tools are sufficiently up to date and then runs the build tools.
704 BUILDING GNU EMACS BY HAND
706 Once Emacs is configured, running `make' in the top directory performs
707 the following steps.
709 1) Run `make epaths-force' in the top directory.  This produces
710 `./src/epaths.h' from the template file `./src/epaths.in', changing
711 the paths to the values specified in `./Makefile'.
713 2) Go to directory `./lib' and run `make'.  This creates include files
714 and libraries used in later steps.
716 3) Go to directory `./lib-src' and run `make'.  This creates
717 executables named `etags', `make-docfile', and others.
719 4) Go to directory `./src' and run `make'.  This refers to files in
720 the `./lisp', `./lib', and `./lib-src' subdirectories using names
721 `../lisp', `../lib', and `../lib-src'.
723 This creates a file `./src/emacs' which is the runnable Emacs,
724 which has another name that contains a version number.
725 Each time you do this, that version number increments in the last place.
727 It also creates a file in `./etc' whose name is `DOC' followed by the
728 current Emacs version.  This file contains documentation strings for
729 all the functions in Emacs.  Each time you run make to make a new
730 emacs, a new DOC file with a new name is made.  You must keep the DOC
731 file for an Emacs version as long as you keep using that Emacs version.
734 INSTALLATION BY HAND
736 The steps below are done by running `make install' in the main
737 directory of the Emacs distribution.
739 1) Copy `./lisp' and its subdirectories, `./etc', and the executables
740 in `./lib-src' to their final destinations, as selected in `./src/epaths.h'.
742 Strictly speaking, not all of the executables in `./lib-src' need be copied.
743 - The programs `hexl', `movemail', `profile', and `rcs2log'
744     are used by Emacs; they do need to be copied.
745 - The programs `etags', `ctags', and `emacsclient' are intended to be
746     run by users; they are handled below.
747 - The programs `make-docfile' and `test-distrib' were
748     used in building Emacs, and are not needed any more.
750 2) Copy the files in `./info' to the place specified in
751 `./lisp/site-init.el' or `./lisp/info.el'.  Note that if the
752 destination directory already contains a file named `dir', you
753 probably don't want to replace it with the `dir' file in the Emacs
754 distribution.  Instead, you should make sure that the existing `dir'
755 file contains an appropriate menu entry for the Emacs info.
757 3) Copy `./src/emacs' to `/usr/local/bin', or to some other directory
758 in users' search paths.  `./src/emacs' has an alternate name
759 `./src/emacs-EMACSVERSION'; you may wish to make a symbolic link named
760 `/usr/local/bin/emacs' pointing to that alternate name, as an easy way
761 of installing different versions.
763 You can delete `./src/temacs'.
765 4) Copy the programs `emacsclient', `ctags', and `etags' from `./lib-src'
766 to `/usr/local/bin'.  These programs are intended for users to run.
768 5) Copy the man pages in `./doc/man' into the appropriate man directory.
770 6) The files in the `./src' subdirectory, except for `emacs', are not
771 used by Emacs once it is built.  However, it is very desirable to keep
772 the source on line for debugging.
775 PROBLEMS
777 See the file `./etc/PROBLEMS' for a list of various problems sometimes
778 encountered, and what to do about them.
780 This file is part of GNU Emacs.
782 GNU Emacs is free software: you can redistribute it and/or modify
783 it under the terms of the GNU General Public License as published by
784 the Free Software Foundation, either version 3 of the License, or
785 (at your option) any later version.
787 GNU Emacs is distributed in the hope that it will be useful,
788 but WITHOUT ANY WARRANTY; without even the implied warranty of
789 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
790 GNU General Public License for more details.
792 You should have received a copy of the GNU General Public License
793 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.