From 8bbeaa52809b0ec4dfc6504bac5bdac879b9a02d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 7 Jan 2022 08:44:43 -0700 Subject: Add to description of Node Objects [skip appveyor] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 222 ++++++++++++++++++++++++++++++++++++++---------------- doc/scons.mod | 1 + 2 files changed, 160 insertions(+), 63 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index a5eff28..a98f4e8 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -12,10 +12,10 @@ without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -# + The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -# + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND @@ -145,16 +145,16 @@ to support additional input file types. Information about files involved in the build, including a cryptographic hash of the contents, -is cached for later reuse, -By default content hashes are used to determine if a file -has changed since the last build, +is cached for later reuse. +By default this hash (the &contentsig;) +is used to determine if a file has changed since the last build, but this can be controlled by selecting an appropriate &f-link-Decider; function. Implicit dependency files are also part of out-of-date computation. The scanned implicit dependency information can optionally be cached and used to speed up future builds. -A hash of each executed build action is cached, -so that changes to build instructions (changing flags, etc.) +A hash of each executed build action (the &buildsig; +is cached, so that changes to build instructions (changing flags, etc.) or to the build tools themselves (new version) can also trigger a rebuild. @@ -4968,20 +4968,51 @@ vars.AddVariables( -File and Directory Nodes +Node Objects + + +&SCons; represents objects that are the sources or targets of +build operations as Nodes, +which are internal data structures. +There are a number of user-visible types of nodes: +File Nodes, Directory Nodes, Value Nodes and Alias Nodes. +Some of the node types have public attributes and methods, +described below. Each of the node types has a global function +and a matching environment method to create instances: +&f-link-File;, &f-link-Dir;, &f-link-Value; and &f-link-Alias;. + + + +Filesystem Nodes The &f-link-File; and &f-link-Dir; functions/methods return File and Directory Nodes, respectively. -Such nodes are Python objects with -several user-visible attributes -and methods that are often useful to access -in SConscript files: +File and Directory Nodes +(collectively, Filesystem Nodes) +represent build components that correspond to an entry +in the computer's filesystem, +whether or not such an entry exists at the time the Node is created. +You do not usually need to explicitly create filesystem Nodes, +since when you supply a string as a target or source of a Builder, +&SCons; will create the Nodes as needed to populate the +dependency graph. +Builders return the target Node(s) in the form of a list, +which you can then make use of. +However, since filesystem Nodes have some useful +public attributes and methods +that you can use in SConscript files, +it is sometimes appropriate to create them manually, +outside the regular context of a Builder call. + + +The following attributes provide information about a Node: + - n.path + node.path The build path of the given @@ -4995,21 +5026,21 @@ is not being used. - n.abspath + node.abspath The absolute build path of the given file or directory. - n.relpath + node.relpath The build path of the given file or directory relative to the root SConstruct file's directory. - n.srcnode() + node.srcnode() The srcnode @@ -5022,101 +5053,116 @@ File or Directory Node. -For example: +Examples: # Get the current build dir's path, relative to top. Dir('.').path + # Current dir's absolute path Dir('.').abspath + # Current dir's path relative to the root SConstruct file's directory Dir('.').relpath + # Next line is always '.', because it is the top dir's path relative to itself. Dir('#.').path -File('foo.c').srcnode().path # source path of the given source file. -# Builders also return File objects: +# Source path of the given source file. +File('foo.c').srcnode().path + +# Builders return lists of File objects: foo = env.Program('foo.c') -print("foo will be built in", foo.path) +print("foo will be built in", foo[0].path) -File and Directory Node objects have methods to create +Filesystem Node objects have methods to create new File and Directory Nodes relative to the original Node. +There are also times when you may need to refer to an entry +in a filesystem without knowing in advance whether it's a +file or a directory. +For those situations, +there is an Entry method of filesystem node objects, +which returns a Node that can represent either a file or a directory. -If the object is a Directory Node, -these methods will place the the new Node within the directory -the Node represents: +If the original Node is a Directory Node, +these methods will place the new Node within the directory +the original Node represents: - d.Dir(name) + node.Dir(name) -Returns a directory Node for a subdirectory of -d -named -name. +Returns a directory Node +name +which is a subdirectory of +the directory represented by +node. - d.File(name) + node.File(name) -Returns a file Node for a file within -d -named -name. +Returns a file Node +name +in the directory represented by +node. - d.Entry(name) + node.Entry(name) -Returns an unresolved Node within -d -named -name. +Returns an unresolved Node +name +in the directory represented by +node. -If the object is a File Node, +If the original Node is a File Node, these methods will place the the new Node in the same -directory as the one the Node represents: +directory as the one the original Node represents: - f.Dir(name) + node.Dir(name) -Returns a directory named +Returns a Node name -within the parent directory of -f. +for a directory in the parent directory of +the file represented by +node. - f.File(name) + node.File(name) -Returns a file named +Returns a Node name -within the parent directory of -f. +for a file in the parent directory of +the file represented by +node. - f.Entry(name) + node.Entry(name) -Returns an unresolved Node named +Returns an unresolved Node name -within the parent directory of -f. +in the parent directory of +the file represented by +node. @@ -5142,6 +5188,56 @@ html = docs.Dir('html') index = html.File('index.html') css = index.File('app.css') + + + +Value and Alias Nodes + + +&SCons; provides two other Node types to represent +object that will not have an equivalent filesystem entry. +Such Nodes always need to be created explicitly. + + + +The &f-link-Alias; method returns an Alias Node. +Aliases are virtual objects - they will not themselves result +in physical objects being constructed, but are entered into +the dependency graph related to their sources. +An alias is checked for up to date by checking if +its sources are up to date. +An alias is built by making sure its sources have been built, +and if any building took place, +applying any Actions that are defined as part of the alias. + + + +An &f-link-Alias; call creates an entry in the alias namespace, +which is used for disambiguation. +If an alias source has a string valued name, +it will be resolved to a filesystem entry Node, +unless it is found in the alias namespace, +in which case it it resolved to the matching alias Node. +As a result, the order of &f-Alias; calls is significant. +An alias can refer to another alias, but only if the +other alias has previously been created. + + + +The &f-link-Value; method returns a Value Node. +Value nodes are often used for generated data that +will not have any corresponding filesystem entry, +but will be used to determine whether a build target is out of date, +or to include as part of a build Action. +Common examples are timestamp strings, +revision control version strings +and other run-time generated strings. + + + +A Value Node can also be the target of a builder. + + @@ -5156,13 +5252,14 @@ to customize its behavior. A number of the main operations use callable objects which can be supplemented by writing your own. Builders, Scanners and Tools each use a kind of plugin system, -allowing you to seamlessly drop in new ones. +allowing you to easily drop in new ones. Information about creating Builder Objects and Scanner Objects appear in the following sections. -The instructions &SCons; actually uses to make things are called -Actions, and it is easy to create Action Objects and hand them +The instructions &SCons; actually uses to +construct things are called Actions, +and it is easy to create Action Objects and hand them to the objects that need to know about those actions (besides Builders, see &f-link-AddPostAction;, &f-link-AddPreAction; and &f-link-Alias; for some examples @@ -5762,14 +5859,13 @@ The canonical example here would be to set a &consvar; to the repository of a source code system. -Any additional keyword arguments supplied +Any such keyword arguments supplied when a Builder object is called will only be associated with the target created by that particular &f-Builder; call (and any other files built as a -result of the call). - -These extra keyword arguments are passed to the +result of the call). +These extra keyword arguments are passed to the following functions: command generator functions, function Actions, @@ -7249,7 +7345,7 @@ A tool specification module must include two functions: Modify the &consenv; env to set up necessary &consvars;, Builders, Emitters, etc., -so the facilities represented by the tool can be executed. +so the facilities represented by the tool can be executed. Care should be taken not to overwrite &consvars; intended to be settable by the user. For example: @@ -7506,8 +7602,8 @@ arguments to itself, not to &scons;: Second, the Cygwin shell does not -reognize typing scons -at the command line prompt as referring to this weapper. +recognize typing scons +at the command line prompt as referring to this wrapper. You can work around this either by executing scons.bat (including the extension) diff --git a/doc/scons.mod b/doc/scons.mod index 8a6df17..10c8c14 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -63,6 +63,7 @@ f77"> f90"> f95"> +flex"> gas"> gcc"> g77"> -- cgit v0.12