>From 8dd5b6ea56c38669bc98104ee2d6b31496624d28 Mon Sep 17 00:00:00 2001 From: Paul Eggert
Date: Tue, 23 Jul 2019 09:19:09 -0700 Subject: [PATCH] Improve pdumper doc; say unexec is deprecated Say that pdumping cannot redump unless -batch is used. Say that the traditional unexec dumping method is by default not available, and is deprecated. Don't call dump files "portable", as dump files are not any more portable than the Emacs executables themselves. Just call them "dump files". Similar, prefer "portable dumper" (since the dumper code is portable) to "portable dumping" (since the dump file is not). Be more systematic about calling them "dump files" instead of "dumped images" or whatnot. --- doc/lispref/internals.texi | 34 ++++++++++++++++++++-------------- etc/NEWS | 14 +++++++++----- etc/TODO | 6 +----- lib/fingerprint.h | 3 +-- lisp/startup.el | 4 ++-- src/alloc.c | 4 ++-- src/emacs.c | 6 +++--- src/minibuf.c | 2 +- src/pdumper.c | 10 +++++----- src/pdumper.h | 4 ++-- src/unexaix.c | 2 +- 11 files changed, 47 insertions(+), 42 deletions(-) diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 72066d34f4..f85c266ede 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -61,10 +61,10 @@ Building Emacs @table @samp @item pdump -@cindex portable dump file -Record the preloaded Lisp data in a @dfn{portable dump} file. This +@cindex dump file +Record the preloaded Lisp data in a @dfn{dump file}. This method produces an additional data file which Emacs will load at -startup. The portable dump file is usually called @file{emacs.pdmp}, +startup. The produced dump file is usually called @file{emacs.pdmp}, and is installed in the Emacs @code{exec-directory} (@pxref{Help Functions}). This method is the most preferred one, as it does not require Emacs to employ any special techniques of memory allocation, @@ -75,7 +75,7 @@ Building Emacs @cindex bootstrapping Emacs Like @samp{pdump}, but used while @dfn{bootstrapping} Emacs, when no previous Emacs binary and no @file{*.elc} byte-compiled Lisp files are -available. The produced portable dump file is usually named +available. The produced dump file is usually named @file{bootstrap-emacs.pdmp} in this case. @item dump @@ -88,6 +88,8 @@ Building Emacs dumped Emacs.) This method is also known as @dfn{unexec}, because it produces a program file from a running process, and thus is in some sense the opposite of executing a program to start a process. +Although this method was the way that Emacs traditionally saved its +state, it is now deprecated. @item bootstrap Like @samp{dump}, but used when bootstrapping Emacs with the @@ -97,11 +99,11 @@ Building Emacs @cindex preloaded Lisp files @vindex preloaded-file-list The dumped @file{emacs} executable (also called a @dfn{pure} Emacs) -is the one which is installed. If the portable dumping was used to +is the one which is installed. If the portable dumper was used to build Emacs, the @file{emacs} executable is actually an exact copy of @file{temacs}, and the corresponding @file{emacs.pdmp} file is installed as well. The variable @code{preloaded-file-list} stores a -list of the preloaded Lisp files recorded in the portable dump file or +list of the preloaded Lisp files recorded in the dump file or in the dumped Emacs executable. If you port Emacs to a new operating system, and are not able to implement dumping of any kind, then Emacs must load @file{loadup.el} each time it starts. @@ -201,15 +203,19 @@ Building Emacs @code{before-init-hook} (@pxref{Startup Summary}). @defun dump-emacs-portable to-file &optional track-referrers -This function dumps the current state of Emacs into a portable dump +This function dumps the current state of Emacs into a dump file @var{to-file}, using the @code{pdump} method. Normally, the -portable dump file is called @file{@var{emacs-name}.dmp}, where +dump file is called @file{@var{emacs-name}.dmp}, where @var{emacs-name} is the name of the Emacs executable file. The optional argument @var{track-referrers}, if non-@code{nil}, causes the -portable dumping process keep additional information to help track +portable dumper to keep additional information to help track down the provenance of object types that are not yet supported by the @code{pdump} method. +Although the portable dumper code can run on many platforms, the dump +files that it produces are not portable---they can be loaded only by +the Emacs executable that dumped them. + If you want to use this function in an Emacs that was already dumped, you must run Emacs with the @samp{-batch} option. @end defun @@ -220,20 +226,20 @@ Building Emacs @var{to-file}, using the @code{unexec} method. It takes symbols from @var{from-file} (this is normally the executable file @file{temacs}). -This function cannot be used in an Emacs that was already dumped. If -Emacs was built without @code{unexec} support, this function will not -be available. +This function cannot be used in an Emacs that was already dumped. +This function is deprecated, and by default Emacs is built without +@code{unexec} support so this function is not available. @end defun @defun pdumper-stats -If the current Emacs session restored its state from a portable dump +If the current Emacs session restored its state from a dump file, this function returns information about the dump file and the time it took to restore the Emacs state. The value is an alist @w{@code{((dumped-with-pdumper . t) (load-time . @var{time}) (dump-file-name . @var{file}))}}, where @var{file} is the name of the dump file, and @var{time} is the time in seconds it took to restore the state from the dump file. -If the current session was not restored from a portable dump file, the +If the current session was not restored from a dump file, the value is nil. @end defun diff --git a/etc/NEWS b/etc/NEWS index 5378e56bca..7fd2214582 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -92,11 +92,6 @@ and in particular better supports the Address Space Layout Randomization (ASLR) feature, a security technique used by most modern operating systems. -Portable dumping can be disabled at configure time via the configure -option '--with-dumping=unexec' (but we don't recommend that, unless -the portable dumping doesn't work on your system for some -reason---please report such systems to the Emacs developers as bugs). - When built with the portable dumping support (which is the default), Emacs looks for the 'emacs.pdmp' file, generated during the build, in its data directory at startup, and loads the dumped state from there. @@ -104,6 +99,15 @@ The new command-line argument '--dump-file=FILE' allows to specify a non-default '.pdmp' file to load the state from; see the node "Initial Options" in the Emacs manual for more information. +An Emacs started via a dump file can create a new dump file only if it +was invoked with the -batch option. + +Although the portable dumper has been tested, it may have a bug on +unusual platforms. If you require traditional unexec dumping you can +use the configure-time option '--with-dumping=unexec'; however, please +file a bug report describing the situation, as unexec dumping is +deprecated. + +++ ** The new configure option '--enable-checking=structs' attempts to check that the portable dumper code has been updated to match the last diff --git a/etc/TODO b/etc/TODO index b2446b0d91..a065763933 100644 --- a/etc/TODO +++ b/etc/TODO @@ -297,11 +297,7 @@ One way of doing this is to start with fx's dynamic loading, and use it to implement things like auto-loaded buffer parsers and database access in cases which need more than Lisp. -** Replace unexec with a more portable form of dumping -See eg https://lists.gnu.org/r/emacs-devel/2014-01/msg01034.html - https://lists.gnu.org/r/emacs-devel/2014-06/msg00452.html - -One way is to provide portable undumping using mmap (per gerd design). +** Fix portable dumping so that you can redump without using -batch. ** Imenu could be extended into a file-structure browsing mechanism using code like that of customize-groups. diff --git a/lib/fingerprint.h b/lib/fingerprint.h index ba2e740cd9..7d2160c988 100644 --- a/lib/fingerprint.h +++ b/lib/fingerprint.h @@ -22,8 +22,7 @@ along with GNU Emacs. If not, see