Display a list of Emacs Lisp files that shadow other files.
If STRINGP is non-nil, returns any shadows as a string.
Otherwise, if interactive shows any shadows in a `*Shadows*' buffer;
else prints messages listing any shadows.
This function lists potential load path problems. Directories in
the `load-path' variable are searched, in order, for Emacs Lisp
files. When a previously encountered file name is found again, a
message is displayed indicating that the later file is "hidden" by
For example, suppose `load-path' is set to
and that each of these directories contains a file called XXX.el. Then
XXX.el in the site-lisp directory is referred to by all of:
(require 'XXX), (autoload .... "XXX"), (load-library "XXX") etc.
The first XXX.el file prevents Emacs from seeing the second (unless
the second is loaded explicitly via `load-file').
When not intended, such shadowings can be the source of subtle
problems. For example, the above situation may have arisen because the
XXX package was not distributed with versions of Emacs prior to
19.30. An Emacs maintainer downloaded XXX from elsewhere and installed
it. Later, XXX was updated and included in the Emacs distribution.
Unless the Emacs maintainer checks for this, the new version of XXX
will be hidden behind the old (which may no longer work with the new
This function performs these checks and flags all possible
shadowings. Because a .el file may exist without a corresponding .elc
(or vice-versa), these suffixes are essentially ignored. A file
XXX.elc in an early directory (that does not contain XXX.el) is
considered to shadow a later file XXX.el, and vice-versa. Shadowings are located by calling the (non-interactive) companion function, `load-path-shadows-find'. (fn &optional STRINGP)