Class Dir

Initialize a generic Node.FS.Base object.

Call the superclass initialization, take care of setting up
our relative and absolute paths, identify our parent
directory, and indicate that this node should use
signatures.

Overrides: Base.__init__

(inherited documentation)

Overrides: Node.get_env_scanner

Overrides: Node.get_target_scanner

Return this directory's implicit dependencies.

We don't bother caching the results because the scan typically
shouldn't be requested more than once (as opposed to scanning
.h file contents, which can be requested as many times as the
files is #included by other files).

Overrides: Node.get_found_includes

Prepare for this Node to be built.

This is called after the Taskmaster has decided that the Node
is out-of-date and must be rebuilt, but before actually calling
the method to build the Node.

This default implementation checks that explicit or implicit
dependencies either exist or are derived, and initializes the
BuildInfo structure that will hold the information about how
this node is, uh, built.

(The existence of source files is checked separately by the
Executor, which aggregates checks for all of the targets built
by a specific action.)

Overriding this method allows for for a Node subclass to remove
the underlying file from the file system.  Note that subclass
methods should call this base class method to get the child
check and the BuildInfo structure.

Overrides: Node.prepare

(inherited documentation)

A null "builder" for directories.

Overrides: Node.build

Return whether this Node has a builder or not.

In Boolean tests, this turns out to be a *lot* more efficient
than simply examining the builder attribute directly ("if
node.builder: ..."). When the builder attribute is examined
directly, it ends up calling __getattr__ for both the __len__
and __nonzero__ attributes on instances of our Builder Proxy
class(es), generating a bazillion extra calls and slowing
things down immensely.

Overrides: Node.has_builder

(inherited documentation)

Return any corresponding targets in a variant directory.
        

Overrides: Node.alter_targets

A directory does not get scanned.

Overrides: Node.scanner_key

Return content signatures and names of all our children
separated by new-lines. Ensure that the nodes are sorted.

Compute the content signature for Directory nodes. In
general, this is not needed and the content signature is not
stored in the DirNodeInfo. However, if get_contents on a Dir
node is called which has a child directory, the child
directory should return the hash of its contents.

Overrides: Node.get_csig

Must be overridden in a specific subclass to return True if this
Node (a dependency) has changed since the last time it was used
to build the specified target.  prev_ni is this Node's state (for
example, its file timestamp, length, maybe content signature)
as of the last time the target was built.

Note that this method is called through the dependency, not the
target, because a dependency Node must be able to use its own
logic to decide if it changed.  For example, File Nodes need to
obey if we're configured to use timestamps, but Python Value Nodes
never use timestamps and always use the content.  If this method
were called through the target, then each Node's implementation
of this method would have to have more complicated logic to
handle all the different Node types on which it might depend.

Overrides: Node.changed_since_last_build

(inherited documentation)

If any child is not up-to-date, then this directory isn't,
either.

Overrides: Node.is_up_to_date

Dir has a special need for srcnode()...if we
have a srcdir attribute set, then that *is* our srcnode.

Overrides: Base.srcnode

Walk this directory tree by calling the specified function
for each directory in the tree.

This behaves like the os.path.walk() function, but for in-memory
Node.FS.Dir objects.  The function takes the same arguments as
the functions passed to os.path.walk():

        func(arg, dirname, fnames)

Except that "dirname" will actually be the directory *Node*,
not the string.  The '.' and '..' entries are excluded from
fnames.  The fnames list may be modified in-place to filter the
subdirectories visited or otherwise impose a specific order.
The "arg" argument is always passed to func() and may be used
in any way (or ignored, passing None is common).

Returns a list of Nodes (or strings) matching a specified
pathname pattern.

Pathname patterns follow UNIX shell semantics:  * matches
any-length strings of any characters, ? matches any character,
and [] can enclose lists or ranges of characters.  Matches do
not span directory separators.

The matches take into account Repositories, returning local
Nodes if a corresponding entry exists in a Repository (either
an in-memory Node or something on disk).

By defafult, the glob() function matches entries that exist
on-disk, in addition to in-memory Nodes.  Setting the "ondisk"
argument to False (or some other non-true value) causes the glob()
function to only match in-memory Nodes.  The default behavior is
to return both the on-disk and in-memory Nodes.

The "source" argument, when true, specifies that corresponding
source Nodes must be returned if you're globbing in a build
directory (initialized with VariantDir()).  The default behavior
is to return Nodes local to the VariantDir().

The "strings" argument, when true, returns the matches as strings,
not Nodes.  The strings are path names relative to this directory.

The underlying algorithm is adapted from the glob.glob() function
in the Python library (but heavily modified), and uses fnmatch()
under the covers.