Re: [PATCH]: Re: Early backtrace.

[Alan Mackenzie <acm@muc.de>]

Hello, Eli.

On Fri, Feb 04, 2022 at 09:24:35 +0200, Eli Zaretskii wrote:
> > Date: Thu, 3 Feb 2022 21:35:26 +0000
> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > How about adding to debug-early.el some minimal documentation, which
> > > would explain how to use this facility for debugging bootstrap
> > > problems and batch-mode problems in general?  The doc strings you,
> > > Alan, provided don't describe the context and the intended use in any
> > > level of useful detail.

> > I'm not sure entirely what's needed here, probably because I've been
> > working a lot at this level for quite a long time.

> It might be a misunderstanding on my part, caused by your particular
> choice of words:

I've revised those words a fair bit.

> >  (defalias 'debug-early
> >    #'(lambda (&rest args)
> > -  "Print a trace of Lisp function calls currently active.
> > +  "Print an error message with a backtrace of active Lisp function calls.
> >  The output stream used is the value of `standard-output'.

> > -There should be two ARGS, the symbol `error' and a cons of
> > -the error symbol and its data.
> > +There should be two ARGS: the symbol `error' (which is ignored)
> > +and a cons of the error symbol and the error data.

> What do you mean by "should be" here?  Is that something the user
> should arrange for, or does this already happen?  If the latter, why
> "should"?

The "should" has now gone.

> > +This is a simplified version of `debug', intended to produce
> > +diagnostics to help in debugging the early parts of the build
> > +process.  It is typically called by the Emacs core when an error
> > +is signaled.

> "Typically" means it is, or can be, also called in other cases?  What
> are those?

"Typically" remains in the doc string for debug-early-backtrace.  This
function can be called at any time, but is particularly useful before
backtrace.el can be loaded.  "Typically" implies the user wouldn't need
it at other times, but isn't prevented from using it then.

I've taken "typically" out of the doc string for debug-early.

> > -This is a simplified version of `debug', intended for use
> > -in debugging the early parts of the build process."
> > +`debug-early' is the default value of the symbol `debugger'
> > +before enough Lisp has been loaded to support `debug' itself, and
> > +in batch mode."

> When you say "intended for use" and "intended to produce", it sounds
> like users should do something to benefit from this "intended use".
> If, instead, you mean that this feature is activated automatically in
> some circumstances, then I suggest to reword this to describe the
> feature from that perspective: when it is activated and what it
> provides when activated.

I've replaced that bit by "The Emacs core calls this function after an
error has been signaled ...."

> Bottom line, I still miss some higher-level overview of this feature,
> which should probably go into the Commentary section of the file.

I've put a bit more into the Commentary section.  Here's the current
state of the patch:



diff --git a/lisp/emacs-lisp/debug-early.el b/lisp/emacs-lisp/debug-early.el
index 718000bfa4..e557643e46 100644
--- a/lisp/emacs-lisp/debug-early.el
+++ b/lisp/emacs-lisp/debug-early.el
@@ -24,10 +24,12 @@
 
 ;;; Commentary:
 
-;; This file dumps a backtrace on stderr when an error is thrown.
-;; It has no dependencies on any Lisp libraries and is thus suitable
-;; for generating backtraces in the early parts of bootstrapping.  It
-;; is also good for generating backtraces in batch mode in general.
+;; This file dumps a backtrace on stderr when an error is thrown.  It
+;; has no dependencies on any Lisp libraries and is thus used for
+;; generating backtraces for bugs in the early parts of bootstrapping.
+;; It is also always used in batch model.  It was introduced in Emacs
+;; 29, before which there was no backtrace available during early
+;; bootstrap.
 
 (defalias 'debug-early-backtrace
   #'(lambda ()
@@ -60,14 +62,22 @@ 'debug-early-backtrace
 
 (defalias 'debug-early
   #'(lambda (&rest args)
-  "Print a trace of Lisp function calls currently active.
+  "Print an error message with a backtrace of active Lisp function calls.
 The output stream used is the value of `standard-output'.
 
-There should be two ARGS, the symbol `error' and a cons of
-the error symbol and its data.
+The Emacs core calls this function after an error has been
+signaled, and supplies two ARGS.  These are the symbol
+`error' (which is ignored) and a cons of the error symbol and the
+error data.
+
+`debug-early' is a simplified version of `debug', and is
+available during the early parts of the build process.  It is
+superseded by `debug' after enough Lisp has been loaded to
+support the latter, except in batch mode which always uses
+`debug-early'.
 
-This is a simplified version of `debug', intended for use
-in debugging the early parts of the build process."
+(In versions of Emacs prior to Emacs 29, no backtrace was
+available before `debug' was usable.)"
   (princ "\nError: ")
   (prin1 (car (car (cdr args))))	; The error symbol.
   (princ " ")


> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).