Re: How does one find out what file a library has been loaded from?

[Eli Zaretskii]

> Date: Wed, 20 Jul 2022 20:34:05 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> Here's a first preliminary effort at amending loading.texi:

Thanks, but in "needs work"(TM).

>  @defun symbol-file symbol &optional type
> -This function returns the name of the file that defined @var{symbol}.
> -If @var{type} is @code{nil}, then any kind of definition is acceptable.
> -If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
> -specifies function definition, variable definition, or face definition
> -only.
> +This function returns a file name associated with the file that
> +defined @var{symbol} (@pxref{eln files}).  If @var{type} is
> +@code{nil}, then any kind of definition is acceptable.  If @var{type}
> +is @code{defun}, @code{defvar}, or @code{defface}, that specifies
> +function definition, variable definition, or face definition only.

This change is for the worse: it introduces a vague and confusing
notion of "file name associated with the file that defines" a symbol.
This should be removed from the patch, as it doesn't add any useful
information, just muddies the waters.

>  @defvar load-history
> -The value of this variable is an alist that associates the names of
> -loaded library files with the names of the functions and variables
> -they defined, as well as the features they provided or required.
> +The value of this variable is an alist that associates names
> +associated with loaded library files (@pxref{eln files}) with the
> +names of the functions and variables the files defined, as well as the
> +features they provided or required.

Likewise.

>  Each element in this alist describes one loaded library (including
>  libraries that are preloaded at startup).  It is a list whose @sc{car}
> -is the absolute file name of the library (a string).  The rest of the
> -list elements have these forms:
> +is an absolute file name associated with the library (a string)
> +(@pxref{eln files}).  The rest of the list elements have these forms:

Likewise.

> -  The command @code{eval-region} updates @code{load-history}, but does so
> -by adding the symbols defined to the element for the file being visited,
> -rather than replacing that element.  @xref{Eval}.
> +@anchor{eln files} For backwards compatibility, @code{load-history}
> +stores and @code{symbol-file} returns the name of a notional byte
> +compiled @file{.elc} file in the same directory as its source file
> +when the real file loaded from is a natively compiled file elsewhere.
> +This @file{.elc} file may or may not actually exist.  For other files,
> +their absolute file names are used.

This last sentence is "out of the blue": what "other files"?  The text
should also have a cross-reference to where native compilation is
described in the manual.

>                                        If you want to find the actual
> +file loaded from, and you suspect if may really be a native compiled
> +file, something like the following should help.  You need to know the
> +name of a function which hasn't been advised, say @var{foo}, defined
> +in the suspected native compiled file.  Then
> +
> +@lisp
> +(let ((foo-fun (symbol-function #'FOO)))
> +       (and foo-fun (subr-native-elisp-p foo-fun)
> +            (native-comp-unit-file (subr-native-comp-unit foo-fun))))
> +@end lisp
> +
> +@noindent
> +will return either the name of the native compiled file defining
> +@var{foo}, or @code{nil} if there is no such file.

This is not a good way of documenting some technique in this manual.
The way we describe such stuff is by documenting the functions a
program needs to use, not by giving a random example which calls the
functions without any documentation of the functions themselves.

Also, native-comp-unit-file doesn't exist in a build without native
compilation support, so some feature test is missing.

Finally, "FOO" is not how we refer to a meta-syntactic variable in the
manual: we use @var{foo} instead.

> +The command @code{eval-region} updates @code{load-history}, but does
> +so by adding the symbols defined to the element for the file being
> +visited, rather than replacing that element.  @xref{Eval}.

This part should be before the text which explains the issues with
loading *.eln files.