Package SCons :: Package Node :: Module FS :: Class Dir
[hide private]
[frames] | no frames]

Class Dir

source code

object --+        
         |        
      Node --+    
             |    
          Base --+
                 |
                Dir
Known Subclasses:
RootDir

A class for directories in a file system.
    



Nested Classes [hide private]
  NodeInfo
The generic base class for signature information for a Node.
  BuildInfo
The generic base class for build information for a Node.

Inherited from Node: Attrs

Instance Methods [hide private]
 
__init__(self, name, directory, fs)
Initialize a generic Node.FS.Base object.
source code
 
_morph(self)
Turn a file system Node (either a freshly initialized directory object or a separate Entry object) into a proper directory object.
source code
 
diskcheck_match(self) source code
 
__clearRepositoryCache(self, duplicate=False)
Called when we change the repository(ies) for a directory.
source code
 
__resetDuplicate(self, node) source code
 
Entry(self, name)
Looks up or creates an entry node named 'name' relative to this directory.
source code
 
Dir(self, name, create=True)
Looks up or creates a directory node named 'name' relative to this directory.
source code
 
File(self, name)
Looks up or creates a file node named 'name' relative to this directory.
source code
 
_lookup_rel(self, name, klass, create=1)
Looks up a *normalized* relative path name, relative to this directory.
source code
 
link(self, srcdir, duplicate)
Set this directory as the variant directory for the supplied source directory.
source code
 
getRepositories(self)
Returns a list of repositories for this directory.
source code
 
get_all_rdirs(self) source code
 
addRepository(self, dir) source code
 
up(self) source code
 
_rel_path_key(self, other) source code
 
rel_path(self, other)
Return a path to "other" relative to this directory.
source code
 
get_env_scanner(self, env, kw={}) source code
 
get_target_scanner(self) source code
 
get_found_includes(self, env, scanner, path)
Return this directory's implicit dependencies.
source code
 
prepare(self)
Prepare for this Node to be built.
source code
 
build(self, **kw)
A null "builder" for directories.
source code
 
_create(self)
Create this directory, silently and without worrying about whether the builder is the default or not.
source code
 
multiple_side_effect_has_builder(self)
Return whether this Node has a builder or not.
source code
 
alter_targets(self)
Return any corresponding targets in a variant directory.
source code
 
scanner_key(self)
A directory does not get scanned.
source code
 
get_text_contents(self)
We already emit things in text, so just return the binary version.
source code
 
get_contents(self)
Return content signatures and names of all our children separated by new-lines.
source code
 
get_csig(self)
Compute the content signature for Directory nodes.
source code
 
do_duplicate(self, src) source code
 
changed_since_last_build(self, target, prev_ni)
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.
source code
 
is_up_to_date(self)
If any child is not up-to-date, then this directory isn't, either.
source code
 
rdir(self) source code
 
sconsign(self)
Return the .sconsign file info for this directory, creating it first if necessary.
source code
 
srcnode(self)
Dir has a special need for srcnode()...if we have a srcdir attribute set, then that *is* our srcnode.
source code
 
get_timestamp(self)
Return the latest timestamp from among our children
source code
 
entry_abspath(self, name) source code
 
entry_labspath(self, name) source code
 
entry_path(self, name) source code
 
entry_tpath(self, name) source code
 
entry_exists_on_disk(self, name) source code
 
srcdir_list(self) source code
 
srcdir_duplicate(self, name) source code
 
_srcdir_find_file_key(self, filename) source code
 
srcdir_find_file(self, filename) source code
 
dir_on_disk(self, name) source code
 
file_on_disk(self, name) source code
 
walk(self, func, arg)
Walk this directory tree by calling the specified function for each directory in the tree.
source code
 
glob(self, pathname, ondisk=True, source=False, strings=False)
Returns a list of Nodes (or strings) matching a specified pathname pattern.
source code
 
