Function: list-load-path-shadows

list-load-path-shadows is an autoloaded, interactive and byte-compiled function defined in shadow.el.gz.

Signature

(list-load-path-shadows &optional STRINGP)

Documentation

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 the earlier.

For example, suppose load-path is set to

("/usr/share/emacs/site-lisp" "/usr/share/emacs/24.3/lisp")

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
24.3. A system administrator downloaded XXX from elsewhere and installed
it. Later, XXX was updated and included in the Emacs distribution. Unless the system administrator checks for this, the new version of XXX will be hidden behind the old (which may no longer work with the new Emacs version).

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.

View in manual

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/shadow.el.gz
;;;###autoload
(defun list-load-path-shadows (&optional stringp)
  "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
the earlier.

For example, suppose `load-path' is set to

\(\"/usr/share/emacs/site-lisp\" \"/usr/share/emacs/24.3/lisp\")

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
24.3.  A system administrator downloaded XXX from elsewhere and installed
it.  Later, XXX was updated and included in the Emacs distribution.
Unless the system administrator checks for this, the new version of XXX
will be hidden behind the old (which may no longer work with the new
Emacs version).

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'."
  (interactive)
  (let* ((shadows (load-path-shadows-find load-path))
	 (n (/ (length shadows) 2))
	 (msg (format "%s Emacs Lisp load-path shadowing%s found"
		      (if (zerop n) "No" (concat "\n" (number-to-string n)))
		      (if (= n 1) " was" "s were"))))
    (with-temp-buffer
      (while shadows
	(insert (format "%s hides %s\n" (car shadows)
			(car (cdr shadows))))
	(setq shadows (cdr (cdr shadows))))
      (if stringp
	  (buffer-string)
	(if (called-interactively-p 'interactive)
	    ;; We are interactive.
	    ;; Create the *Shadows* buffer and display shadowings there.
	    (let ((string (buffer-string)))
	      (with-current-buffer (get-buffer-create "*Shadows*")
		(display-buffer (current-buffer))
		(load-path-shadows-mode) ; run after-change-major-mode-hook
		(let ((inhibit-read-only t))
		  (erase-buffer)
		  (insert string)
		  (insert msg "\n")
		  (while (re-search-backward "\\(^.*\\) hides \\(.*$\\)"
					     nil t)
		    (dotimes (i 2)
		      (make-button (match-beginning (1+ i))
				   (match-end (1+ i))
				   'type 'load-path-shadows-find-file
				   'shadow-file
				   (match-string (1+ i)))))
		  (goto-char (point-max)))))
	  ;; We are non-interactive, print shadows via message.
	  (unless (zerop n)
	    (message "This site has duplicate Lisp libraries with the same name.
If a locally-installed Lisp library overrides a library in the Emacs release,
that can cause trouble, and you should probably remove the locally-installed
version unless you know what you are doing.\n")
	    (goto-char (point-min))
	    ;; Mimic the previous behavior of using lots of messages.
	    ;; I think one single message would look better...
	    (while (not (eobp))
	      (message "%s" (buffer-substring (line-beginning-position)
					      (line-end-position)))
	      (forward-line 1))
	    (message "%s" msg)))))))