Node¶
Node: filesystem structure
Each file/folder is represented by exactly one node.
Some potential class properties are stored on
waflib.Build.BuildContext
: nodes to depend on, etc. Unused class members can increase the .wafpickle file size sensibly.Node objects should never be created directly, use the methods
Node.make_node()
orNode.find_node()
for the low-level operationsThe methods
Node.find_resource()
,Node.find_dir()
Node.find_or_declare()
must be used when a build context is presentEach instance of
waflib.Context.Context
has a uniqueNode
subclass required for serialization. (waflib.Node.Nod3
, see thewaflib.Context.Context
initializer). A reference to the context owning a node is held as self.ctx
- waflib.Node.exclude_regs = '\n**/*~\n**/#*#\n**/.#*\n**/%*%\n**/._*\n**/*.swp\n**/CVS\n**/CVS/**\n**/.cvsignore\n**/SCCS\n**/SCCS/**\n**/vssver.scc\n**/.svn\n**/.svn/**\n**/BitKeeper\n**/.git\n**/.git/**\n**/.gitignore\n**/.bzr\n**/.bzrignore\n**/.bzr/**\n**/.hg\n**/.hg/**\n**/_MTN\n**/_MTN/**\n**/.arch-ids\n**/{arch}\n**/_darcs\n**/_darcs/**\n**/.intlcache\n**/.DS_Store'¶
Ant patterns for files and folders to exclude while doing the recursive traversal in
waflib.Node.Node.ant_glob()
- class waflib.Node.Node(name, parent)[source]¶
This class is organized in two parts:
The basic methods meant for filesystem access (compute paths, create folders, etc)
The methods bound to a
waflib.Build.BuildContext
(requirebld.srcnode
andbld.bldnode
)
- dict_class¶
alias of
dict
- __slots__ = ('name', 'parent', 'children', 'cache_abspath', 'cache_isdir')¶
- __init__(name, parent)[source]¶
Note
Use
Node.make_node()
orNode.find_node()
instead of calling this constructor
- name¶
- parent¶
- read(flags='r', encoding='latin-1')[source]¶
Reads and returns the contents of the file represented by this node, see
waflib.Utils.readf()
:def build(bld): bld.path.find_node('wscript').read()
- Parameters
flags (string) – Open mode
encoding (string) – encoding value for Python3
- Return type
string or bytes
- Returns
File contents
- write(data, flags='w', encoding='latin-1')[source]¶
Writes data to the file represented by this node, see
waflib.Utils.writef()
:def build(bld): bld.path.make_node('foo.txt').write('Hello, world!')
- Parameters
data (string) – data to write
flags (string) – Write mode
encoding (string) – encoding value for Python3
- read_json(convert=True, encoding='utf-8')[source]¶
Reads and parses the contents of this node as JSON (Python ≥ 2.6):
def build(bld): bld.path.find_node('abc.json').read_json()
Note that this by default automatically decodes unicode strings on Python2, unlike what the Python JSON module does.
- Parameters
convert (boolean) – Prevents decoding of unicode strings on Python2
encoding (string) – The encoding of the file to read. This default to UTF8 as per the JSON standard
- Return type
object
- Returns
Parsed file contents
- write_json(data, pretty=True)[source]¶
Writes a python object as JSON to disk (Python ≥ 2.6) as UTF-8 data (JSON standard):
def build(bld): bld.path.find_node('xyz.json').write_json(199)
- Parameters
data (object) – The data to write to disk
pretty (boolean) – Determines if the JSON will be nicely space separated
- delete(evict=True)[source]¶
Removes the file/folder from the filesystem (equivalent to rm -rf), and remove this object from the Node tree. Do not use this object after calling this method.
- height()[source]¶
Returns the depth in the folder hierarchy from the filesystem root or from all the file drives
- Returns
filesystem depth
- Return type
integer
- listdir()[source]¶
Lists the folder contents
- Returns
list of file/folder names ordered alphabetically
- Return type
list of string
- mkdir()[source]¶
Creates a folder represented by this node. Intermediate folders are created as needed.
- Raises
waflib.Errors.WafError
when the folder is missing
- find_node(lst)[source]¶
Finds a node on the file system (files or folders), and creates the corresponding Node objects if it exists
- Parameters
lst (string or list of string) – relative path
- Returns
The corresponding Node object or None if no entry was found on the filesystem
- Return type
:py:class:´waflib.Node.Node´
- make_node(lst)[source]¶
Returns or creates a Node object corresponding to the input path without considering the filesystem.
- Parameters
lst (string or list of string) – relative path
- Return type
:py:class:´waflib.Node.Node´
- search_node(lst)[source]¶
Returns a Node previously defined in the data structure. The filesystem is not considered.
- Parameters
lst (string or list of string) – relative path
- Return type
:py:class:´waflib.Node.Node´ or None if there is no entry in the Node datastructure
- path_from(node)[source]¶
Path of this node seen from the other:
def build(bld): n1 = bld.path.find_node('foo/bar/xyz.txt') n2 = bld.path.find_node('foo/stuff/') n1.path_from(n2) # '../bar/xyz.txt'
- Parameters
node (
waflib.Node.Node
) – path to use as a reference- Returns
a relative path or an absolute one if that is better
- Return type
string
- abspath()[source]¶
Returns the absolute path. A cache is kept in the context as
cache_node_abspath
- Return type
string
- is_child_of(node)[source]¶
Returns whether the object belongs to a subtree of the input node:
def build(bld): node = bld.path.find_node('wscript') node.is_child_of(bld.path) # True
- Parameters
node (
waflib.Node.Node
) – path to use as a reference- Return type
bool
- ant_iter(accept=None, maxdepth=25, pats=[], dir=False, src=True, remove=True, quiet=False)[source]¶
Recursive method used by
waflib.Node.ant_glob()
.- Parameters
accept (function) – function used for accepting/rejecting a node, returns the patterns that can be still accepted in recursion
maxdepth (int) – maximum depth in the filesystem (25)
pats (tuple) – list of patterns to accept and list of patterns to exclude
dir (bool) – return folders too (False by default)
src (bool) – return files (True by default)
remove (bool) – remove files/folders that do not exist (True by default)
quiet (bool) – disable build directory traversal warnings (verbose mode)
- Returns
A generator object to iterate from
- Return type
iterator
- ant_glob(*k, **kw)[source]¶
Finds files across folders and returns Node objects:
**/*
find all files recursively**/*.class
find all files ending by .class..
find files having two dot characters
For example:
def configure(cfg): # find all .cpp files cfg.path.ant_glob('**/*.cpp') # find particular files from the root filesystem (can be slow) cfg.root.ant_glob('etc/*.txt') # simple exclusion rule example cfg.path.ant_glob('*.c*', excl=['*.c'], src=True, dir=False)
For more information about the patterns, consult http://ant.apache.org/manual/dirtasks.html Please remember that the ‘..’ sequence does not represent the parent directory:
def configure(cfg): cfg.path.ant_glob('../*.h') # incorrect cfg.path.parent.ant_glob('*.h') # correct
The Node structure is itself a filesystem cache, so certain precautions must be taken while matching files in the build or installation phases. Nodes objects that do have a corresponding file or folder are garbage-collected by default. This garbage collection is usually required to prevent returning files that do not exist anymore. Yet, this may also remove Node objects of files that are yet-to-be built.
This typically happens when trying to match files in the build directory, but there are also cases when files are created in the source directory. Run
waf -v
to display any warnings, and try consider passingremove=False
when matching files in the build directory.Since ant_glob can traverse both source and build folders, it is a best practice to call this method only from the most specific build node:
def build(bld): # traverses the build directory, may need ``remove=False``: bld.path.ant_glob('project/dir/**/*.h') # better, no accidental build directory traversal: bld.path.find_node('project/dir').ant_glob('**/*.h') # best
In addition, files and folders are listed immediately. When matching files in the build folders, consider passing
generator=True
so that the generator object returned can defer computation to a later stage. For example:def build(bld): bld(rule='tar xvf ${SRC}', source='arch.tar') bld.add_group() gen = bld.bldnode.ant_glob("*.h", generator=True, remove=True) # files will be listed only after the arch.tar is unpacked bld(rule='ls ${SRC}', source=gen, name='XYZ')
- Parameters
incl (string or list of strings) – ant patterns or list of patterns to include
excl (string or list of strings) – ant patterns or list of patterns to exclude
dir (bool) – return folders too (False by default)
src (bool) – return files (True by default)
maxdepth (int) – maximum depth of recursion
ignorecase (bool) – ignore case while matching (False by default)
generator (bool) – Whether to evaluate the Nodes lazily
remove (bool) – remove files/folders that do not exist (True by default)
quiet (bool) – disable build directory traversal warnings (verbose mode)
- Returns
The corresponding Node objects as a list or as a generator object (generator=True)
- Return type
by default, list of
waflib.Node.Node
instances
- is_src()[source]¶
Returns True if the node is below the source directory. Note that
!is_src() ≠ is_bld()
- Return type
bool
- is_bld()[source]¶
Returns True if the node is below the build directory. Note that
!is_bld() ≠ is_src()
- Return type
bool
- get_src()[source]¶
Returns the corresponding Node object in the source directory (or self if already under the source directory). Use this method only if the purpose is to create a Node object (this is common with folders but not with files, see ticket 1937)
- Return type
- get_bld()[source]¶
Return the corresponding Node object in the build directory (or self if already under the build directory). Use this method only if the purpose is to create a Node object (this is common with folders but not with files, see ticket 1937)
- Return type
- find_resource(lst)[source]¶
Use this method in the build phase to find source files corresponding to the relative path given.
First it looks up the Node data structure to find any declared Node object in the build directory. If None is found, it then considers the filesystem in the source directory.
- Parameters
lst (string or list of string) – relative path
- Returns
the corresponding Node object or None
- Return type
- find_or_declare(lst)[source]¶
Use this method in the build phase to declare output files which are meant to be written in the build directory.
This method creates the Node object and its parent folder as needed.
- Parameters
lst (string or list of string) – relative path
- find_dir(lst)[source]¶
Searches for a folder on the filesystem (see
waflib.Node.Node.find_node()
)- Parameters
lst (string or list of string) – relative path
- Returns
The corresponding Node object or None if there is no such folder
- Return type
- change_ext(ext, ext_in=None)[source]¶
Declares a build node with a distinct extension; this is uses
waflib.Node.Node.find_or_declare()
- Returns
A build node of the same path, but with a different extension
- Return type
- bldpath()[source]¶
Returns the relative path seen from the build directory
src/foo.cpp
- Return type
string
- srcpath()[source]¶
Returns the relative path seen from the source directory
../src/foo.cpp
- Return type
string
- relpath()[source]¶
If a file in the build directory, returns
waflib.Node.Node.bldpath()
, else returnswaflib.Node.Node.srcpath()
- Return type
string
- h_file()¶
-
- Returns
a hash representing the file contents
- Return type
string or bytes
- children¶
- cache_abspath¶
- cache_isdir¶
- get_bld_sig()[source]¶
Returns a signature (see
waflib.Node.Node.h_file()
) for the purpose of build dependency calculation. This method uses a per-context cache.- Returns
a hash representing the object contents
- Return type
string or bytes
- waflib.Node.pickle_lock = <unlocked _thread.lock object>¶
Lock mandatory for thread-safe node serialization