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

Class Dir

source code

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

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=None)
Called when we change the repository(ies) for a directory. This clears any cached information that is invalidated by changing the repository.
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
 
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. Ensure that the nodes are sorted.
source code
 
get_csig(self)
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.
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. 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.
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)
Searches through the file/dir entries of the current directory, and returns True if a physical entry with the given name could be found.
source code
 
rentry_exists_on_disk(self, name)
Searches through the file/dir entries of the current and all its remote directories (repos), and returns True if a physical entry with the given name could be found. The local directory (self) gets searched first, so repositories take a lower precedence regarding the searching order.
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, exclude=None)
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, release_target_info, 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_pseudo, 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__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

Class Variables [hide private]
  memoizer_counters = []

Inherited from Node: __metaclass__

Instance Variables [hide private]

Inherited from Base: fs, name, suffix

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: object.__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.

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_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

entry_exists_on_disk(self, name)

source code 

Searches through the file/dir entries of the current directory, and returns True if a physical entry with the given name could be found.

@see rentry_exists_on_disk

rentry_exists_on_disk(self, name)

source code 

Searches through the file/dir entries of the current and all its remote directories (repos), and returns True if a physical entry with the given name could be found. The local directory (self) gets searched first, so repositories take a lower precedence regarding the searching order.

@see entry_exists_on_disk

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, exclude=None)

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 "exclude" argument, if not None, must be a pattern or a list of patterns following the same UNIX shell semantics. Elements matching a least one pattern of this list will be excluded from the result.

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