diff --git a/INSTALL b/INSTALL index 2aaa02f37d7..edc7f0699e2 100644 --- a/INSTALL +++ b/INSTALL @@ -264,6 +264,25 @@ to force GTK+ to run under Broadway, start Emacs like this: 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, when they are loaded in 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, @@ -553,10 +572,17 @@ need to create them if you have nothing to put in them. 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. +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, +running Emacs uninstalled is fully supported only when it is built in +the source tree. Or you can "install" the executable and the other files into their installed locations, with 'make install'. By default, Emacs's files @@ -574,6 +600,11 @@ are installed in the following directories: 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. + +'~/.emacs.d/eln-cache/' holds the remaining 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.