From 8f38c68b367cf12b83281c30b420fbd8ad6a573f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 5 Jun 2022 15:43:49 -0600 Subject: Tweaked Builder intro section in manpage [skip appveyor] Mostly wording changes, some rearranging/grouping. Makes sure the three documented recognized kwargs are listed together, followed by the statement that unrecognized kwargs are consvar overrides. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 343 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 181 insertions(+), 162 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 4578d1c..8e64290 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2612,28 +2612,35 @@ and specifically Tool Modules. Builder Methods -You tell &scons; what to build +You tell &SCons; what to build by calling Builders, -functions which take -particular action(s) to produce a particular result type -(conventionally described by the builder name such as &b-Program;) -when given source files of a particular type. -Calling a builder defines one or more targets to the build system; -whether the targets are actually built on a given -invocation is determined by command-line options, -target selection rules, and whether &SCons; -determines the target(s) are out of date. +functions which take particular action(s) +to produce target(s) of a particular type +(conventionally hinted at by the builder name, e.g. &Program;) +from the specified source files. +A builder call is a declaration: &SCons; enters the +specified relationship into its internal dependency node graph, +and only later makes the decision on whether anything is actually built, +since this depends on command-line options, +target selection rules, and whether the target(s) are +out of date with respect to the sources. &SCons; -defines a number of builders, and you can also write your own. -Builders are attached to a &consenv; as methods, -and the available builder methods are listed as +provides a number of builders, and you can also write your own +(see Builder Objects). +Builders are created dynamically at run-time, +often (though not always) by tools which determine +whether the external dependencies for the builder are satisfied, +and which perform the necessary setup +(see Tools). +Builers are attached to a &consenv; as methods. +The available builder methods are registered as key-value pairs in the -BUILDERS attribute of the &consenv;. -The available builders can be displayed like this -for debugging purposes: +&cv-link-BUILDERS; attribute of the &consenv;, +so the available builders can be examined. +This example displays them for debugging purposes: @@ -2646,7 +2653,6 @@ Builder methods take two required arguments: target and source. -Either can be passed as a scalar or as a list. The target and source arguments can be specified either as positional arguments, @@ -2660,24 +2666,17 @@ Builder methods also take a variety of keyword arguments, described below. - -The builder may add other targets -beyond those requested if indicated by an Emitter -(see and, for example, -&cv-link-PROGEMITTER; for more information). - - Because long lists of file names -can lead to a lot of quoting, -&scons; +can lead to a lot of quoting in a builder call, +&SCons; supplies a &f-link-Split; global function and a same-named environment method that splits a single string into a list, using -strings of white-space characters as the delimiter. +strings of white-space characters as the delimiter (similar to the Python string split -method, but succeeds even if the input isn't a string.) +method, but succeeds even if the input isn't a string). The following are equivalent examples of calling the @@ -2695,9 +2694,12 @@ env.Program('bar', source='bar.c foo.c'.split()) -Python follows the POSIX pathname convention for path -strings: if a string begins with the operating system pathname separator -(on Windows both the slash and backslash separator work, +Sources and targets can be specified as a a scalar or as a list, +either of strings or nodes (more on nodes below). +When specifying path strings, +Python follows the POSIX pathname convention: +if a string begins with the operating system pathname separator +(on Windows both the slash and backslash separator are accepted, and any leading drive specifier is ignored for the determination) it is considered an absolute path, otherwise it is a relative path. @@ -2706,32 +2708,26 @@ it is searched for as a file in the current directory. If it contains separator characters, the search follows down from the starting point, which is the top of the directory tree for an absolute path and the current directory for a relative path. +The "current directory" in this context is the directory +of the SConscript file currently being processed. -&scons; recognizes a third way to specify +&SCons; also recognizes a third way to specify path strings: if the string begins with the # character it is top-relative - it works like a relative path but the search follows down from the directory containing the top-level &SConstruct; rather than -from the current directory. The # is allowed -to be followed by a pathname separator, which is ignored if -found in that position. +from the current directory. The # +can optionally be followed by a pathname separator, +which is ignored if found in that position. Top-relative paths only work in places where &scons; will interpret the path (see some examples below). To be used in other contexts the string will need to be converted to a relative or absolute path first. - -target and source -can be absolute, relative, or -top-relative. Relative pathnames are searched considering the -directory of the SConscript -file currently being processed as the "current directory". - - Examples: @@ -2786,14 +2782,12 @@ env.Program(source='bar.c') env.Program('bar.c') -As a convenience, a +The optional srcdir -keyword argument may be specified -when calling a Builder. -When specified, +keyword argument specifies that all source file strings that are not absolute paths or top-relative paths -will be interpreted relative to the specified +shall be interpreted relative to the specified srcdir. The following example will build the build/prog @@ -2810,6 +2804,84 @@ and env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') +The optional +parse_flags +keyword argument causes behavior similarly to the +&f-link-env-MergeFlags; method, where the argument value is +broken into individual settings and merged into the appropriate &consvars;. + + + +env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') + + +This example adds 'include' to +the &cv-link-CPPPATH; &consvar;, +'EBUG' to +&cv-link-CPPDEFINES;, +and 'm' to +&cv-link-LIBS;. + + +The optional +chdir +keyword argument +specifies that the Builder's action(s) +should be executed +after changing directory. +If the +chdir +argument is +a path string or a directory Node, +scons will change to the specified directory. +If the +chdir +is not a string or Node +and evaluates true, +then &scons; will change to the +target file's directory. + + +# scons will change to the "sub" subdirectory +# before executing the "cp" command. +env.Command( + target='sub/dir/foo.out', + source='sub/dir/foo.in', + action="cp dir/foo.in dir/foo.out", + chdir='sub', +) + +# Because chdir is not a string, scons will change to the +# target's directory ("sub/dir") before executing the +# "cp" command. +env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out", chdir=True) + + +Note that &SCons; will +not +automatically modify +its expansion of +&consvars; like +$TARGET +and +$SOURCE +when using the chdir +keyword argument--that is, +the expanded file names +will still be relative to +the top-level directory where &SConstruct; was found, +and consequently incorrect +relative to the chdir directory. +If you use the chdir keyword argument, +you will typically need to supply a different +command line using +expansions like +${TARGET.file} +and +${SOURCE.file} +to use just the filename portion of the +targets and source. + Keyword arguments that are not specifically recognized are treated as &consvar; overrides, @@ -2837,30 +2909,10 @@ env.SharedLibrary( Note that both the &cv-link-SHLIBSUFFIX; and &cv-link-LIBSUFFIXES; -variables must be set if you want &scons; to search automatically +&consvars; must be set if you want &scons; to search automatically for dependencies on the non-standard library names; see the descriptions below of these variables for more information. -The optional -parse_flags -keyword argument is recognized by builders. -This works similarly to the -&f-link-env-MergeFlags; method, where the argument value is -broken into individual settings and merged into the appropriate &consvars;. - - - -env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') - - -This example adds 'include' to -the &cv-link-CPPPATH; &consvar;, -'EBUG' to -&cv-link-CPPDEFINES;, -and 'm' to -&cv-link-LIBS;. - - Although the builder methods defined by &scons; are, in fact, @@ -2872,8 +2924,8 @@ Program('hello', 'hello.c') SharedLibrary('word', 'word.cpp') -If called this way, methods will internally use the -&defenv; that consists of the tools and values that +If called this way, the builder will internally use the +&DefEnv; that consists of the tools and values that &scons; has determined are appropriate for the local system. @@ -2888,14 +2940,31 @@ to the Python module: from SCons.Script import * -Builder methods return a NodeList, -a list-like object whose elements are Nodes, -&SCons;' internal representation of build targets or sources. -See for more information. + +A builder may add additional targets +(and, in fact, sources) beyond those requested, +if an attached Emitter chooses to do so +(see and, as an example, +&cv-link-PROGEMITTER;, for more information). +For example, the GNU linker takes a command-line argument +, +which causes it to produce a linker map file in addition +to the executable file actually being linked. +If the &b-link-Program; builder's emitter is configured +to add this mapfile if the option is set, +two targets will be returned when you only asked for one. + + + +For this reason, +builder methods always return a NodeList, +a list-like object whose elements are Nodes. +Nodes are the internal representation of build targets or sources +(see for more information). The returned NodeList object can be passed to other builder methods as source(s) -or passed to any &SCons; function or method -where a filename would normally be accepted. +or to other &SCons; functions or methods +where a path string would normally be accepted. For example, @@ -2912,7 +2981,7 @@ env.Program("prog", ['foo.c', bar_obj_list, 'main.c']) makes for a more portable build by avoiding having to specify a platform-specific object suffix -when calling the &Program; builder method. +when calling the &b-link-Program; builder method. The NodeList object @@ -2929,7 +2998,7 @@ Default(tgt) lists passed as source and target, so they are free to contain elements which are themselves lists, such as bar_obj_list -returned by the &StaticObject; call above. +returned by the &b-link-StaticObject; call. If you need to manipulate a list of lists returned by builders directly in Python code, you can either build a new list by hand: @@ -2943,7 +3012,7 @@ for obj in objects: Or you can use the &f-link-Flatten; -function supplied by &scons; +function supplied by &SCons; to create a list containing just the Nodes, which may be more convenient: @@ -2955,9 +3024,9 @@ for obj in objects: print(str(obj)) -&SCons; builder calls return +Since builder calls return a list-like object, not an actual Python list, -so it is not appropriate to use the Python add +it is not appropriate to use the Python add operator (+ or +=) to append builder results to a Python list. Because the list and the object are different types, @@ -2997,69 +3066,11 @@ print("The path to bar_obj is:", str(bar_obj_list[0])) Note that because the Builder call returns a NodeList, -you have to access the first element in the list, +you have to access the first element in the list (bar_obj_list[0] in the example) to get at the Node that actually represents the object file. -Builder calls support a -chdir -keyword argument that -specifies that the Builder's action(s) -should be executed -after changing directory. -If the -chdir -argument is -a string or a directory Node, -scons will change to the specified directory. -If the -chdir -is not a string or Node -and is non-zero, -then scons will change to the -target file's directory. - - -# scons will change to the "sub" subdirectory -# before executing the "cp" command. -env.Command('sub/dir/foo.out', 'sub/dir/foo.in', - "cp dir/foo.in dir/foo.out", - chdir='sub') - -# Because chdir is not a string, scons will change to the -# target's directory ("sub/dir") before executing the -# "cp" command. -env.Command('sub/dir/foo.out', 'sub/dir/foo.in', - "cp foo.in foo.out", - chdir=1) - - -Note that &SCons; will -not -automatically modify -its expansion of -&consvars; like -$TARGET -and -$SOURCE -when using the chdir -keyword argument--that is, -the expanded file names -will still be relative to -the top-level directory where &SConstruct; was found, -and consequently incorrect -relative to the chdir directory. -If you use the chdir keyword argument, -you will typically need to supply a different -command line using -expansions like -${TARGET.file} -and -${SOURCE.file} -to use just the filename portion of the -targets and source. - When trying to handle errors that may occur in a builder method, consider that the corresponding Action is executed at a different @@ -3073,13 +3084,22 @@ a useful exception message indicating the problem in the SConscript files - programmatically recovering from build errors is rarely useful. -&scons; -predefines the following builder methods. + +The following builder methods are predefined in the +&SCons; core software distribution. Depending on the setup of a particular &consenv; and on the type and software installation status of the underlying system, -not all builders may be available to that -&consenv;. +not all builders may be available in that +&consenv;. +Since the function calling signature is the same for all builders: + + +Buildername(target, source, [key=val, ...]) + + +it is omitted in this listing for brevity. + @@ -5585,38 +5605,37 @@ and the list of sources for this builder. def e(target, source, env): - return (target + ['foo.foo'], source + ['foo.src']) + return target + ['foo.foo'], source + ['foo.src'] # Simple association of an emitter function with a Builder. -b = Builder("my_build < $TARGET > $SOURCE", - emitter = e) +b = Builder("my_build < $TARGET > $SOURCE", emitter=e) def e2(target, source, env): - return (target + ['bar.foo'], source + ['bar.src']) + return target + ['bar.foo'], source + ['bar.src'] # Simple association of a list of emitter functions with a Builder. -b = Builder("my_build < $TARGET > $SOURCE", - emitter = [e, e2]) +b = Builder("my_build < $TARGET > $SOURCE", emitter=[e, e2]) -# Calling an emitter function through a &consvar;. +# Calling an emitter function through a construction variable. env = Environment(MY_EMITTER=e) -b = Builder("my_build < $TARGET > $SOURCE", - emitter='$MY_EMITTER') +b = Builder("my_build < $TARGET > $SOURCE", emitter='$MY_EMITTER') -# Calling a list of emitter functions through a &consvar;. +# Calling a list of emitter functions through a construction variable. env = Environment(EMITTER_LIST=[e, e2]) -b = Builder("my_build < $TARGET > $SOURCE", - emitter='$EMITTER_LIST') +b = Builder("my_build < $TARGET > $SOURCE", emitter='$EMITTER_LIST') # Associating multiple emitters with different file # suffixes using a dictionary. def e_suf1(target, source, env): - return (target + ['another_target_file'], source) + return target + ['another_target_file'], source + def e_suf2(target, source, env): - return (target, source + ['another_source_file']) -b = Builder("my_build < $TARGET > $SOURCE", - emitter={'.suf1' : e_suf1, - '.suf2' : e_suf2}) + return target, source + ['another_source_file'] + +b = Builder( + action="my_build < $TARGET > $SOURCE", + emitter={'.suf1': e_suf1, '.suf2': e_suf2} +) -- cgit v0.12 From 869c75679492039a5dcb1f66fd9a78d59a4340da Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 20 Jun 2022 08:58:35 -0600 Subject: A few more tweaks in Builder Methods intro [skip appveyor] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 50 ++++++++++++++++++++++++-------------------------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 8e64290..2e7784c 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2675,7 +2675,7 @@ and a same-named environment method that splits a single string into a list, using strings of white-space characters as the delimiter -(similar to the Python string split +(similar to the &Python; string split method, but succeeds even if the input isn't a string). @@ -2697,7 +2697,7 @@ env.Program('bar', source='bar.c foo.c'.split()) Sources and targets can be specified as a a scalar or as a list, either of strings or nodes (more on nodes below). When specifying path strings, -Python follows the POSIX pathname convention: +&Python; follows the POSIX pathname convention: if a string begins with the operating system pathname separator (on Windows both the slash and backslash separator are accepted, and any leading drive specifier is ignored for @@ -2806,7 +2806,7 @@ env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') The optional parse_flags -keyword argument causes behavior similarly to the +keyword argument causes behavior similarl to the &f-link-env-MergeFlags; method, where the argument value is broken into individual settings and merged into the appropriate &consvars;. @@ -2861,15 +2861,13 @@ env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out", chdir=True not automatically modify its expansion of -&consvars; like -$TARGET -and -$SOURCE +&consvars; like &cv-link-TARGET; +and &cv-link-SOURCE; when using the chdir keyword argument--that is, the expanded file names will still be relative to -the top-level directory where &SConstruct; was found, +the top-level directory where the &SConstruct; was found, and consequently incorrect relative to the chdir directory. If you use the chdir keyword argument, @@ -2880,7 +2878,7 @@ expansions like and ${SOURCE.file} to use just the filename portion of the -targets and source. +target and source. Keyword arguments that are not specifically recognized are treated as &consvar; @@ -2911,7 +2909,7 @@ env.SharedLibrary( and &cv-link-LIBSUFFIXES; &consvars; must be set if you want &scons; to search automatically for dependencies on the non-standard library names; -see the descriptions below of these variables for more information. +see the descriptions of these variables for more information. Although the builder methods defined by &scons; @@ -2930,11 +2928,11 @@ SharedLibrary('word', 'word.cpp') has determined are appropriate for the local system. Builder methods that can be called without an explicit -environment (indicated in the listing of builders without -a leading env.) -may be called from custom Python modules that you +environment (indicated in the listing of builders below +without a leading env.) +may be called from custom &Python; modules that you import into an SConscript file by adding the following -to the Python module: +to the &Python; module: from SCons.Script import * @@ -2942,17 +2940,17 @@ from SCons.Script import * A builder may add additional targets -(and, in fact, sources) beyond those requested, +beyond those requested if an attached Emitter chooses to do so -(see and, as an example, -&cv-link-PROGEMITTER;, for more information). +(see for more information. +&cv-link-PROGEMITTER; is an example). For example, the GNU linker takes a command-line argument , which causes it to produce a linker map file in addition to the executable file actually being linked. If the &b-link-Program; builder's emitter is configured to add this mapfile if the option is set, -two targets will be returned when you only asked for one. +then two targets will be returned when you only asked for one. @@ -3000,7 +2998,7 @@ contain elements which are themselves lists, such as bar_obj_list returned by the &b-link-StaticObject; call. If you need to manipulate a list of lists returned by builders -directly in Python code, +directly in &Python; code, you can either build a new list by hand: @@ -3025,19 +3023,19 @@ for obj in objects: Since builder calls return -a list-like object, not an actual Python list, -it is not appropriate to use the Python add +a list-like object, not an actual &Python; list, +it is not appropriate to use the &Python; add operator (+ or +=) -to append builder results to a Python list. +to append builder results to a &Python; list. Because the list and the object are different types, -Python will not update the original list in place, +&Python; will not update the original list in place, but will instead create a new NodeList object containing the concatenation of the list elements and the builder results. -This will cause problems for any other Python variables +This will cause problems for any other &Python; variables in your SCons configuration that still hold on to a reference to the original list. -Instead, use the Python list +Instead, use the &Python; list extend method to make sure the list is updated in-place. Example: @@ -3055,7 +3053,7 @@ object_files.extend(Object('bar.c')) The path name for a Node's file may be used -by passing the Node to Python's builtin +by passing the Node to &Python;'s builtin str function: -- cgit v0.12 From 773f267b2ec42b4e629d01bab51f69d49d1605c8 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 25 Jun 2022 15:31:38 -0400 Subject: minor edits plus adding a warning about using chdir --- doc/man/scons.xml | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 2e7784c..19f5eb1 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2635,7 +2635,7 @@ often (though not always) by tools which determine whether the external dependencies for the builder are satisfied, and which perform the necessary setup (see Tools). -Builers are attached to a &consenv; as methods. +Builders are attached to a &consenv; as methods. The available builder methods are registered as key-value pairs in the &cv-link-BUILDERS; attribute of the &consenv;, @@ -2694,8 +2694,8 @@ env.Program('bar', source='bar.c foo.c'.split()) -Sources and targets can be specified as a a scalar or as a list, -either of strings or nodes (more on nodes below). +Sources and targets can be specified as a scalar or as a list, +composed of either strings or nodes (more on nodes below). When specifying path strings, &Python; follows the POSIX pathname convention: if a string begins with the operating system pathname separator @@ -2806,7 +2806,7 @@ env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') The optional parse_flags -keyword argument causes behavior similarl to the +keyword argument causes behavior similar to the &f-link-env-MergeFlags; method, where the argument value is broken into individual settings and merged into the appropriate &consvars;. @@ -2841,6 +2841,23 @@ and evaluates true, then &scons; will change to the target file's directory. + + +Python only keeps one current directory +location even if there are multiple threads. +This means that use of the +chdir +argument +will +not +work with the SCons + +option, +because individual worker threads spawned +by SCons interfere with each other +when they start changing directory. + + # scons will change to the "sub" subdirectory # before executing the "cp" command. @@ -2950,7 +2967,7 @@ which causes it to produce a linker map file in addition to the executable file actually being linked. If the &b-link-Program; builder's emitter is configured to add this mapfile if the option is set, -then two targets will be returned when you only asked for one. +then two targets will be returned when you only provided for one. -- cgit v0.12