New user option compilation-search-extra-path

* lisp/progmodes/compile.el (compilation-search-extra-path): New
option (bug#80279).
(compilation-start): Use it.
(compilation-search-path):
* doc/emacs/building.texi:
* etc/NEWS: Document it, and also compilation-search-path.

doc/emacs/building.texi

@@ -188,6 +188,21 @@ appears in the @file{*compilation*} buffer.  (This variable can also
 have the values @code{if-location-known} and @code{first-known}, which
 modify the conditions for automatically visiting the error locus.)
 
+@vindex compilation-search-path
+@vindex compilation-search-extra-path
+  The actual locus of an error message is determined by
+@code{compilation-search-path}, a list of directory names.  By default,
+Emacs visits the file indicated in the error message under the directory
+where the compilation happens, which is the special directory name
+@code{nil} in the default value for @code{compilation-search-path}
+(i.e. @code{(nil)}).  If you would like Emacs to try to find the file
+under a different directory (e.g. when you compile a nested project),
+customize @code{compilation-search-path} to include that directory.  For
+directory-local customization (@pxref{Directory Variables}), prefer
+using @code{compilation-search-extra-path} instead, which will be
+considered in addition to @code{compilation-search-path}, and takes
+precedence over it.
+
   Compilation mode provides the following additional commands.  These
 commands can also be used in @file{*grep*} buffers, where the
 hyperlinks are search matches rather than error messages (@pxref{Grep

etc/NEWS

@@ -787,6 +787,14 @@ docstring for the new option.
 ** Emacs now comes with Org v9.8.
 See the file "etc/ORG-NEWS" for user-visible changes in Org.
 
++++
+** New user option 'compilation-search-extra-path'
+compile.el will now use paths specified in both
+'compilation-search-extra-path' and 'compilation-search-path', when
+doing search.  'compilation-search-extra-path' is consulted first.
+One possible use case of this option is to customize add new search
+paths on a per-project basis with directory-local customization.
+
 
 * Editing Changes in Emacs 31.1
 

lisp/progmodes/compile.el

@@ -966,10 +966,22 @@ of `my-compilation-root' here."
 (defcustom compilation-search-path '(nil)
   "List of directories to search for source files named in error messages.
 Elements should be directory names, not file names of directories.
-The value nil as an element means to try the default directory."
+The value nil as an element means to try the default directory.
+
+For directory-local customizations, prefer
+`compilation-search-extra-path' instead."
   :type '(repeat (choice (const :tag "Default" nil)
 			 (string :tag "Directory"))))
 
+;;;###autoload
+(defcustom compilation-search-extra-path nil
+  "List of extra directories to search for source files named in error messages.
+Elements in this list will be searched before those in
+`compilation-search-path'.
+
+The buffer-local value of this variable will be inherited by the
+compilation buffer.")
+
 ;;;###autoload
 (defcustom compile-command
   ;; Divide by less than 2 and round up to avoid using all processors on
@@ -2009,6 +2021,8 @@ Returns the compilation buffer created."
 	    (replace-regexp-in-string "-mode\\'" "" (symbol-name mode))))
 	 (thisdir default-directory)
 	 (thisenv compilation-environment)
+         (thissearchpath (append compilation-search-extra-path
+                                 compilation-search-path))
          (buffer-path (and (local-variable-p 'exec-path) exec-path))
          (buffer-env (and (local-variable-p 'process-environment)
                           process-environment))
@@ -2084,6 +2098,7 @@ Returns the compilation buffer created."
         ;; NB: must be done after (funcall mode) as that resets local variables
         (setq-local compilation-directory thisdir)
         (setq-local compilation-environment thisenv)
+        (setq-local compilation-search-path thissearchpath)
         (if buffer-path
             (setq-local exec-path buffer-path)
           (kill-local-variable 'exec-path))