diff --git a/INSTALL b/INSTALL index 2aaa02f37d7..0682320924a 100644 --- a/INSTALL +++ b/INSTALL @@ -264,6 +264,26 @@ 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 have 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, @@ -552,13 +572,25 @@ 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. - -Or you can "install" the executable and the other files into their +6) After building Emacs, you can invoke the Emacs executable "in place", +i.e., from the directory where it was built, or you can first install it +and then invoke the installed executable. + +6a) 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). + +6b) If you built Emacs in a directory outside of the source directory +("out-of-tree"), it still uses the ../lisp and ../info directories in +the source directory (because byte-compiled Lisp files and Info files +are machine-independent), but the ../lib-src and ../native-lisp files in +the build directory (because these compiled files are +machine-dependent). + +6c) 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: @@ -574,6 +606,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/share/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.