From f55307bcd6b047ca841549362b05479abb6b5728 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 9 Feb 2024 13:18:42 -0700 Subject: doc: update Pseudo description and more The Pseudo manpage entry is updated to be more descriptive. Since they were near neighbors in Environment.py, it and the three functions Precious, Repository and Requires received minor docstring changes there; Precious and Requires also got a minor tweak to the manpage entry (mainly to clarify allowable argument types and list return value). Signed-off-by: Mats Wichmann --- CHANGES.txt | 1 + RELEASE.txt | 1 + SCons/Environment.py | 12 +++++++++--- SCons/Environment.xml | 4 ++++ SCons/Node/__init__.py | 4 ++-- SCons/Script/Main.xml | 41 ++++++++++++++++++++++++----------------- 6 files changed, 41 insertions(+), 22 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 357cb45..30543e5 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -80,6 +80,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER Fixes #4468. - Fix bad typing in Action.py: process() and strfunction(). - Add Pseudo() to global functions, had been omitted. Fixes #4474. + The Pseudo manpage entry was updated to provide more clarity. RELEASE 4.6.0 - Sun, 19 Nov 2023 17:22:20 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index ae43db1..8afc3d9 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -80,6 +80,7 @@ DOCUMENTATION - Fixed the Scanner examples in the User Guide to be runnable and added some more explantion. Clarified discussion of the scanner function in the Scanner Objects section of the manpage. +- The manpage entry for Pseudo was clarified. DEVELOPMENT ----------- diff --git a/SCons/Environment.py b/SCons/Environment.py index 64d38b0..e61ec1f 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -2339,6 +2339,7 @@ class Base(SubstitutionEnvironment): return ret def Precious(self, *targets): + """Mark *targets* as precious: do not delete before building.""" tlist = [] for t in targets: tlist.extend(self.arg2nodes(t, self.fs.Entry)) @@ -2347,6 +2348,7 @@ class Base(SubstitutionEnvironment): return tlist def Pseudo(self, *targets): + """Mark *targets* as pseudo: must not exist.""" tlist = [] for t in targets: tlist.extend(self.arg2nodes(t, self.fs.Entry)) @@ -2355,13 +2357,17 @@ class Base(SubstitutionEnvironment): return tlist def Repository(self, *dirs, **kw) -> None: + """Specify Repository directories to search.""" dirs = self.arg2nodes(list(dirs), self.fs.Dir) self.fs.Repository(*dirs, **kw) def Requires(self, target, prerequisite): - """Specify that 'prerequisite' must be built before 'target', - (but 'target' does not actually depend on 'prerequisite' - and need not be rebuilt if it changes).""" + """Specify that *prerequisite* must be built before *target*. + + Creates an order-only relationship, not a full dependency. + *prerequisite* must exist before *target* can be built, but + a change to *prerequisite* does not trigger a rebuild of *target*. + """ tlist = self.arg2nodes(target, self.fs.Entry) plist = self.arg2nodes(prerequisite, self.fs.Entry) for t in tlist: diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 89d9b49..94dab08 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -2988,6 +2988,10 @@ but the target file(s) do not actually depend on the prerequisites and will not be rebuilt simply because the prerequisite file(s) change. +target and +prerequisite may each +be a string or Node, or a list of strings or Nodes. +Returns a list of the affected target nodes. diff --git a/SCons/Node/__init__.py b/SCons/Node/__init__.py index 3da4faf..c3a671c 100644 --- a/SCons/Node/__init__.py +++ b/SCons/Node/__init__.py @@ -1230,7 +1230,7 @@ class Node(metaclass=NoSlotsPyPy): self.precious = precious def set_pseudo(self, pseudo: bool = True) -> None: - """Set the Node's precious value.""" + """Set the Node's pseudo value.""" self.pseudo = pseudo def set_noclean(self, noclean: int = 1) -> None: @@ -1250,7 +1250,7 @@ class Node(metaclass=NoSlotsPyPy): self.always_build = always_build def exists(self) -> bool: - """Does this node exists?""" + """Reports whether node exists.""" return _exists_map[self._func_exists](self) def rexists(self): diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index 9248668..36e7d30 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -725,13 +725,12 @@ Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) -Marks each given -target -as precious so it is not deleted before it is rebuilt. Normally -&scons; -deletes a target before building it. -Multiple targets can be passed in to a single call to -&f-Precious;. +Marks target as precious so it is not +deleted before it is rebuilt. +Normally &SCons; deletes a target before building it. +Multiple targets can be passed in a single call, +and may be strings and/or nodes. +Returns a list of the affected target nodes. @@ -742,16 +741,24 @@ Multiple targets can be passed in to a single call to -This indicates that each given -target -should not be created by the build rule, and if the target is created, -an error will be generated. This is similar to the gnu make .PHONY -target. However, in the vast majority of cases, an -&f-Alias; -is more appropriate. - -Multiple targets can be passed in to a single call to -&f-Pseudo;. +Marks target as a pseudo target, +not representing the production of any physical target file. +If any pseudo target does exist, +&SCons; will abort the build with an error. +Multiple targets can be passed in a single call, +and may be strings and/or Nodes. +Returns a list of the affected target nodes. + + + +&f-Pseudo; may be useful in conjuction with a builder +call (such as &f-link-Command;) which does not create a physical target, +and the behavior if the target accidentally existed would be incorrect. +This is similar in concept to the GNU make +.PHONY target. +&SCons; also provides a powerful target alias capability +(see &f-link-Alias;) which may provide more flexibility +in many situations when defining target names that are not directly built. -- cgit v0.12