From 1dbd7d0cb5cf4b2e0e5261a6b10c6c255a440757 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 29 Apr 2020 06:59:28 -0600 Subject: Document env.Detect [ci skip] Add description of the Detect method, which has been around but not listed in the documentation. Tweak some other wording in the same doc file. Fixes #3441 Signed-off-by: Mats Wichmann --- src/engine/SCons/Environment.xml | 57 ++++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 20 deletions(-) diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 5dea66e..213ac90 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1156,7 +1156,7 @@ Such a function must accept the following four arguments: -dependency +dependency The Node (file) which @@ -1170,7 +1170,7 @@ was built. -target +target The Node (file) being built. @@ -1183,7 +1183,7 @@ has "changed." -prev_ni +prev_ni Stored information about the state of the @@ -1199,7 +1199,7 @@ size, or content signature. -repo_node +repo_node If set, use this Node instead of the one specified by @@ -1220,10 +1220,9 @@ target only exists in a Repository. The function -should return a -True -(non-zero) -value if the +should return a value which evaluates +True +if the dependency has "changed" since the last time the @@ -1232,9 +1231,8 @@ was built (indicating that the target should be rebuilt), -and -False -(zero) +and a value which evaluates +False otherwise (indicating that the target should not @@ -1308,6 +1306,28 @@ env.Depends(bar, installed_lib) + + +(progs) + + + +Returns the first value from progs +(which may be a string or a list of strings) +which is found by looking in the paths specified +by PATH in the ENV +attribute of env, or None. +The method is designed to look for executable programs, +so it applies the filename suffixes found in +PATHEXT in the ENV +attribute of env in attempting +matches but returns only the bare name from +progs. + + + + + ([vars]) @@ -1769,9 +1789,8 @@ repository or source directory. The ondisk -argument may be set to -False -(or any other non-true value) +argument may be set to a value which evaluates +False to disable the search for matches on disk, thereby only returning matches among already-configured File or Dir Nodes. @@ -1783,9 +1802,8 @@ for any on-disk matches found. The source -argument may be set to -True -(or any equivalent value) +argument may be set to a value which evaluates +True to specify that, when the local directory is a &f-VariantDir;, @@ -1797,9 +1815,8 @@ not the local directory. The strings -argument may be set to -True -(or any equivalent value) +argument may be set to a value which evaluates +True to have the &f-Glob; function return strings, not Nodes, -- cgit v0.12 From 5686bfc3594d8107ab4e63c4009694986675f99f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 4 May 2020 10:00:35 -0600 Subject: [PR #3631] clarify Detect and WhereIs [ci skip] Per review comment, simplfy the way the consenv values are referred to, and add a reference to env.WhereIs. env.WhereIs had some issues as well, so updated: clarified the difference between env. version and global version, and found the Note at the end to use SCons.Util.WhereIs was not needed, since the global function WhereIs is exactly SCons.Util.WhereIs: Script/__init__.py: WhereIs = SCons.Util.WhereIs Signed-off-by: Mats Wichmann --- src/engine/SCons/Environment.xml | 82 ++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 213ac90..ff3e385 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -1312,22 +1312,20 @@ env.Depends(bar, installed_lib) +Find an executable from one or more choices: +progs may be a string or a list of strings. Returns the first value from progs -(which may be a string or a list of strings) -which is found by looking in the paths specified -by PATH in the ENV -attribute of env, or None. -The method is designed to look for executable programs, -so it applies the filename suffixes found in -PATHEXT in the ENV -attribute of env in attempting -matches but returns only the bare name from -progs. +that was found, or None. +Executable is searched by checking the paths specified +by env['ENV']['PATH']. +On Windows systems, additionally applies the filename suffixes found in +env['ENV']['PATHEXT'] +but will not include any such extension in the return value. +&f-env-Detect; is a wrapper around &f-link-env-WhereIs;. - ([vars]) @@ -3320,51 +3318,53 @@ SConscript(dirs='doc', variant_dir='build/doc', duplicate=0) Searches for the specified executable program, -returning the full path name to the program -if it is found, else None. -Searches the value of the +returning the full path to the program +or None. + + +When called as a &consenv; method, +searches the paths in the path keyword argument, -or if None (the default) -the value of the calling environment's PATH -(env['ENV']['PATH']). -If path is None and -the env['ENV']['PATH'] key does not exist, -the user's current external PATH -(os.environ['PATH']) is used as fallback. +or if None (the default) +the paths listed in the &consenv; +(env['ENV']['PATH']). +The external environment's path list +(os.environ['PATH']) +is used as a fallback if the key +env['ENV']['PATH'] +does not exist. On Windows systems, searches for executable programs with any of the file extensions listed in the pathext keyword argument, or if None (the default) -the calling environment's PATHEXT -(env['ENV']['PATHEXT']). -The user's current external PATHEXT +the pathname extensions listed in the &consenv; +(env['ENV']['PATHEXT']). +The external environment's pathname extensions list (os.environ['PATHEXT']) -is used as a fallback if pathext is -None -and the key env['ENV']['PATHEXT'] +is used as a fallback if the key +env['ENV']['PATHEXT'] does not exist. +When called as a global function, uses the external +environment's path +os.environ['PATH'] +and path extensions +os.environ['PATHEXT'], +respectively, if +path and +pathext are +None. + + Will not select any path name or names -in the specified +in the optional reject -list, if any. - - - -If you would prefer to search -the user's current external PATH -(os.environ['PATH']) -by default, -consider using the function SCons.Util.WhereIs instead. -Note that SCons.Util.WhereIs -does not expand environment variables automatically -(no implicit env.subst for its arguments). +list. - -- cgit v0.12