[Emacs-diffs] master 6bac9ea: Improve documentation of portable dumping

[Eli Zaretskii]

branch: master
commit 6bac9ea1770c0954adf5f4af660e94b5a0b09003
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of portable dumping
    
    * src/pdumper.c (Fdump_emacs_portable): Improve the doc string
    and the error messages.
    
    * doc/lispref/internals.texi (Building Emacs): Document
    portable dumping and the 'dump-emacs-portable' function.
---
 doc/lispref/internals.texi | 86 +++++++++++++++++++++++++++++++++++++---------
 src/pdumper.c              |  6 ++--
 2 files changed, 73 insertions(+), 19 deletions(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index d7c1fb7..66606da 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -48,24 +48,63 @@ environment.  After this step, the Emacs executable is no 
longer
 @dfn{bare}.
 
 @cindex dumping Emacs
address@hidden @option{--temacs} option, and dumping method
   Because it takes some time to load the standard Lisp files, the
 @file{temacs} executable usually isn't run directly by users.
-Instead, as one of the last steps of building Emacs, the command
address@hidden -batch -l loadup dump} is run.  The special @samp{dump}
-argument causes @command{temacs} to dump out an executable program,
-called @file{emacs}, which has all the standard Lisp files preloaded.
-(The @samp{-batch} argument prevents @file{temacs} from trying to
-initialize any of its data on the terminal, so that the tables of
-terminal information are empty in the dumped Emacs.)
+Instead, one of the last steps of building Emacs runs the command
address@hidden@samp{temacs -batch -l loadup address@hidden  The
+special option @option{--temacs} tells @command{temacs} how to record
+all the standard preloaded Lisp functions and variables, so that when
+you subsequently run Emacs, it will start much faster.  The
address@hidden option requires an argument @var{dump-method}, which
+can be one of the following:
+
address@hidden @samp
address@hidden pdump
address@hidden portable dump file
+Record the preloaded Lisp data in a @dfn{portable 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},
+and is installed in the Emacs @code{data-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,
+which might get in the way of various memory-layout techniques used by
+modern systems to enhance security and privacy.
+
address@hidden pbootstrap
address@hidden 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
address@hidden in this case.
+
address@hidden dump
address@hidden unexec
+This method causes @command{temacs} to dump out an executable program,
+called @file{emacs}, which has all the standard Lisp files already
+preloaded into it.  (The @samp{-batch} argument prevents
address@hidden from trying to initialize any of its data on the
+terminal, so that the tables of terminal information are empty in the
+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.
+
address@hidden bootstrap
+Like @samp{dump}, but used when bootstrapping Emacs with the
address@hidden method.
address@hidden table
 
 @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.  The variable
address@hidden stores a list of the Lisp files preloaded
-into the dumped Emacs.  If you port Emacs to a new operating system,
-and are not able to implement dumping, then Emacs must load
address@hidden each time it starts.
+is the one which is installed.  If the portable dumping was used to
+build Emacs, the @file{emacs} executable is actually an exact copy of
address@hidden, 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
+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.
 
 @cindex build details
 @cindex deterministic build
@@ -161,14 +200,29 @@ In the unlikely event that you need a more general 
functionality than
 @code{custom-initialize-delay} provides, you can use
 @code{before-init-hook} (@pxref{Startup Summary}).
 
address@hidden dump-emacs-portable to-file &optional track-referrers
+This function dumps the current state of Emacs into a portable dump
+file @var{to-file}, using the @code{pdump} method.  Normally, the
+portable dump file is called @address@hidden, where
address@hidden is the name of the Emacs executable file.  The
+optional argument @var{track-referrers}, if address@hidden, causes the
+portable dumping process keep additional information to help track
+down the provenance of object types that are not yet supported by the
address@hidden method.
+
+If you want to use this function in an Emacs that was already dumped,
+you must run Emacs with the @samp{-batch} option.
address@hidden defun
+
 @defun dump-emacs to-file from-file
 @cindex unexec
 This function dumps the current state of Emacs into an executable file
address@hidden  It takes symbols from @var{from-file} (this is normally
-the executable file @file{temacs}).
address@hidden, using the @code{unexec} method.  It takes symbols from
address@hidden (this is normally the executable file @file{temacs}).
 
-If you want to use this function in an Emacs that was already dumped,
-you must run Emacs with @samp{-batch}.
+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.
 @end defun
 
 @node Pure Storage
diff --git a/src/pdumper.c b/src/pdumper.c
index db66e1b..cd242f7 100644
--- a/src/pdumper.c
+++ b/src/pdumper.c
@@ -4033,7 +4033,7 @@ dump_drain_deferred_symbols (struct dump_context *ctx)
 DEFUN ("dump-emacs-portable",
        Fdump_emacs_portable, Sdump_emacs_portable,
        1, 2, 0,
-       doc: /* Dump current state of Emacs into dump file FILENAME.
+       doc: /* Dump current state of Emacs into portable dump file FILENAME.
 If TRACK-REFERRERS is non-nil, keep additional debugging information
 that can help track down the provenance of unsupported object
 types.  */)
@@ -4048,10 +4048,10 @@ types.  */)
            "unexpected results.");
 
   if (!main_thread_p (current_thread))
-    error ("Function can be called only on main thread");
+    error ("This function can be called only in the main thread");
 
   if (!NILP (XCDR (Fall_threads ())))
-    error ("No other threads can be running");
+    error ("No other Lisp threads can be running when this function is 
called");
 
   /* Clear out any detritus in memory.  */
   do {