bug#70246: 30.0.50; Update INSTALL for native compilation

[Stephen Berman via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 1053 bytes --]

The INSTALL file in the Emacs sources makes no reference to native
compilation.  The attached patch is an attempt to fill this gap (but I'm
not sure about the default locations of installed natively compiled Lisp
files, since I do not install Emacs when I build and do not have a
distribution installation of Emacs built with native compilation to
check).

In GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version
 3.24.41, cairo version 1.18.0) of 2024-03-31 built on strobelfs
Repository revision: 09f381d70d8852d90cdd3c8d7e1e2786dbc61f92
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101011
System Description: Linux From Scratch r12.1-30

Configured using:
 'configure 'CFLAGS=-Og -g3' PKG_CONFIG_PATH=/opt/qt5/lib/pkgconfig'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
LCMS2 LIBSYSTEMD LIBXML2 MODULES NATIVE_COMP NOTIFY INOTIFY PDUMPER PNG
RSVG SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS WEBP X11
XDBE XIM XINPUT2 XPM GTK3 ZLIB


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: INSTALL patch --]
[-- Type: text/x-patch, Size: 3775 bytes --]

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.