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 4484d0cffdeab746bd48b7973342cee91904817d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 30 Apr 2020 11:03:46 -0600 Subject: manpage: tweaks to EXTENDING SCONS section [ci skip] * Lots of markup changes * Some wording changes. * Some lists compacted into instead of when it didn't need necessary to have linfeed+intent following the term. That is, using the inline style: term - descriptiong of term * Several inline lists of arguments to passed functions were broken out into for better readability. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 587 +++++++++++++++++++++++++----------------------------- 1 file changed, 270 insertions(+), 317 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index c201f05..cd840b6 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4764,7 +4764,7 @@ to a &consenv;. you should only need to add a new Builder object when you want to build a new type of file or other external target. If you just want to invoke a different compiler or other tool -to build a Program, Object, Library, or any other +to build &Program;, &Object;, &Library;, or any other type of output file for which &scons; already has an existing Builder, @@ -4772,22 +4772,22 @@ it is generally much easier to use those existing Builders in a &consenv; that sets the appropriate &consvars; -(CC, LINK, etc.). +(CC, LINK, etc.). Builder objects are created using the -Builder -function. +&f-link-Builder; +factory function. The -Builder +&f-Builder; function accepts the following keyword arguments: - action + action The command line string used to build the target from the source. -action +action can also be: a list of strings representing the command to be executed and its arguments @@ -4801,42 +4801,41 @@ an Action object (see the next section); or a list of any of the above. -An action function -takes three arguments: -source -- a list of source nodes, -target -- a list of target nodes, -env -- the &consenv;. +An action function takes three arguments: + + + source - a list of source nodes;. + target - a list of target nodes;. + env - the &consenv;. + The -action +action and -generator +generator arguments must not both be used for the same Builder. - prefix + prefix The prefix that will be prepended to the target file name. -This may be specified as: +prefix may be: - a string - a callable object - + a string + a callable object - a function or other callable that takes two arguments (a &consenv; and a list of sources) and returns a prefix - a dictionary - + a dictionary - specifies a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix. Both the source suffix and target prefix specifications may use environment variable substitution, and the target prefix (the 'value' entries in the dictionary) may also be a callable object. The default target prefix -may be indicated by a dictionary entry with a key value of None. +may be indicated by a dictionary entry with a key value of None. @@ -4857,7 +4856,7 @@ b = Builder("build_it < $SOURCE > $TARGET", - suffix + suffix The suffix that will be appended to the target file name. This may be specified in the same manner as the prefix above. @@ -4885,12 +4884,12 @@ b = Builder("build_it < $SOURCE > $TARGET", - ensure_suffix + ensure_suffix When set to any true value, causes &scons; to add the target suffix specified by the -suffix +suffix keyword to any target strings that have a different suffix. (The default behavior is to leave untouched @@ -4917,7 +4916,7 @@ env.B2('bar.txt', 'bar.in') - src_suffix + src_suffix The expected source file name suffix. This may be a string or a list of strings. @@ -4925,7 +4924,7 @@ of strings. - target_scanner + target_scanner A Scanner object that will be invoked to find @@ -4943,7 +4942,7 @@ for information about creating Scanner objects. - source_scanner + source_scanner A Scanner object that will be invoked to @@ -4953,10 +4952,10 @@ used to build this target file. This is where you would specify a scanner to find things like -#include +#include lines in source files. The pre-built -DirScanner +DirScanner Scanner object may be used to indicate that this Builder should scan directory trees @@ -4970,7 +4969,7 @@ for information about creating your own Scanner objects. - target_factory + target_factory A factory function that the Builder will use to turn any targets specified as strings into SCons Nodes. @@ -4994,7 +4993,7 @@ env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) -Note that the call to the MakeDirectory Builder +Note that the call to this MakeDirectory Builder needs to specify an empty source list to make the string represent the builder's target; without that, it would assume the argument is the source, @@ -5006,7 +5005,7 @@ and a circular dependency. - source_factory + source_factory A factory function that the Builder will use to turn any sources specified as strings into SCons Nodes. @@ -5033,12 +5032,12 @@ env.Collect('archive', ['directory_name', 'file_name']) - emitter + emitter A function or list of functions to manipulate the target and source lists before dependencies are established and the target(s) are actually built. -emitter +emitter can also be a string containing a &consvar; to expand to an emitter function or list of functions, or a dictionary mapping source file suffixes @@ -5047,15 +5046,15 @@ to emitter functions. is used to select the actual emitter function from an emitter dictionary.) -An emitter function -takes three arguments: -source -- a list of source nodes, -target -- a list of target nodes, -env -- the &consenv;. -An emitter must return a tuple containing two lists, +An emitter function takes three arguments: + + + source - a list of source nodes. + target - a list of target nodes. + env - the &consenv;. + + +An emitter must return a tuple containing two lists, the list of targets to be built by this builder, and the list of sources for this builder. @@ -5100,10 +5099,11 @@ b = Builder("my_build < $TARGET > $SOURCE", - multi + multi Specifies whether this builder is allowed to be called multiple times for -the same target file(s). The default is 0, which means the builder +the same target file(s). The default is 0, +which means the builder can not be called multiple times for the same target file(s). Calling a builder multiple times for the same target simply adds additional source files to the target; it is not allowed to change the environment associated @@ -5114,7 +5114,7 @@ builder with the target. - env + env A &consenv; that can be used to fetch source code using this Builder. @@ -5127,7 +5127,7 @@ used to call the Builder for the target file.) - generator + generator A function that returns a list of actions that will be executed to build the target(s) from the source(s). @@ -5136,20 +5136,20 @@ an Action object, or anything that can be converted into an Action object (see the next section). -The generator function -takes four arguments: -source -- a list of source nodes, -target -- a list of target nodes, -env -- the &consenv;, -for_signature -- a Boolean value that specifies -whether the generator is being called -for generating a build signature -(as opposed to actually executing the command). -Example: +The generator function takes four arguments: + + + source - A list of source nodes;. + target - A list of target nodes;. + env - the &consenv;. + for_signature - + A Boolean value that specifies + whether the generator is being called + for generating a build signature + (as opposed to actually executing the command). + + +Example: def g(source, target, env, for_signature): @@ -5168,7 +5168,7 @@ arguments must not both be used for the same Builder. - src_builder + src_builder Specifies a builder to use when a source file name suffix does not match any of the suffixes of the builder. Using this argument produces a @@ -5177,20 +5177,21 @@ multi-stage builder. - single_source + single_source Specifies that this builder expects exactly one source file per call. Giving more than one source file without target files results in implicitly calling the builder multiple times (once for each source given). Giving multiple -source files together with target files results in a UserError exception. +source files together with target files results in a +UserError exception. - source_ext_match + source_ext_match When the specified -action +action argument is a dictionary, the default behavior when a builder is passed multiple source files is to make sure that the @@ -5198,29 +5199,29 @@ extensions of all the source files match. If it is legal for this builder to be called with a list of source files with different extensions, this check can be suppressed by setting -source_ext_match +source_ext_match to -None +None or some other non-true value. When -source_ext_match +source_ext_match is disable, &scons; will use the suffix of the first specified source file to select the appropriate action from the -action +action dictionary. In the following example, the setting of -source_ext_match +source_ext_match prevents &scons; from exiting with an error due to the mismatched suffixes of -foo.in +foo.in and -foo.extra. +foo.extra. b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, @@ -5234,7 +5235,7 @@ env.MyBuild('foo.out', ['foo.in', 'foo.extra']) - env + env A &consenv; that can be used to fetch source code using this Builder. @@ -5254,19 +5255,19 @@ env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') - chdir + chdir A directory from which scons will execute the action(s) specified for this Builder. If the -chdir +chdir argument is a string or a directory Node, scons will change to the specified directory. If the -chdir +chdir is not a string or Node and is non-zero, then scons will change to the @@ -5277,9 +5278,9 @@ target file's directory. automatically modify its expansion of &consvars; like -$TARGET +$TARGET and -$SOURCE +$SOURCE when using the chdir keyword argument--that is, the expanded file names @@ -5290,9 +5291,9 @@ relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like -${TARGET.file} +${TARGET.file} and -${SOURCE.file} +${SOURCE.file} to use just the filename portion of the targets and source. @@ -5307,7 +5308,7 @@ env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') Python only keeps one current directory location for all of the threads. This means that use of the -chdir +chdir argument will not @@ -5323,7 +5324,7 @@ when they start changing directory. Any additional keyword arguments supplied when a Builder object is created -(that is, when the Builder() function is called) +(that is, when the &f-link-Builder; function is called) will be set in the executing construction environment when the Builder object is called. The canonical example here would be @@ -5331,11 +5332,9 @@ to set a &consvar; to the repository of a source code system. Any additional keyword arguments supplied -when a Builder -object -is called +when a Builder object is called will only be associated with the target -created by that particular Builder call +created by that particular &f-Builder; call (and any other files built as a result of the call). @@ -5351,18 +5350,15 @@ and emitter functions. Action Objects The -Builder() +&f-link-Builder; function will turn its -action +action keyword argument into an appropriate internal Action object. You can also explicitly create Action objects -using the -Action() -global function, +using the &f-link-Action; global function, which can then be passed to the -Builder() -function. +&f-Builder; function. This can be used to configure an Action object more flexibly, or it may simply be more efficient @@ -5372,14 +5368,14 @@ when multiple Builder objects need to do the same thing. The -Action() +&f-link-Action; global function returns an appropriate object for the action represented by the type of the first argument: - Action + action If the first argument is already an Action object, the object is simply returned. @@ -5387,7 +5383,7 @@ the object is simply returned. - String + string If the first argument is a string, a command-line Action is returned. @@ -5422,7 +5418,7 @@ Action('-build $TARGET $SOURCES') - List + list If the first argument is a list, then a list of Action objects is returned. @@ -5446,23 +5442,26 @@ Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) - Function + function If the first argument is a Python function, a function Action is returned. -The Python function must accept three keyword arguments, -target -(a Node object representing the target file), -source -(a Node object representing the source file) -and -env -(the &consenv; -used for building the target file). +The Python function must accept three keyword arguments: + + + target - + a Node object representing the target file. + source - + a Node object representing the source file. + env - + the &consenv; used for building the target file. + + + The -target +target and -source +source arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may @@ -5477,7 +5476,7 @@ source_file_names = [str(x) for x in source] The function should return 0 or -None +None to indicate a successful build of the target file(s). The function may raise an exception or return a non-zero exit status @@ -5492,13 +5491,14 @@ a = Action(build_it) If the action argument is not one of the above, -None is returned. +None is returned. -The second argument is optional and is used to define the output +The second argument to &f-Action; +is optional and is used to define the output which is printed when the Action is actually performed. In the absence of this parameter, or if it's an empty string, @@ -5510,30 +5510,33 @@ The argument must be either a Python function or a string. it's a function that returns a string to be printed to describe the action being executed. The function may also be specified by the -strfunction= +strfunction= keyword argument. Like a function to build a file, -this function must accept three keyword arguments: -target -(a Node object representing the target file), -source -(a Node object representing the source file) -and -env -(a &consenv;). -The -target +this function must accept three keyword arguments: + + + source - + a Node object representing the source file. + target - + a Node object representing the target file. + env - the &consenv;. + + +The +target and -source +source arguments may be lists of Node objects if there is more than one target file or source file. In the second case, you provide the string itself. The string may also be specified by the -cmdstr= +cmdstr= keyword argument. The string typically contains variables, notably -$TARGET(S) and $SOURCE(S), or consists of just a single +$TARGET(S) and $SOURCE(S), +or consists of just a single variable, which is optionally defined somewhere else. SCons itself heavily uses the latter variant. @@ -5564,7 +5567,7 @@ may either be a &consvar; or a list of &consvars; whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. The variables may also be specified by a -varlist= +varlist= keyword parameter; if both are present, they are combined. This is necessary whenever you want a target to be rebuilt @@ -5594,18 +5597,21 @@ can be passed the following optional keyword arguments to modify the Action object's behavior: + + + chdir + -chdir -specifies that +Specifies that scons will execute the action after changing to the specified directory. If the -chdir +chdir argument is a string or a directory Node, scons will change to the specified directory. If the -chdir +chdir argument is not a string or Node and is non-zero, @@ -5617,9 +5623,7 @@ target file's directory. automatically modify its expansion of &consvars; like -$TARGET -and -$SOURCE +&cv-TARGET; and &cv-SOURCE; when using the chdir keyword argument--that is, the expanded file names @@ -5630,9 +5634,9 @@ relative to the chdir directory. Builders created using chdir keyword argument, will need to use &consvar; expansions like -${TARGET.file} +${TARGET.file} and -${SOURCE.file} +${SOURCE.file} to use just the filename portion of the targets and source. @@ -5640,10 +5644,13 @@ targets and source. a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=1) - + + + + exitstatfunc + -exitstatfunc -specifies a function +A function that is passed the exit status (or return value) from the specified action @@ -5663,11 +5670,13 @@ def always_succeed(s): a = Action("build < ${SOURCE.file} > ${TARGET.file}", exitstatfunc=always_succeed) - - + + + + batch_key + -batch_key -specifies that the Action can create multiple target files +Specifies that the Action can create multiple target files by processing multiple independent source files simultaneously. (The canonical example is "batch compilation" of multiple object files @@ -5675,7 +5684,7 @@ by passing multiple source files to a single invocation of a compiler such as Microsoft's Visual C / C++ compiler.) If the -batch_key +batch_key argument evaluates True and is not a callable object, the configured Action object will cause &scons; @@ -5696,7 +5705,7 @@ a = Action('build $CHANGED_SOURCES', batch_key=True) The -batch_key +batch_key argument may also be a callable function that returns a key that @@ -5704,61 +5713,43 @@ will be used to identify different "batches" of target files to be collected for batch building. A -batch_key +batch_key function must accept the following arguments: - - - action - -The action object. - - - - - env - -The &consenv; -configured for the target. - - - - - target - -The list of targets for a particular configured action. - - - - - source - -The list of source for a particular configured action. + + action - The action object. + env - + The &consenv; configured for the target. + target - + The list of targets for a particular configured action. + source - + The list of source for a particular configured action. + The returned key should typically be a tuple of values derived from the arguments, using any appropriate logic to decide how multiple invocations should be batched. For example, a -batch_key +batch_key function may decide to return the value of a specific construction variable from the -env +env argument which will cause &scons; to batch-build targets with matching values of that variable, or perhaps return the -id() +Python id() of the entire &consenv;, in which case &scons; will batch-build all targets configured with the same &consenv;. Returning -None +None indicates that the particular target should not @@ -5803,8 +5794,7 @@ appropriate time. (In Object-Oriented terminology, these are actually Action -Factory -functions +Factory functions that return Action objects.) In practice, @@ -5819,7 +5809,7 @@ to perform the action at the time the SConscript file is being read, you can use the -Execute +&f-link-Execute; global function to do so: @@ -5829,9 +5819,7 @@ Execute(Touch('file')) Second, you can use these functions to supply Actions in a list -for use by the -Command -method. +for use by the &f-link-env-Command; method. This can allow you to perform more complicated sequences of file manipulation @@ -5851,13 +5839,13 @@ env.Command('foo.out', 'foo.in', - Chmod(dest, mode) + Chmod(dest, mode) Returns an Action object that changes the permissions on the specified -dest +dest file or directory to the specified -mode +mode which can be octal or string, similar to the bash command. Examples: @@ -5879,13 +5867,13 @@ env.Command('foo.out', 'foo.in', - Copy(dest, src) + Copy(dest, src) Returns an Action object that will copy the -src +src source file or directory to the -dest +dest destination file or directory. Examples: @@ -5900,22 +5888,21 @@ env.Command('bar.out', 'bar.in', - Delete(entry, [must_exist]) + Delete(entry, [must_exist]) Returns an Action that deletes the specified -entry, +entry, which may be a file or a directory tree. If a directory is specified, the entire directory tree will be removed. If the -must_exist -flag is set, +must_exist +flag is set to a True value, then a Python error will be thrown if the specified entry does not exist; -the default is -must_exist=0, +the default is False, that is, the Action will silently do nothing if the entry does not exist. Examples: @@ -5934,12 +5921,12 @@ Execute(Delete('file_that_must_exist', must_exist=1)) - Mkdir(dir) + Mkdir(dir) Returns an Action that creates the specified directory -dir . +dir. Examples: @@ -5956,14 +5943,14 @@ env.Command('foo.out', 'foo.in', - Move(dest, src) + Move(dest, src) Returns an Action that moves the specified -src +src file or directory to the specified -dest +dest file or directory. Examples: @@ -5979,20 +5966,19 @@ env.Command('output_file', 'input_file', - Touch(file) + Touch(file) Returns an Action that updates the modification time on the specified -file. +file. Examples: Execute(Touch('file_to_be_touched')) -env.Command('marker', 'input_file', - [MyBuildAction, - Touch('$TARGET')]) +env.Command('marker', 'input_file', + action=[MyBuildAction, Touch('$TARGET')]) @@ -6005,11 +5991,12 @@ env.Command('marker', 'input_file', Before executing a command, &scons; -performs &consvar; interpolation on the string that makes up +performs &consvar; substitution on the string that makes up the command line of the builder. -Variables are introduced in such strings by a -$ -prefix. +&Consvars; to be interpolated are indicated in the +string with a leading +$, to distinguish them from plain text +which is not to be substituted. Besides regular &consvars;, scons provides the following special variables for each command execution: @@ -6104,11 +6091,11 @@ cc -c -o foo foo.c bar.c Variable names may be surrounded by curly braces -{ } +({}) to separate the name from surrounding characters which are not part of the name. -Within the curly braces, a variable name may have -a Python slice subscript appended to select one +Within the curly braces, a variable name may use +Python list subscripting/slicing notation to select one or more items from a list. In the previous example, the string: ${SOURCES[1]} @@ -6119,13 +6106,13 @@ bar.c Additionally, a variable name may -have the following special +have the following modifiers appended within the enclosing curly braces -to modify the interpolated string: +to access properties of the interpolated string: - base + base The base path of the file name, including the directory path @@ -6134,14 +6121,14 @@ but excluding any suffix. - dir + dir The name of the directory in which the file exists. - file + file The file name, minus any directory portion. @@ -6149,43 +6136,39 @@ minus any directory portion. - filebase + filebase -Just the basename of the file, -minus any suffix -and minus the directory. +Like file +but minus its suffix.. - suffix + suffix Just the file suffix. - abspath + abspath The absolute path name of the file. - posix + posix -The POSIX form of the path, -with directories separated by -/ -(forward slashes) -not backslashes. -This is sometimes necessary on Windows systems +The path with directories separated by forward slashes +(/). +Sometimes necessary on Windows systems when a path references a file on other (POSIX) systems. - srcpath + srcpath The directory and file name to the source file linked to this file through VariantDir(). @@ -6195,7 +6178,7 @@ it just returns the directory and filename unchanged. - srcdir + srcdir The directory containing the source file linked to this file through VariantDir(). @@ -6205,7 +6188,7 @@ it just returns the directory part of the filename. - rsrcpath + rsrcpath The directory and file name to the source file linked to this file through VariantDir(). @@ -6217,7 +6200,7 @@ directory and filename unchanged. - rsrcdir + rsrcdir The Repository directory containing the source file linked to this file through VariantDir(). @@ -6255,7 +6238,7 @@ to enclose arbitrary Python code to be evaluated. (In fact, this is how the above modifiers are substituted, they are simply attributes of the Python objects that represent &cv-TARGET;, &cv-SOURCES;, etc.) -See the section "Python Code Substitution" below, +See below for more thorough examples of how this can be used. @@ -6266,37 +6249,16 @@ associated with a The function should accept four arguments: - - - target - -a list of target nodes - - - - - source - -a list of source nodes - - - - - env - -the &consenv; - - - - - for_signature - -a Boolean value that specifies -whether the function is being called -for generating a build signature. - - - + + target - a list of target nodes + source - a list of source nodes + env - the &consenv; + for_signature - + a Boolean value that specifies + whether the function is being called + for generating a build signature. + + SCons will insert whatever @@ -6384,7 +6346,7 @@ echo Last build occurred . > $TARGET Any Python code within curly braces -{} +({}) and introduced by the variable prefix $ will be evaluated using the Python eval statement, with the Python globals set to @@ -6443,7 +6405,7 @@ command lines: - String + string When the value is a string it is interpreted as a space delimited list of command line arguments. @@ -6451,7 +6413,7 @@ command line arguments. - List + list When the value is a list it is interpreted as a list of command line arguments. Each element of the list is converted to a string. @@ -6459,7 +6421,7 @@ arguments. Each element of the list is converted to a string. - Other + other Anything that is not a list or string is converted to a string and interpreted as a single command line argument. @@ -6467,12 +6429,12 @@ interpreted as a single command line argument. - Newline + newline -Newline characters (\n) delimit lines. The newline parsing is done after +Newline characters (\n) delimit lines. +The newline parsing is done after all other parsing, so it is not possible for arguments (e.g. file names) to -contain embedded newline characters. This limitation will likely go away in -a future version of SCons. +contain embedded newline characters. @@ -6494,7 +6456,7 @@ function accepts the following arguments: function This can be either: - + a Python function that will process the Node (file) @@ -6508,52 +6470,43 @@ a dictionary that maps keys (typically the file suffix, but see below for more discussion) to other Scanners that should be called. - + If the argument is a Python function, the function must accept three required arguments and an optional fourth: -def scanner_function(node, env, path, arg=None): -The -node -argument is the internal -&SCons; node representing the file. -Use -str(node) -to fetch the name of the file, and -node.get_contents() -to fetch contents of the file. -Note that the file is -not -guaranteed to exist before the scanner is called, -so the scanner function should check that -if there's any chance that the scanned file -might not exist -(for example, if it's built from other files). + + node - + The internal &SCons; node representing the file. + Use str(node) + to fetch the name of the file, and + node.get_contents() + to fetch the contents of the file. + Note that the file is + not + guaranteed to exist before the scanner is called, + so the scanner function should check that + if there's any chance that the scanned file + might not exist + (for example, if it's built from other files). + + env - The &consenv; for the scan. + path - + A tuple (or list) + of directories that can be searched + for files. + This will usually be the tuple returned by the + path_function + argument (see below). + + arg - + The argument supplied when the scanner was created, if any + (default None. + + -The -env -argument is the &consenv; for the scan. -Fetch values from it using the -&f-env-Dictionary; -method or using dictionary key lookup -directly on the &consenv;. - -The -path -argument is a tuple (or list) -of directories that can be searched -for files. -This will usually be the tuple returned by the -path_function -argument (see below). - -The -arg -argument is the argument supplied -when the scanner was created, if any. -- cgit v0.12 From 6b171b43acef2d92f39418d3d1eebf3cb8721840 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 3 May 2020 08:58:28 -0600 Subject: Tweaks to manpage special modifiers wording [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index cd840b6..1e7964f 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6168,6 +6168,18 @@ when a path references a file on other (POSIX) systems. + windows + +The path with directories separated by backslashes. +(\\). +Sometimes necessary on POSIX-style systems +when a path references a file on other (Windows) systems. +win32 is a (deprecated) synonym for +windows. + + + + srcpath The directory and file name to the source file linked to this file through @@ -6233,6 +6245,13 @@ ${SOURCE.rsrcpath} => /usr/repository/src/file.x ${SOURCE.rsrcdir} => /usr/repository/src + +Modifiers can be combined, like +${TARGET.base.windows}, +${TARGET.srcpath.base), +${TARGET.file.suffix}, etc. + + Note that curly braces braces may also be used to enclose arbitrary Python code to be evaluated. (In fact, this is how the above modifiers are substituted, @@ -6483,7 +6502,9 @@ and an optional fourth: Use str(node) to fetch the name of the file, and node.get_contents() - to fetch the contents of the file. + to fetch the contents of the file as bytes or + node.get_text_contents() + to fetch the contents as text. Note that the file is not guaranteed to exist before the scanner is called, -- 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