Re: directory search fails!

[Eli Zaretskii]

> From: Paul Smith <address@hidden>
> Date: Wed, 22 Sep 2010 17:56:34 -0400
> Cc: address@hidden
> 
> On Wed, 2010-09-22 at 11:52 -0800, ali hagigat wrote:
> > b. If the target does need to be rebuilt (is out-of-date), the
> > pathname found during
> > directory search is thrown away, and the target is rebuilt using the file 
> > name
> > specified in the makefile. In short, if make must rebuild, then the
> > target is rebuilt
> > locally, not in the directory found via directory search.
> > --------------------------------------------------------------------------------------
> > If a target is found by directory search and needs to be rebuilt and
> > updated, that target seems to be updated at the same directory found
> > by directory search algorithm.
> 
> No.  That is exactly the opposite of what the manual says in the section
> you quote above (and make's implementation agrees with the manual).

Right.

This list is not exactly the right place for posting changes, but
since this discussion involved list members, I think it's appropriate
in this case.

Here's the modified text of the node that describes the details of the
directory search algorithm.  Let me know if it is clear enough and
correct to be put into the manual.

  @node Search Algorithm, Recipes/Search, Selective Search, Directory Search
  @subsection How Directory Searches are Performed
  @cindex algorithm for directory search
  @cindex directory search algorithm

  When a prerequisite of a target is found through directory search,
  regardless of type (general with @code{VPATH} or selective with
  @code{vpath}), the pathname found by the search may not be the one
  that @code{make} actually uses for updating that target.  Sometimes
  the path of a prerequisite discovered through directory search is
  thrown away.

  This section describes the details of the decision whether or not to
  keep the path of a prerequisite found through directory search.

  The algorithm @code{make} uses to decide whether to keep or abandon a
  path or a prerequisite (denoted as @var{P} below) found via directory
  search is as follows:

  @enumerate
  @item
  If a prerequisite file @var{P} does not exist at the path specified
  in the makefile, directory search is performed.

  @item
  If the prerequisite @var{P} is found via directory search, the
  pathname under which @code{make} found @var{P} is tentatively recorded
  as the actual prerequisite.  (This is a tentative decision, because it
  could be reversed later, see below.)

  @item
  All the prerequisites of @var{P} are examined using this same method,
  i.e.@: by using directory search if the file specified by the makefile
  does not exist.

  @item
  After recursively processing all the prerequisites of @var{P},
  @code{make} decides whether or not @var{P} needs to be rebuilt.  This
  decision affects whether the actual pathname of @var{P} found by
  directory search is kept:

  @enumerate a
  @item
  If @var{P} does @emph{not} need to be rebuilt, the actual pathname of
  @var{P} found during directory search is used in any prerequisite
  lists which contain @var{P}.  In other words, if @code{make} doesn't
  need to rebuild a prerequisite, then it uses its pathname found via
  directory search when it processes targets which depend on this
  prerequisite.

  @item
  If @var{P} @emph{does} need to be rebuilt (is out-of-date), its actual
  pathname found during directory search is @emph{thrown away}, and
  @var{P} is rebuilt at the literal location specified in the makefile.
  In other words, if @code{make} must rebuild a prerequisite, then it is
  rebuilt locally, not in the directory found via directory search.
  @end enumerate
  @end enumerate

  This algorithm may seem complex, but in practice it is quite often
  exactly what you want.

  @cindex traditional directory search (GPATH)
  @cindex directory search, traditional (GPATH)
  Other versions of @code{make} use a simpler algorithm: if the file
  does not exist, and it is found via directory search, then that
  pathname is always used whether or not it needs to be built.  Thus, if
  the prerequisite is rebuilt, it is created at the pathname found
  during directory search, and that pathname is used for any targets
  which mention the prerequisite in their prerequisite lists.

  @vindex GPATH
  If, in fact, this is the behavior you want for some or all of your
  directories, you can use the @code{GPATH} variable to indicate this to
  @code{make}.

  @code{GPATH} has the same syntax and format as @code{VPATH} (that is, a
  space- or colon-delimited list of pathnames).  If an out-of-date target
  is found by directory search in a directory that also appears in
  @code{GPATH}, then that pathname is not thrown away.  The target is
  rebuilt using the expanded path.