_glob1(self, pattern, ondisk=True, source=False, strings=False)
Globs for and returns a list of entry names matching a single pattern in this directory.
source code

Inherited from Base: RDirs, Rfindalldirs, __str__, exists, for_signature, get_abspath, get_dir, get_path, get_subst_proxy, get_suffix, getmtime, getsize, is_under, isdir, isfile, islink, must_be_same, rentry, rexists, rfile, rstr, set_local, set_src_builder, src_builder, stat, str_for_display, target_from_source

Inherited from Base (private): _Rfindalldirs_key, _get_str, _save_str

Inherited from Node: Decider, add_dependency, add_ignore, add_prerequisite, add_source, add_to_implicit, add_to_waiting_parents, add_to_waiting_s_e, add_wkid, all_children, builder_set, built, changed, children, children_are_up_to_date, clear, clear_memoized_values, del_binfo, disambiguate, do_not_store_info, env_set, executor_cleanup, explain, get_binfo, get_build_env, get_build_scanner_path, get_builder, get_cachedir_csig, get_env, get_executor, get_implicit_deps, get_ninfo, get_source_scanner, get_state, get_stored_implicit, get_stored_info, get_string, has_builder, has_explicit_builder, is_derived, is_literal, make_ready, missing, new_binfo, new_ninfo, postprocess, push_to_cache, remove, render_include_tree, reset_executor, retrieve_from_cache, scan, select_scanner, set_always_build, set_executor, set_explicit, set_nocache, set_noclean, set_precious, set_specific_source, set_state, state_has_changed, store_info, visited

Inherited from Node (private): _add_child, _children_get, _children_reset

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__

Class Variables [hide private]
  memoizer_counters = []

Inherited from Node: __metaclass__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, name, directory, fs)
(Constructor)

source code 
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)

_morph(self)

source code 
Turn a file system Node (either a freshly initialized directory
object or a separate Entry object) into a proper directory object.

Set up this directory's entries and hook it into the file
system tree.  Specify that directories (this Node) don't use
signatures for calculating whether they're current.

__clearRepositoryCache(self, duplicate=False)

source code 
Called when we change the repository(ies) for a directory.
This clears any cached information that is invalidated by changing
the repository.

_lookup_rel(self, name, klass, create=1)

source code 

Looks up a *normalized* relative path name, relative to this
directory.

This method is intended for use by internal lookups with
already-normalized path data.  For general-purpose lookups,
use the Entry(), Dir() and File() methods above.

This method does *no* input checking and will die or give
incorrect results if it's passed a non-normalized path name (e.g.,
a path containing '..'), an absolute path name, a top-relative
('#foo') path name, or any kind of object.

get_env_scanner(self, env, kw={})

source code 
Overrides: Node.get_env_scanner

get_target_scanner(self)

source code 
Overrides: Node.get_target_scanner

get_found_includes(self, env, scanner, path)

source code 
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(self)

source code 
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)

build(self, **kw)

source code 
A null "builder" for directories.

Overrides: Node.build

multiple_side_effect_has_builder(self)

source code 
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)

alter_targets(self)

source code 
Return any corresponding targets in a variant directory.
        

Overrides: Node.alter_targets

scanner_key(self)

source code 
A directory does not get scanned.

Overrides: Node.scanner_key

get_contents(self)

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

get_csig(self)

source code 
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

changed_since_last_build(self, target, prev_ni)

source code 


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)

is_up_to_date(self)

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

Overrides: Node.is_up_to_date

srcnode(self)

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

Overrides: Base.srcnode

walk(self, func, arg)

source code 

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).

glob(self, pathname, ondisk=True, source=False, strings=False)

source code 

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.

_glob1(self, pattern, ondisk=True, source=False, strings=False)

source code 

Globs for and returns a list of entry names matching a single
pattern in this directory.

This searches any repositories and source directories for
corresponding entries and returns a Node (or string) relative
to the current directory if an entry is found anywhere.

TODO: handle pattern with no wildcard

Overrides: Base._glob1