From d1c74bc17b36e4ce4f163a70ff64100b03e9c6f3 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 28 Jan 2022 06:10:02 -0700 Subject: Man: mention $$ a subst escape [skip appveyor] Some rewordings elsewhere in Variable Substitution section - mainly to a variable that's a function. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 56 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 23 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index fc2e24d..eb91d88 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6414,18 +6414,25 @@ env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) &scons; performs variable substitution on the string that makes up the action part of the builder. -Variables to be interpolated are indicated in the -string with a leading -$, to distinguish them from plain text +Variables or other text to be substituted are indicated in the +string by a leading $, +to distinguish them from plain text which is not to be substituted. -The name may be surrounded by curly braces -(${}) -to separate the name from surrounding characters if necessary. -Curly braces are required when you use +The substitutable text may be surrounded by curly braces +to separate it from surrounding characters if necessary +(for example ${FOO}BAR). +To avoid substituting a substring that looks like a variable name, +escape it with an additional $, +(for example, $$FOO will be left in the +final string as $FOO). + + +The curly brace notation is required when you use Python list subscripting/slicing notation on a variable to select one or more items from a list, or access a variable's special attributes, -or use Python expression substitution. +or when you use Python expression substitution +(see below for descriptions of these). @@ -6670,9 +6677,10 @@ echo Last build occurred . > $TARGET While &consvars; are normally directly substituted, if a variable refers to a &consvar; -whose value is a &Python; function, -that function is called during substitution. -Such a function must accept four arguments: +whose value is a callable &Python; object (a function +or a class with a __call__ method), +that object is called during substitution. +The callable must accept four arguments: target, source, env and @@ -6681,19 +6689,21 @@ Such a function must accept four arguments: target is a list of target nodes, env is the &consenv; to use for context, and for_signature is -a Boolean value that tells the function +a boolean value that tells the callable if it is being called for the purpose of generating a build signature. Since the build signature is used for rebuild determination, -the function should omit variable elements -that do not affect whether a rebuild should be triggered -(see $( -and $) -above) if for_signature is true. +variable elements that do not affect whether +a rebuild should be triggered +should be omitted from the returned string +if for_signature is true. +See $( +and $) above +for the syntax. &SCons; will insert whatever -the called function returns +the callable returns into the expanded string: @@ -6712,11 +6722,11 @@ will be exactly as it was set: "$FOO baz". You can use this feature to pass arguments to a -Python function by creating a callable class -that stores one or more arguments in an object, -and then uses them when the -__call__() -method is called. +callable variable by creating a callable class +that stores passed arguments in the instance, +and then uses them +(in the __call__ method) +when the instance is called. Note that in this case, the entire variable expansion must be enclosed by curly braces -- cgit v0.12 From 34b62e00d8f0d73c8229d82ce3805f0f72f8380f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 29 Jan 2022 09:20:37 -0700 Subject: man: drop some extra wording [ci skip] An extra stanza was added "or other text" that didn't really make sense in context, remove it again. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index eb91d88..13a06a4 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6414,7 +6414,7 @@ env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) &scons; performs variable substitution on the string that makes up the action part of the builder. -Variables or other text to be substituted are indicated in the +Variables to be substituted are indicated in the string by a leading $, to distinguish them from plain text which is not to be substituted. -- cgit v0.12 From fa23e2ff1f4f4086c9edad2a508d6d6fa281ecb1 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 9 Feb 2022 09:39:20 -0700 Subject: Updates to User Guide: 6/Dependencies Removed most references to md5 and tried to make the terminology used a bit more consistent. Added some markup - refernced functions now hyperlinked on first mention of each section. Signed-off-by: Mats Wichmann --- doc/user/depends.xml | 128 ++++++++++++++++++++++++++------------------------- 1 file changed, 65 insertions(+), 63 deletions(-) diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 90b446c..f8959a3 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -109,26 +109,26 @@ int main() { printf("Hello, world!\n"); } things when an input file changes, so that the built software is up to date. By default, - &SCons; keeps track of this through an - MD5 &signature;, or checksum, of the contents of each file, + &SCons; keeps track of this through a + content signature, + or hash, of the contents of each file, although you can easily configure &SCons; to use the - modification times (or time stamps) - instead. - You can even specify your own Python function - for deciding if an input file has changed. + modification times (or time stamps) instead. + You can even write your own Python function + for deciding if an input file should trigger a rebuild.
- Using MD5 Signatures to Decide if a File Has Changed + Using Content Signatures to Decide if a File Has Changed - By default, - &SCons; keeps track of whether a file has changed - based on an MD5 checksum of the file's contents, - not the file's modification time. + By default, &SCons; + uses a cryptographic hash of the file's contents, + not the file's modification time, + to decide whether a file has changed. This means that you may be surprised by the default &SCons; behavior if you are used to the &Make; convention of forcing @@ -168,31 +168,33 @@ int main() { printf("Hello, world!\n"); } Note that you can, if you wish, - specify this default behavior - (MD5 signatures) explicitly - using the &Decider; function as follows: + specify the default behavior of using + content signatures explicitly, + using the &f-link-Decider; function as follows: Program('hello.c') -Decider('MD5') +Decider('content') - You can also use the string 'content' - as a synonym for 'MD5' - when calling the &Decider; function. + You can also use the string 'MD5' + as a synonym for 'content' + when calling the &f-Decider; function - this older + name is deprecated since &SCons; now supports a + choice of hash functions, not just the MD5 function.
- Ramifications of Using MD5 Signatures + Ramifications of Using Content Signatures - Using MD5 signatures to decide if an input file has changed + Using content signatures to decide if an input file has changed has one surprising benefit: if a source file has been changed in such a way that the contents of the @@ -265,7 +267,7 @@ Decider('MD5') if a source file's modification time is newer than the target file. - To do this, call the &Decider; + To do this, call the &f-link-Decider; function as follows: @@ -300,7 +302,7 @@ int main() { printf("Hello, world!\n"); } as the behavior of &Make;, you can also use the string 'make' as a synonym for 'timestamp-newer' - when calling the &Decider; function: + when calling the &f-Decider; function: @@ -335,7 +337,7 @@ Decider('make') is newer than the target file. To do this, specify the argument 'timestamp-match' - when calling the &Decider; function: + when calling the &f-Decider; function: @@ -389,11 +391,11 @@ int main() { printf("Hello, world!\n"); } As a performance enhancement, &SCons; provides a way to use - MD5 checksums of file contents + a file's content signature, but to read those contents only when the file's timestamp has changed. - To do this, call the &Decider; - function with 'MD5-timestamp' + To do this, call the &f-link-Decider; + function with 'content-timestamp' argument as follows: @@ -401,7 +403,7 @@ int main() { printf("Hello, world!\n"); } Program('hello.c') -Decider('MD5-timestamp') +Decider('content-timestamp') int main() { printf("Hello, world!\n"); } @@ -411,7 +413,7 @@ int main() { printf("Hello, world!\n"); } So configured, &SCons; will still behave like - it does when using Decider('MD5'): + it does when using Decider('content'): @@ -453,7 +455,7 @@ cc -o hello hello.o will have been performed by simply looking at the modification time of the &hello_c; file, not by opening it and performing - an MD5 checksum calcuation on its contents. + a signature calcuation on its contents. This can significantly speed up many up-to-date builds. @@ -461,7 +463,7 @@ cc -o hello hello.o The only drawback to using - Decider('MD5-timestamp') + Decider('content-timestamp') is that &SCons; will not rebuild a target file if a source file was modified within one second of the last time &SCons; built the file. @@ -475,7 +477,7 @@ cc -o hello hello.o rely on the ability to apply changes to files automatically and then rebuild as quickly as possible, in which case use of - Decider('MD5-timestamp') + Decider('content-timestamp') may not be appropriate. @@ -488,7 +490,7 @@ cc -o hello hello.o The different string values that we've passed to - the &Decider; function are essentially used by &SCons; + the &f-link-Decider; function are essentially used by &SCons; to pick one of several specific internal functions that implement various ways of deciding if a dependency (usually a source file) @@ -566,13 +568,13 @@ int main() { printf("Hello, world!\n"); } - .csig + csig - The content signature, - or MD5 checksum, of the contents of the - dependency + The content signature: + a cryptgraphic hash, or checksum, of the file contents + of the dependency file the last time the ⌖ was built. @@ -580,7 +582,7 @@ int main() { printf("Hello, world!\n"); } - .size + size @@ -592,7 +594,7 @@ int main() { printf("Hello, world!\n"); } - .timestamp + timestamp @@ -689,22 +691,21 @@ env.Install("install", "test.txt") The previous examples have all demonstrated calling - the global &Decider; function + the global &f-link-Decider; function to configure all dependency decisions that &SCons; makes. Sometimes, however, you want to be able to configure different decision-making for different targets. - When that's necessary, you can use the - env.Decider + When that's necessary, you can use the &f-env-Decider; method to affect only the configuration decisions for targets built with a - specific construction environment. + specific &consenv;. For example, if we arbitrarily want to build - one program using MD5 checkums + one program using content signatures and another using file modification times from the same source we might configure it this way: @@ -716,7 +717,7 @@ env.Install("install", "test.txt") env1 = Environment(CPPPATH = ['.']) env2 = env1.Clone() env2.Decider('timestamp-match') -env1.Program('prog-MD5', 'program1.c') +env1.Program('prog-content', 'program1.c') env2.Program('prog-timestamp', 'program2.c') @@ -767,7 +768,7 @@ int main() { printf("Hello, world!\n"); } -Program('hello.c', CPPPATH = '.') +Program('hello.c', CPPPATH='.') #include <hello.h> @@ -825,8 +826,8 @@ main() First, notice that &SCons; - added the -I. argument - from the &cv-CPPPATH; variable + constructed the -I. argument + from the '.' in the &cv-CPPPATH; variable so that the compilation would find the &hello_h; file in the local directory. @@ -1104,7 +1105,7 @@ SetOption('implicit_cache', 1) &SCons; allows you to specific explicitly that one file depends on another file, and must be rebuilt whenever that file changes. - This is specified using the &Depends; method: + This is specified using the &f-link-Depends; method: @@ -1131,7 +1132,7 @@ cc -o hello hello.o Note that the dependency - (the second argument to &Depends;) + (the second argument to &f-Depends;) may also be a list of Node objects (for example, as returned by a call to a Builder): @@ -1206,7 +1207,7 @@ Program('hello', 'hello.c', CPPPATH='.') Apparently, the scanner does not know about the header dependency. - Being not a full-fledged C preprocessor, the scanner does not + Note being a full-fledged C preprocessor, the scanner does not expand the macro. @@ -1214,7 +1215,7 @@ Program('hello', 'hello.c', CPPPATH='.') In these cases, you may also use the compiler to extract the - implicit dependencies. &ParseDepends; can parse the contents of + implicit dependencies. &f-link-ParseDepends; can parse the contents of the compiler output in the style of &Make;, and explicitly establish all of the listed dependencies. @@ -1222,7 +1223,7 @@ Program('hello', 'hello.c', CPPPATH='.') - The following example uses &ParseDepends; to process a compiler + The following example uses &f-ParseDepends; to process a compiler generated dependency file which is generated as a side effect during compilation of the object file: @@ -1320,13 +1321,13 @@ scons: `.' is up to date. - &ParseDepends; immediately reads the specified file at invocation + &f-ParseDepends; immediately reads the specified file at invocation time and just returns if the file does not exist. A dependency file generated during the build process is not automatically parsed again. Hence, the compiler-extracted dependencies are not stored in the signature database during the same build pass. This - limitation of &ParseDepends; leads to unnecessary recompilations. - Therefore, &ParseDepends; should only be used if scanners are not + limitation of &f-ParseDepends; leads to unnecessary recompilations. + Therefore, &f-ParseDepends; should only be used if scanners are not available for the employed language or not powerful enough for the specific task. @@ -1344,7 +1345,8 @@ scons: `.' is up to date. even if a dependency file changes. In this case, you would tell &SCons; specifically - to ignore a dependency as follows: + to ignore a dependency using the + &f-link-Ignore; function as follows: @@ -1414,7 +1416,7 @@ Ignore(hello, '/usr/include/stdio.h') - &Ignore; can also be used to prevent a generated file from being built + &f-Ignore; can also be used to prevent a generated file from being built by default. This is due to the fact that directories depend on their contents. So to ignore a generated file from the default build, you specify that the directory should ignore the generated file. @@ -1535,7 +1537,7 @@ int main() { printf("Hello, %s! I was built: %s\n", date); } - One solution is to use the &Requires; function + One solution is to use the &f-link-Requires; function to specify that the version.o must be rebuilt before it is used by the link step, but that changes to version.o @@ -1573,7 +1575,7 @@ int main() { printf("Hello, %s! I was built: %s\n", date); } we have to find some other way to get it into the link command line. For this example, we're cheating a bit and stuffing the object file name (extracted from version_obj - list returned by the &b-Object; call) + list returned by the &b-Object; builder call) into the &cv-link-LINKFLAGS; variable, because &cv-LINKFLAGS; is already included in the &cv-link-LINKCOM; command line. @@ -1611,8 +1613,8 @@ int main() { printf("Hello, %s! I was built: %s\n", date); } How &SCons; handles dependencies can also be affected - by the &AlwaysBuild; method. - When a file is passed to the &AlwaysBuild; method, + by the &f-link-AlwaysBuild; method. + When a file is passed to the &f-AlwaysBuild; method, like so: @@ -1643,7 +1645,7 @@ int main() { printf("Hello, %s!\n", string); } - The &AlwaysBuild; function has a somewhat misleading name, + The &f-AlwaysBuild; function has a somewhat misleading name, because it does not actually mean the target file will be rebuilt every single time &SCons; is invoked. Instead, it means that the target will, in fact, @@ -1652,7 +1654,7 @@ int main() { printf("Hello, %s!\n", string); } the command line (and their dependencies). So specifying some other target on the command line, a target that does not - itself depend on the &AlwaysBuild; target, + itself depend on the &f-AlwaysBuild; target, will still be rebuilt only if it's out-of-date with respect to its dependencies: -- cgit v0.12 From f21adf30aaa4412a3524b91dbbbb7681772e705e Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 9 Feb 2022 11:24:21 -0700 Subject: Fix typo Note -> Not [ci skip] Signed-off-by: Mats Wichmann --- doc/user/depends.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/depends.xml b/doc/user/depends.xml index f8959a3..d3f80aa 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -1207,7 +1207,7 @@ Program('hello', 'hello.c', CPPPATH='.') Apparently, the scanner does not know about the header dependency. - Note being a full-fledged C preprocessor, the scanner does not + Not being a full-fledged C preprocessor, the scanner does not expand the macro. -- cgit v0.12 From 610a3026779747c6838cd6638e238231e4e99b27 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 10 Feb 2022 07:35:30 -0700 Subject: Use entity for content signature [ci skip] Signed-off-by: Mats Wichmann --- RELEASE.txt | 4 ++-- doc/scons.mod | 5 +++-- doc/user/depends.xml | 14 +++++++------- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/RELEASE.txt b/RELEASE.txt index aeffddf..c507dad 100755 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -32,8 +32,6 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY POpen object is properly closed. - SCons help (-H) no longer prints the "ignored for compatibility" options, which are still listed in the manpage. -- Help is now sensitive to the size of the terminal window: the width of the - help text will scale to wider (or narrower) terminals than 80 characters. FIXES @@ -48,6 +46,8 @@ IMPROVEMENTS - Verify that a user specified msvc script (via MSVC_USE_SCRIPT) exists and raise an exception immediately when the user specified msvc script does not exist. - Add cache-debug messages for push failures. +- Command-line help is now sensitive to the size of the terminal window: the + width of the help text will scale for terminals other than 80 chars wide. PACKAGING --------- diff --git a/doc/scons.mod b/doc/scons.mod index 6a2fd6b..5579d4d 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -450,8 +450,9 @@ Nodes"> -signature"> -build signature"> +content signature"> +content signatures"> +build signature"> true"> false"> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index d3f80aa..62b6d91 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -110,7 +110,7 @@ int main() { printf("Hello, world!\n"); } so that the built software is up to date. By default, &SCons; keeps track of this through a - content signature, + &contentsig;, or hash, of the contents of each file, although you can easily configure &SCons; to use the @@ -169,7 +169,7 @@ int main() { printf("Hello, world!\n"); } Note that you can, if you wish, specify the default behavior of using - content signatures explicitly, + &contentsigs; explicitly, using the &f-link-Decider; function as follows: @@ -194,7 +194,7 @@ Decider('content') - Using content signatures to decide if an input file has changed + Using &contentsigs; to decide if an input file has changed has one surprising benefit: if a source file has been changed in such a way that the contents of the @@ -391,7 +391,7 @@ int main() { printf("Hello, world!\n"); } As a performance enhancement, &SCons; provides a way to use - a file's content signature, + a file's &contentsig;, but to read those contents only when the file's timestamp has changed. To do this, call the &f-link-Decider; @@ -552,7 +552,7 @@ int main() { printf("Hello, world!\n"); } The third argument, prev_ni, is an object that holds the - signature or timestamp information + &contentsig; and/or timestamp information that was recorded about the dependency the last time the target was built. A prev_ni object can hold @@ -572,7 +572,7 @@ int main() { printf("Hello, world!\n"); } - The content signature: + The &contentsig;: a cryptgraphic hash, or checksum, of the file contents of the dependency file the last time the ⌖ was built. @@ -705,7 +705,7 @@ env.Install("install", "test.txt") For example, if we arbitrarily want to build - one program using content signatures + one program using &contentsigs; and another using file modification times from the same source we might configure it this way: -- cgit v0.12 From 578b215c262b08d0887be534a09af5d14770b532 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 10 Feb 2022 09:32:50 -0700 Subject: Update RELEASE.txt with decider name change [ci skip] Signed-off-by: Mats Wichmann --- RELEASE.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/RELEASE.txt b/RELEASE.txt index c507dad..2aac813 100755 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -32,6 +32,9 @@ CHANGED/ENHANCED EXISTING FUNCTIONALITY POpen object is properly closed. - SCons help (-H) no longer prints the "ignored for compatibility" options, which are still listed in the manpage. +- The change to "content" and "content-timestamp" Decider names is reflected + in the User Guide as well, since the hash function may be other than md5 + (tidying up from earlier change) FIXES -- cgit v0.12 From a3c6d2ac68aa36e2b1c5976f6a949b92ed428aec Mon Sep 17 00:00:00 2001 From: Zhichang Yu Date: Fri, 18 Feb 2022 15:41:49 +0800 Subject: MSVC_SCRIPT_ARGS is the arguments (whitespace separated) passed to the script MSVC_USE_SCRIPT. --- CHANGES.txt | 3 +++ RELEASE.txt | 1 + SCons/Tool/MSCommon/vc.py | 5 +++-- SCons/Tool/msvc.xml | 9 +++++++++ 4 files changed, 16 insertions(+), 2 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 149de73..0411613 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -51,6 +51,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - runtest.py now accepts -j 0 to auto-detect number of usable processors for testing threads. + From Zhichang Yu: + - Define MSVC_SCRIPT_ARGS to pass arguments (whitespace separated) to MSVC_USE_SCRIPT. + RELEASE 4.3.0 - Tue, 16 Nov 2021 18:12:46 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index aeffddf..9b75d5d 100755 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -15,6 +15,7 @@ NEW FUNCTIONALITY ----------------- - List new features (presumably why a checkpoint is being released) +- Define MSVC_SCRIPT_ARGS to pass arguments (whitespace separated) to MSVC_USE_SCRIPT. DEPRECATED FUNCTIONALITY ------------------------ diff --git a/SCons/Tool/MSCommon/vc.py b/SCons/Tool/MSCommon/vc.py index 4f9f9c6..f3f9a07 100644 --- a/SCons/Tool/MSCommon/vc.py +++ b/SCons/Tool/MSCommon/vc.py @@ -942,8 +942,9 @@ def msvc_setup_env(env): use_script = use_script.strip() if not os.path.exists(use_script): raise MSVCScriptNotFound('Script specified by MSVC_USE_SCRIPT not found: "{}"'.format(use_script)) - debug('use_script 1 %s', repr(use_script)) - d = script_env(use_script) + args = env.get('MSVC_SCRIPT_ARGS', None) + debug('use_script 1 %s %s', repr(use_script), repr(args)) + d = script_env(use_script, args) elif use_script: d = msvc_find_valid_batch_script(env,version) debug('use_script 2 %s', d) diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml index 3c6af95..959363d 100644 --- a/SCons/Tool/msvc.xml +++ b/SCons/Tool/msvc.xml @@ -395,6 +395,7 @@ and extract the relevant variables from the result (typically %PATH%) for supplying to the build. This can be useful to force the use of a compiler version that &SCons; does not detect. +MSVC_SCRIPT_ARGS is the arguments (whitespace separated) passed to this script. @@ -412,6 +413,14 @@ you don't want &SCons; to change anything. + + + +This is the arguments (whitespace separated) passed to the script MSVC_USE_SCRIPT. + + + + - - - - - + + + + + @@ -105,13 +105,12 @@ See its __doc__ string for a discussion of the format. SHLINKCOM PROGSUFFIX PRINT_CMD_LINE_FUNC - + - + + + + @@ -119,31 +118,41 @@ See its __doc__ string for a discussion of the format. - &b-Ninja; is a special builder which - adds a target to create a ninja build file. + A special builder which + adds a target to create a Ninja build file. The builder does not require any source files to be specified. This is an experimental feature. To enable it you must use one of the following methods - + - # On the command line - --experimental=ninja +# On the command line +--experimental=ninja - # Or in your SConstruct - SetOption('experimental', 'ninja') +# Or in your SConstruct +SetOption('experimental', 'ninja') This functionality is subject to change and/or removal without deprecation cycle. - - To use this tool you must install pypi's ninja - package. - This can be done via - pip install ninja + To use this tool you need to install the &Python; &ninja; package, + as the tool by default depends on being able to do an + import of the package + (although see &cv-link-__NINJA_NO;). + The can be done via: + +# In a virtualenv, or "python" is the native executable: +python -m pip install ninja + +# Windows using Python launcher: +py -m pip install ninja + +# Anaconda: +conda install -c conda-forge ninja + @@ -184,10 +193,10 @@ See its __doc__ string for a discussion of the format. - The list of source file suffixes which are generated by SCons build steps. + The list of source file suffixes which are generated by &SCons; build steps. All source files which match these suffixes will be added to the _generated_sources alias in the output - ninja.build file. - Then all other source files will be made to depend on this in the ninja.build file, forcing the + &ninja; build file. + Then all other source files will be made to depend on this in the &ninja; build file, forcing the generated sources to be built first. @@ -196,9 +205,9 @@ See its __doc__ string for a discussion of the format. - This propagates directly into the generated ninja.build file. - From Ninja's docs - defines the string which should be stripped from msvc’s /showIncludes output + A string which propagates directly into the generated &ninja; build file. + From Ninja's docs: + defines the string which should be stripped from msvc’s output @@ -206,15 +215,13 @@ See its __doc__ string for a discussion of the format. - This propagates directly into the generated ninja.build file. + A directory name which propagates directly into the generated &ninja; build file. From Ninja's docs: -
- - builddir - A directory for some Ninja output files. ... (You can also store other build output in this - directory.) - -
+ builddir: + A directory for some Ninja output files. ... (You can also store other build output in this + directory.) + + The default value is .ninja. @@ -222,8 +229,8 @@ See its __doc__ string for a discussion of the format. - A generator function used to create a ninja depsfile which includes all the files which would require - SCons to be invoked if they change. + A generator function used to create a &ninja; depsfile which includes all the files which would require + &SCons; to be invoked if they change. Or a list of said files. @@ -232,13 +239,14 @@ See its __doc__ string for a discussion of the format. - Boolean value (True|False) to instruct ninja to expand the command line arguments normally put into + Boolean value to instruct &ninja; to expand the command line arguments normally put into response files. - This prevents lines in the compilation database like gcc @rsp_file and instead yields - gcc -c -o myfile.o myfile.c -Ia -DXYZ + If true, prevents unexpanded lines in the compilation database like + gcc @rsp_file and instead yields expanded lines like + gcc -c -o myfile.o myfile.c -Ia -DXYZ. - Ninja's compdb tool added the -x flag in Ninja V1.9.0 + Ninja's compdb tool added the flag in Ninja V1.9.0 @@ -247,12 +255,17 @@ See its __doc__ string for a discussion of the format. A string that sets the environment for any environment variables that - differ between the OS environment and the SCons command ENV. + differ between the OS environment and the &SCons; execution environment. + + It will be compatible with the default shell of the operating system. + - If not explicitly specified, SCons will generate this dynamically from the Environment()'s 'ENV' - env['ENV'] + + If not explicitly set, &SCons; will generate this dynamically from the + execution environment stored in the current &consenv; + (e.g. env['ENV']) where those values differ from the existing shell.. @@ -261,7 +274,7 @@ See its __doc__ string for a discussion of the format. - Set the ninja_pool for this or all targets in scope for this env var. + Set the ninja_pool for this or all targets in scope for this env var. @@ -269,11 +282,14 @@ See its __doc__ string for a discussion of the format. - Boolean (True|False). Default: False - When True, SCons will not run ninja automatically after creating the ninja.build file. + Boolean. Default: False. + If true, &SCons; will not run &ninja; automatically after creating the &ninja; build file. + - If not set, this will be set to True if --disable_execute_ninja or - SetOption('disable_execute_ninja', True) + + If not explicitly set, this will be set to True + if or + SetOption('disable_execute_ninja', True) is seen. @@ -281,7 +297,7 @@ See its __doc__ string for a discussion of the format. - Internal flag. Used to tell SCons whether or not to try to import pypi's ninja python package. + Internal flag. Used to tell &SCons; whether or not to try to import the &Python; &ninja; module. This is set to True when being called by Ninja? @@ -291,8 +307,8 @@ See its __doc__ string for a discussion of the format. - The filename for the generated Ninja build file defaults to - ninja.build + The filename for the generated Ninja build file. + The default is ninja.build. @@ -300,8 +316,9 @@ See its __doc__ string for a discussion of the format. - Name of the Alias() which is will cause SCons to create the ninja.build file, and - then (optionally) run ninja. + The name of the alias target which will cause &SCons; to create the &ninja; build file, + and then (optionally) run &ninja;. + The default value is generate-ninja. @@ -309,9 +326,9 @@ See its __doc__ string for a discussion of the format. - Theres also NINJA_SYNTAX which is the path to a custom ninja_syntax.py file which is used in generation. - The tool currently assumes you have ninja installed through pip, and grabs the syntax file from that - installation if none specified. + The path to a custom ninja_syntax.py file which is used in generation. + The tool currently assumes you have &ninja; installed as a &Python; module and grabs the syntax file from that + installation if &cv-NINJA_SYNTAX; is not explicitly set. @@ -319,9 +336,9 @@ See its __doc__ string for a discussion of the format. - When NINJA_FORCE_SCONS_BUILD is True, this will cause the build nodes to callback to scons instead of using - ninja to build them. This is intended to be passed to the environment on the builder invocation. - It is useful if you have a build node which does something which is not easily translated into ninja. + If true, causes the build nodes to callback to scons instead of using + &ninja; to build them. This is intended to be passed to the environment on the builder invocation. + It is useful if you have a build node which does something which is not easily translated into &ninja;. @@ -330,7 +347,7 @@ See its __doc__ string for a discussion of the format. Internal value used to specify the function to call with argument env to generate the list of files - which if changed would require the ninja file to be regenerated. + which if changed would require the &ninja; build file to be regenerated. diff --git a/doc/user/external.xml b/doc/user/external.xml index 5f88f5a..1d67edd 100644 --- a/doc/user/external.xml +++ b/doc/user/external.xml @@ -110,7 +110,7 @@ The entries in this file can be filtered by using COMPILATIONDB_PATH_FILTER='pattern' - where the filter pattern is a string following the Python + where the filter pattern is a string following the &Python; fnmatch @@ -306,54 +306,90 @@ - This is an experimental new feature. It is subject to change and/or removal without depreciation cycle - - - To use this tool you must install pypi's ninja - package. - This can be done via - pip install ninja + This is an experimental new feature. + It is subject to change and/or removal without a depreciation cycle. + - To enable this feature you'll need to use one of the following + To enable this feature you'll need to use one of the following: + - # On the command line - --experimental=ninja +# On the command line +--experimental=ninja - # Or in your SConstruct - SetOption('experimental', 'ninja') +# Or in your SConstruct +SetOption('experimental', 'ninja') - - This tool will enabled creating a ninja build file from your SCons based build system. It can then invoke - ninja to run your build. For most builds ninja will be significantly faster, but you may have to give up - some accuracy. You are NOT advised to use this for production builds. It can however significantly speed up - your build/debug/compile iterations. + Ninja is a small build system that tries to be fast + by not making decisions. &SCons; can at times be slow + because it makes lots of decisions to carry out its goal + of "correctness". The two tools can be paired to benefit + some build scenarios: by using the &t-link-ninja; tool, + &SCons; can generate the build file &ninja; uses (basically + doing the decision-making ahead of time and recording that + for &ninja;), and can invoke &ninja; to perform a build. + For situations where relationships are not changing, such + as edit/build/debug iterations, this works fine and should + provide considerable speedups for more complex builds. + The implication is if there are larger changes taking place, + &ninja; is not as appropriate - but you can always use &SCons; + to regenerate the build file. You are NOT advised to use + this for production builds. + + + + To use the &t-link-ninja; tool you'll need to first install the + &Python; &ninja; package, as the tool depends on being able to do an + import of the package. + This can be done via: + + +# In a virtualenv, or "python" is the native executable: +python -m pip install ninja + +# Windows using Python launcher: +py -m pip install ninja + +# Anaconda: +conda install -c conda-forge ninja + + - It's not expected that the ninja builder will work for all builds at this point. It's still under active - development. If you find that your build doesn't work with ninja please bring this to the users mailing list - or devel channel on our discord server. + Reminder that like any non-default tool, you need to initialize it before use + (e.g. env.Tool('ninja')). + - Specifically if your build has many (or even any) python function actions you may find that the ninja build - will be slower as it will run ninja, which will then run SCons for each target created by a python action. - To alleviate some of these, especially those python based actions built into SCons there is special logic to - implement those actions via shell commands in the ninja build file. + It is not expected that the &b-link-Ninja; builder will work for all builds at this point. It is still under active + development. If you find that your build doesn't work with &ninja; please bring this to the users mailing list + or devel channel on our Discord server. + + Specifically if your build has many (or even any) &Python; function actions you may find that the &ninja; build + will be slower as it will run &ninja;, which will then run SCons for each target created by a &Python; action. + To alleviate some of these, especially those &Python; based actions built into SCons there is special logic to + implement those actions via shell commands in the &ninja; build file. + + + See: + + + Ninja Build System - - - + + Ninja File Format Specification - + +
-- cgit v0.12 From 5741258b63df0acd080232fa0bb464b51e7e7282 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Thu, 24 Feb 2022 14:19:26 -0600 Subject: Added ninja mingw support and improved CommandGeneratorAction support --- CHANGES.txt | 1 + RELEASE.txt | 1 + SCons/Tool/ninja/Methods.py | 3 ++- SCons/Tool/ninja/__init__.py | 11 ++++++++--- SCons/Util.py | 2 +- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 149de73..7c3062c 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -29,6 +29,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER From Daniel Moody: - Add cache-debug messages for push failures. + - Added ninja mingw support and improved ninja CommandGeneratorAction support. From Mats Wichmann: - Tweak the way default site_scons paths on Windows are expressed to diff --git a/RELEASE.txt b/RELEASE.txt index aeffddf..b1784ea 100755 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -48,6 +48,7 @@ IMPROVEMENTS - Verify that a user specified msvc script (via MSVC_USE_SCRIPT) exists and raise an exception immediately when the user specified msvc script does not exist. - Add cache-debug messages for push failures. +- Added ninja mingw support and improved ninja CommandGeneratorAction support. PACKAGING --------- diff --git a/SCons/Tool/ninja/Methods.py b/SCons/Tool/ninja/Methods.py index 073cf71..35cf280 100644 --- a/SCons/Tool/ninja/Methods.py +++ b/SCons/Tool/ninja/Methods.py @@ -134,7 +134,7 @@ def get_command(env, node, action): # pylint: disable=too-many-branches variables = {} - comstr = get_comstr(sub_env, action, tlist, slist) + comstr = str(get_comstr(sub_env, action, tlist, slist)) if not comstr: return None @@ -255,6 +255,7 @@ def gen_get_response_file_command(env, rule, tool, tool_is_dynamic=False, custom ) cmd, rsp_content = cmd_list[:tool_idx], cmd_list[tool_idx:] + rsp_content = [rsp_content_item.replace('\\', '/') for rsp_content_item in rsp_content] rsp_content = ['"' + rsp_content_item + '"' for rsp_content_item in rsp_content] rsp_content = " ".join(rsp_content) diff --git a/SCons/Tool/ninja/__init__.py b/SCons/Tool/ninja/__init__.py index 44c2251..893990d 100644 --- a/SCons/Tool/ninja/__init__.py +++ b/SCons/Tool/ninja/__init__.py @@ -214,7 +214,7 @@ def generate(env): # This adds the required flags such that the generated compile # commands will create depfiles as appropriate in the Ninja file. - if env["PLATFORM"] == "win32": + if env["PLATFORM"] == "win32" and 'mingw' not in env['TOOLS']: env.Append(CCFLAGS=["/showIncludes"]) else: env.Append(CCFLAGS=["-MMD", "-MF", "${TARGET}.d"]) @@ -267,7 +267,12 @@ def generate(env): def robust_rule_mapping(var, rule, tool): provider = gen_get_response_file_command(env, rule, tool) env.NinjaRuleMapping("${" + var + "}", provider) - env.NinjaRuleMapping(env.get(var, None), provider) + + # some of these construction vars could be generators, e.g. + # CommandGeneratorAction, so if the var is not a string, we + # can't parse the generated string. + if isinstance(env.get(var), str): + env.NinjaRuleMapping(env.get(var, None), provider) robust_rule_mapping("CCCOM", "CC", "$CC") robust_rule_mapping("SHCCCOM", "CC", "$CC") @@ -423,7 +428,7 @@ def generate(env): return if target.check_attributes('ninja_file') is None: NINJA_STATE.add_build(target) - else: + else: target.build() SCons.Taskmaster.Task.execute = ninja_execute diff --git a/SCons/Util.py b/SCons/Util.py index 31202cc..17bb4f2 100644 --- a/SCons/Util.py +++ b/SCons/Util.py @@ -1213,7 +1213,7 @@ class CLVar(UserList): return super().__iadd__(CLVar(other)) def __str__(self): - return ' '.join(self.data) + return ' '.join([str(d) for d in self.data]) class Selector(OrderedDict): -- cgit v0.12 From 247af9aaee58822b9be66034d3bb9067b2cecda9 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 24 Feb 2022 17:28:32 -0700 Subject: Typo fix [ci skip] Signed-off-by: Mats Wichmann --- SCons/Tool/ninja/ninja.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Tool/ninja/ninja.xml b/SCons/Tool/ninja/ninja.xml index 3510a90..08139d7 100644 --- a/SCons/Tool/ninja/ninja.xml +++ b/SCons/Tool/ninja/ninja.xml @@ -142,7 +142,7 @@ SetOption('experimental', 'ninja') as the tool by default depends on being able to do an import of the package (although see &cv-link-__NINJA_NO;). - The can be done via: + This can be done via: # In a virtualenv, or "python" is the native executable: python -m pip install ninja -- cgit v0.12 From 2617860ac856dc081d511f75ef1711fb3375c50f Mon Sep 17 00:00:00 2001 From: William Deegan Date: Fri, 25 Feb 2022 18:10:47 -0800 Subject: Initial change to use CCDEFFLAGS set by individual compilers rather than hardcoding those flags for all compilers in the ninja tool itself --- SCons/Tool/cc.xml | 13 +++++++++++++ SCons/Tool/clang.py | 8 ++++++-- SCons/Tool/clang.xml | 25 ++++++++++++++++++++++++- SCons/Tool/gcc.py | 3 +++ SCons/Tool/gcc.xml | 1 + SCons/Tool/gxx.py | 3 +++ SCons/Tool/msvc.py | 3 +++ SCons/Tool/msvc.xml | 1 + SCons/Tool/ninja/__init__.py | 7 ++++--- SCons/Tool/ninja/ninja.xml | 1 + 10 files changed, 59 insertions(+), 6 deletions(-) diff --git a/SCons/Tool/cc.xml b/SCons/Tool/cc.xml index a7d6daa..7c8f944 100644 --- a/SCons/Tool/cc.xml +++ b/SCons/Tool/cc.xml @@ -48,6 +48,7 @@ Sets construction variables for generic POSIX C compilers. SHOBJSUFFIX CFILESUFFIX + CCDEPFLAGS PLATFORM @@ -215,4 +216,16 @@ See also &cv-link-CFLAGS; for compiling to static objects. + + + +Options to pass to C or C++ compiler to generate list of dependency files. + + + This is set only by compilers which support this functionality. (&t-link-gcc;, &t-link-clang;, and &t-link-msvc; currently) + + + + + diff --git a/SCons/Tool/clang.py b/SCons/Tool/clang.py index 6c9227c..8c2f728 100644 --- a/SCons/Tool/clang.py +++ b/SCons/Tool/clang.py @@ -43,6 +43,7 @@ from SCons.Tool.MSCommon import msvc_setup_env_once compilers = ['clang'] + def generate(env): """Add Builders and construction variables for clang to an Environment.""" SCons.Tool.cc.generate(env) @@ -58,7 +59,6 @@ def generate(env): # Set-up ms tools paths msvc_setup_env_once(env) - env['CC'] = env.Detect(compilers) or 'clang' if env['PLATFORM'] in ['cygwin', 'win32']: env['SHCCFLAGS'] = SCons.Util.CLVar('$CCFLAGS') @@ -67,7 +67,7 @@ def generate(env): # determine compiler version if env['CC']: - #pipe = SCons.Action._subproc(env, [env['CC'], '-dumpversion'], + # pipe = SCons.Action._subproc(env, [env['CC'], '-dumpversion'], pipe = SCons.Action._subproc(env, [env['CC'], '--version'], stdin='devnull', stderr='devnull', @@ -81,6 +81,10 @@ def generate(env): if match: env['CCVERSION'] = match.group(1) + env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + + + def exists(env): return env.Detect(compilers) diff --git a/SCons/Tool/clang.xml b/SCons/Tool/clang.xml index 2d989fa..8fdd3c1 100644 --- a/SCons/Tool/clang.xml +++ b/SCons/Tool/clang.xml @@ -1,6 +1,28 @@ diff --git a/SCons/Tool/ninja/__init__.py b/SCons/Tool/ninja/__init__.py index 893990d..cc69554 100644 --- a/SCons/Tool/ninja/__init__.py +++ b/SCons/Tool/ninja/__init__.py @@ -214,10 +214,11 @@ def generate(env): # This adds the required flags such that the generated compile # commands will create depfiles as appropriate in the Ninja file. - if env["PLATFORM"] == "win32" and 'mingw' not in env['TOOLS']: - env.Append(CCFLAGS=["/showIncludes"]) + if 'CCDEPFLAGS' not in env: + # Issue some warning here + pass else: - env.Append(CCFLAGS=["-MMD", "-MF", "${TARGET}.d"]) + env.Append(CCFLAGS='$CCDEPFLAGS') env.AddMethod(CheckNinjaCompdbExpand, "CheckNinjaCompdbExpand") diff --git a/SCons/Tool/ninja/ninja.xml b/SCons/Tool/ninja/ninja.xml index c5ee15b..f0ca4f8 100644 --- a/SCons/Tool/ninja/ninja.xml +++ b/SCons/Tool/ninja/ninja.xml @@ -90,6 +90,7 @@ See its __doc__ string for a discussion of the format. ARFLAGS CC CCCOM + CCDEPFLAGS CCFLAGS CXX CXXCOM -- cgit v0.12 From 5b855a33291742122709d6242f9017d1c43bbb08 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Sat, 26 Feb 2022 00:27:24 -0600 Subject: fix a few typos and add tests back --- SCons/Tool/clang.py | 2 +- SCons/Tool/clangxx.py | 3 +- SCons/Tool/gcc.py | 2 +- SCons/Tool/gxx.py | 2 +- test/ninja/mingw_command_generator_action.py | 89 ++++++++++++++++++++++ .../sconstruct_mingw_command_generator_action | 7 ++ 6 files changed, 101 insertions(+), 4 deletions(-) create mode 100644 test/ninja/mingw_command_generator_action.py create mode 100644 test/ninja/ninja_test_sconscripts/sconstruct_mingw_command_generator_action diff --git a/SCons/Tool/clang.py b/SCons/Tool/clang.py index 8c2f728..2a12a31 100644 --- a/SCons/Tool/clang.py +++ b/SCons/Tool/clang.py @@ -81,7 +81,7 @@ def generate(env): if match: env['CCVERSION'] = match.group(1) - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' diff --git a/SCons/Tool/clangxx.py b/SCons/Tool/clangxx.py index 4443b39..88ba6cc 100644 --- a/SCons/Tool/clangxx.py +++ b/SCons/Tool/clangxx.py @@ -51,7 +51,8 @@ def generate(env): SCons.Tool.cxx.generate(env) env['CXX'] = env.Detect(compilers) or 'clang++' - + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' + # platform specific settings if env['PLATFORM'] == 'aix': env['SHCXXFLAGS'] = SCons.Util.CLVar('$CXXFLAGS -mminimal-toc') diff --git a/SCons/Tool/gcc.py b/SCons/Tool/gcc.py index 0474d6a..94dfad3 100644 --- a/SCons/Tool/gcc.py +++ b/SCons/Tool/gcc.py @@ -57,7 +57,7 @@ def generate(env): if version: env['CCVERSION'] = version - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' diff --git a/SCons/Tool/gxx.py b/SCons/Tool/gxx.py index 77ed148..cc93f93 100644 --- a/SCons/Tool/gxx.py +++ b/SCons/Tool/gxx.py @@ -64,7 +64,7 @@ def generate(env): if version: env['CXXVERSION'] = version - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' diff --git a/test/ninja/mingw_command_generator_action.py b/test/ninja/mingw_command_generator_action.py new file mode 100644 index 0000000..58c5106 --- /dev/null +++ b/test/ninja/mingw_command_generator_action.py @@ -0,0 +1,89 @@ +#!/usr/bin/env python +# +# Copyright The SCons Foundation +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# 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 +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +# + +import os +import sys + +import TestSCons +from TestCmd import IS_WINDOWS +import SCons +from SCons.Platform.mingw import MINGW_DEFAULT_PATHS +from SCons.Platform.cygwin import CYGWIN_DEFAULT_PATHS + +test = TestSCons.TestSCons() + +if sys.platform not in ('cygwin', 'win32',): + test.skip_test("Skipping mingw test on non-Windows platform %s." % sys.platform) + +dp = MINGW_DEFAULT_PATHS + CYGWIN_DEFAULT_PATHS +gcc = SCons.Tool.find_program_path(test.Environment(), 'gcc', default_paths=dp) +if not gcc: + test.skip_test("Skipping mingw test, no MinGW found.\n") + +# ninja must have the os environment setup to work properly +os.environ["PATH"] += os.pathsep + os.path.dirname(gcc) + +try: + import ninja +except ImportError: + test.skip_test("Could not find module in python") + +_python_ = TestSCons._python_ +_exe = TestSCons._exe + +ninja_bin = os.path.abspath(os.path.join( + ninja.BIN_DIR, + 'ninja' + _exe)) + +test.dir_fixture('ninja-fixture') + +test.file_fixture('ninja_test_sconscripts/sconstruct_mingw_command_generator_action', 'SConstruct') + +# generate simple build +test.run(stdout=None) +test.must_contain_all_lines(test.stdout(), ['Generating: build.ninja']) +test.must_contain_all(test.stdout(), 'Executing:') +test.must_contain_all(test.stdout(), 'ninja%(_exe)s -f' % locals()) +test.run(program=test.workpath('test' + _exe), stdout="library_function") + +# clean build and ninja files +test.run(arguments='-c', stdout=None) + +# only generate the ninja file +test.run(arguments='--disable-execute-ninja', stdout=None) +test.must_contain_all_lines(test.stdout(), ['Generating: build.ninja']) +test.must_not_exist(test.workpath('test' + _exe)) + +# run ninja independently +program = test.workpath('run_ninja_env.bat') if IS_WINDOWS else ninja_bin +test.run(program=program, stdout=None) +test.run(program=test.workpath('test' + _exe), stdout="library_function") + +test.pass_test() + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/test/ninja/ninja_test_sconscripts/sconstruct_mingw_command_generator_action b/test/ninja/ninja_test_sconscripts/sconstruct_mingw_command_generator_action new file mode 100644 index 0000000..e3fcfe2 --- /dev/null +++ b/test/ninja/ninja_test_sconscripts/sconstruct_mingw_command_generator_action @@ -0,0 +1,7 @@ +SetOption('experimental','ninja') +DefaultEnvironment(tools=[]) + +env = Environment(tools=['mingw']) +env.Tool('ninja') +dll = env.SharedLibrary(target='test_impl', source='test_impl.c') +env.Program(target='test', source='test1.c', LIBS=[dll]) \ No newline at end of file -- cgit v0.12 From c9bd964430508256a246b3af00358e4fcd42f714 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Sat, 26 Feb 2022 00:53:38 -0600 Subject: Add mingw setup for windows --- .github/workflows/experimental_tests.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/experimental_tests.yml b/.github/workflows/experimental_tests.yml index aac28d0..3672144 100644 --- a/.github/workflows/experimental_tests.yml +++ b/.github/workflows/experimental_tests.yml @@ -30,6 +30,12 @@ jobs: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 + - name: Set up MinGW + uses: egor-tensin/setup-mingw@v2 + if: matrix.os == 'windows-latest' + with: + platform: x64 + - name: Set up Python 3.8 ${{ matrix.os }} uses: actions/setup-python@v2 with: -- cgit v0.12 From bcf17d9bd1d223472a67870a41bb10fe15b28814 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 26 Feb 2022 19:11:40 -0800 Subject: fix typo in gcc/clang CCDEFLAGS --- SCons/Tool/clang.py | 2 +- SCons/Tool/clangxx.py | 3 +++ SCons/Tool/gcc.py | 2 +- SCons/Tool/gxx.py | 2 +- 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/SCons/Tool/clang.py b/SCons/Tool/clang.py index 8c2f728..2a12a31 100644 --- a/SCons/Tool/clang.py +++ b/SCons/Tool/clang.py @@ -81,7 +81,7 @@ def generate(env): if match: env['CCVERSION'] = match.group(1) - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' diff --git a/SCons/Tool/clangxx.py b/SCons/Tool/clangxx.py index 4443b39..a78dc6c 100644 --- a/SCons/Tool/clangxx.py +++ b/SCons/Tool/clangxx.py @@ -89,6 +89,9 @@ def generate(env): if match: env['CXXVERSION'] = match.group(1) + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' + + def exists(env): return env.Detect(compilers) diff --git a/SCons/Tool/gcc.py b/SCons/Tool/gcc.py index 0474d6a..94dfad3 100644 --- a/SCons/Tool/gcc.py +++ b/SCons/Tool/gcc.py @@ -57,7 +57,7 @@ def generate(env): if version: env['CCVERSION'] = version - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' diff --git a/SCons/Tool/gxx.py b/SCons/Tool/gxx.py index 77ed148..cc93f93 100644 --- a/SCons/Tool/gxx.py +++ b/SCons/Tool/gxx.py @@ -64,7 +64,7 @@ def generate(env): if version: env['CXXVERSION'] = version - env['CCDEPFLAGS'] = '.MMD -MF ${TARGET}.d' + env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' -- cgit v0.12 From b27c096277ab49f046a5b934d1a938e9ed5e4325 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sun, 27 Feb 2022 20:48:18 -0800 Subject: fix duplicate CCDEPFLAGS def in clangxx tool --- SCons/Tool/clangxx.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/SCons/Tool/clangxx.py b/SCons/Tool/clangxx.py index 775e943..a78dc6c 100644 --- a/SCons/Tool/clangxx.py +++ b/SCons/Tool/clangxx.py @@ -51,8 +51,7 @@ def generate(env): SCons.Tool.cxx.generate(env) env['CXX'] = env.Detect(compilers) or 'clang++' - env['CCDEPFLAGS'] = '-MMD -MF ${TARGET}.d' - + # platform specific settings if env['PLATFORM'] == 'aix': env['SHCXXFLAGS'] = SCons.Util.CLVar('$CXXFLAGS -mminimal-toc') -- cgit v0.12 From 5353f82282315a347dd3a7ee212adbb82d42b7ba Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 28 Feb 2022 08:03:00 -0700 Subject: Ninja docs (#4105): address some review comments Signed-off-by: Mats Wichmann --- SCons/Tool/ninja/ninja.xml | 18 +++++++----------- doc/user/external.xml | 2 +- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/SCons/Tool/ninja/ninja.xml b/SCons/Tool/ninja/ninja.xml index 08139d7..f9a44ae 100644 --- a/SCons/Tool/ninja/ninja.xml +++ b/SCons/Tool/ninja/ninja.xml @@ -144,14 +144,7 @@ SetOption('experimental', 'ninja') (although see &cv-link-__NINJA_NO;). This can be done via: -# In a virtualenv, or "python" is the native executable: python -m pip install ninja - -# Windows using Python launcher: -py -m pip install ninja - -# Anaconda: -conda install -c conda-forge ninja @@ -205,7 +198,8 @@ conda install -c conda-forge ninja - A string which propagates directly into the generated &ninja; build file. + The msvc_deps_prefix string. + Propagates directly into the generated &ninja; build file. From Ninja's docs: defines the string which should be stripped from msvc’s output @@ -215,9 +209,10 @@ conda install -c conda-forge ninja - A directory name which propagates directly into the generated &ninja; build file. + The builddir value. + Propagates directly into the generated &ninja; build file. From Ninja's docs: - builddir: + A directory for some Ninja output files. ... (You can also store other build output in this directory.) @@ -229,7 +224,8 @@ conda install -c conda-forge ninja - A generator function used to create a &ninja; depsfile which includes all the files which would require + A generator function used to create a &ninja; depfile which + includes all the files which would require &SCons; to be invoked if they change. Or a list of said files. diff --git a/doc/user/external.xml b/doc/user/external.xml index 1d67edd..b483196 100644 --- a/doc/user/external.xml +++ b/doc/user/external.xml @@ -367,7 +367,7 @@ conda install -c conda-forge ninja It is not expected that the &b-link-Ninja; builder will work for all builds at this point. It is still under active development. If you find that your build doesn't work with &ninja; please bring this to the users mailing list - or devel channel on our Discord server. + or #scons-help channel on our Discord server. -- cgit v0.12 From 2e94a5bc02f4e2f873e881a7a95f4c6093025258 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Tue, 1 Mar 2022 20:27:06 -0800 Subject: hide __NINJA_NO for now --- SCons/Tool/ninja/ninja.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/SCons/Tool/ninja/ninja.xml b/SCons/Tool/ninja/ninja.xml index f9a44ae..4638efb 100644 --- a/SCons/Tool/ninja/ninja.xml +++ b/SCons/Tool/ninja/ninja.xml @@ -71,7 +71,7 @@ See its __doc__ string for a discussion of the format. NINJA_SYNTAX NINJA_FORCE_SCONS_BUILD _NINJA_REGENERATE_DEPS_FUNC - __NINJA_NO + IMPLICIT_COMMAND_DEPENDENCIES @@ -141,7 +141,7 @@ SetOption('experimental', 'ninja') To use this tool you need to install the &Python; &ninja; package, as the tool by default depends on being able to do an import of the package - (although see &cv-link-__NINJA_NO;). + This can be done via: python -m pip install ninja @@ -290,6 +290,7 @@ python -m pip install ninja + -- cgit v0.12 From 306b34fa44d175730f9fbc191c9a63aed313aeec Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 11 Feb 2022 12:34:23 -0700 Subject: Updates to User Guide: 22/Caching [skip appveyor] Use entities. Adopt the "derived-file cache" terminology used elsewhere instead of the former wording "shared cache". Also added entity references for content/build sigs to manpage, as well as some other entity fiddling. CacheDir entry now mentions SCons doesn't do cache maintenance. Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 20 ++++--- doc/man/scons.xml | 60 +++++++++---------- doc/user/caching.xml | 155 +++++++++++++++++++++++++++++--------------------- 3 files changed, 133 insertions(+), 102 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index f471866..d314711 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -107,8 +107,7 @@ to the commands executed to build target files, you must do so explicitly. A common example is -the system -PATH +the system &PATH; environment variable, so that &scons; @@ -547,7 +546,7 @@ and/or suffix, so the contents are treated as a list of strings, that is, adding a string will result in a separate string entry, not a combined string. For &cv-CPPDEFINES; as well as -for &cv-link-LIBS;, and the various *PATH +for &cv-link-LIBS;, and the various *PATH; variables, &SCons; will supply the compiler-specific syntax (e.g. adding a -D or /D prefix for &cv-CPPDEFINES;), so this syntax should be omitted when @@ -625,7 +624,7 @@ do not make sense and a &Python; exception will be raised. When using &f-env-Append; to modify &consvars; which are path specifications (conventionally, -the names of such end in PATH), +the names of such end in PATH), it is recommended to add the values as a list of strings, even if there is only a single string to add. The same goes for adding library names to &cv-LIBS;. @@ -812,7 +811,7 @@ is being used and &scons; finds a derived file that needs to be rebuilt, it will first look in the cache to see if a -file with matching build signature exists +file with matching &buildsig; exists (indicating the input file(s) and build action(s) were identical to those for the current target), and if so, will retrieve the file from the cache. @@ -824,7 +823,7 @@ If the derived file is not present in the cache, &scons; will build it and then place a copy of the built file in the cache, -identified by its build signature, for future use. +identified by its &buildsig;, for future use. @@ -881,6 +880,13 @@ method can be used to disable caching of specific files. This can be useful if inputs and/or outputs of some tool are impossible to predict or prohibitively large. + + +Note that (at this time) &SCons; provides no facilities +for managing the derived-file cache. It is up to the developer +to arrange for cache pruning, expiry, etc. if needed. + + @@ -1324,7 +1330,7 @@ was built. This can be consulted to match various file characteristics such as the timestamp, -size, or content signature. +size, or &contentsig;. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index fc2e24d..047f230 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1165,7 +1165,7 @@ the help message not to be displayed. -Set the block size used when computing content signatures to +Set the block size used when computing &contentsigs; to KILOBYTES. This value determines the size of the chunks which are read in at once when computing signature hashes. Files below that size are fully stored in memory @@ -1187,8 +1187,8 @@ be appropriate for most uses. Set the hashing algorithm used by SCons to ALGORITHM. -This value determines the hashing algorithm used in generating content -signatures or &f-link-CacheDir; keys. +This value determines the hashing algorithm used in generating +&contentsigs; or &CacheDir; keys. The supported list of values are: md5, sha1, and sha256. However, the Python interpreter used to run SCons must have the corresponding @@ -1272,8 +1272,7 @@ but with the following limitations: &scons; will not detect changes to implicit dependency search paths -(e.g. -CPPPATH, LIBPATH) +(e.g. &cv-link-CPPPATH;, &cv-link-LIBPATH;) that would ordinarily cause different versions of same-named files to be used. @@ -1281,8 +1280,7 @@ cause different versions of same-named files to be used. will miss changes in the implicit dependencies in cases where a new implicit dependency is added earlier in the implicit dependency search path -(e.g. -CPPPATH, LIBPATH) +(e.g. &cv-link-CPPPATH;, &cv-link-LIBPATH;) than a current implicit dependency with the same name. @@ -1551,16 +1549,16 @@ targets specified on the command line will still be processed. Set the maximum expected drift in the modification time of files to SECONDS. This value determines how long a file must be unmodified -before its cached content signature +before its cached &contentsig; will be used instead of -calculating a new content signature (hash) +calculating a new &contentsig; (hash) of the file's contents. The default value is 2 days, which means a file must have a modification time of at least two days ago in order to have its -cached content signature used. -A negative value means to never cache the content -signature and to ignore the cached value if there already is one. A value -of 0 means to always use the cached signature, +cached &contentsig; used. +A negative value means to never cache the +&contentsig; and to ignore the cached value if there already is one. +A value of 0 means to always use the cached signature, no matter how old the file is. @@ -2408,11 +2406,11 @@ env = Environment(parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to -the CPPPATH &consvar;, +the &cv-link-CPPPATH; &consvar;, 'EBUG' to -CPPDEFINES, +&cv-link-CPPDEFINES;, and 'm' to -LIBS. +&cv-link-LIBS;. @@ -2574,7 +2572,7 @@ or if tools includes 'default', then &scons; will auto-detect usable tools, using the execution environment value of PATH (that is, env['ENV']['PATH'] - -the external evironment PATH from os.environ +the external evironment &PATH; from os.environ is not used) for looking up any backing programs, and the platform name in effect to determine the default tools for that platform. @@ -2856,11 +2854,12 @@ env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm') This example adds 'include' to -CPPPATH, +the &cv-link-CPPPATH; &consvar;, 'EBUG' to -CPPDEFINES, +&cv-link-CPPDEFINES;, and 'm' to -LIBS. +&cv-link-LIBS;. + Although the builder methods defined by &scons; @@ -5546,9 +5545,9 @@ must accept four arguments: env is the &consenv; to use for context, and for_signature is a Boolean value that tells the function -if it is being called for the purpose of generating a build signature +if it is being called for the purpose of generating a &buildsig; (as opposed to actually executing the command). -Since the build signature is used for rebuild determination, +Since the &buildsig; is used for rebuild determination, the function should omit those elements that do not affect whether a rebuild should be triggered if for_signature is true. @@ -5974,6 +5973,7 @@ l = Action(build_it, '$STRINGIT') Any additional positional arguments, if present, may either be &consvars; or lists of &consvars; whose values will be included in the signature of the Action +(the &buildsig;) when deciding whether a target should be rebuilt because the action changed. Such variables may also be specified using the varlist @@ -6637,14 +6637,14 @@ may be used to surround parts of a command line that may change without causing a rebuild--that is, -which are not included in the signature +which are not included in the &buildsig; of target files built with this command. All text between $( and $) will be removed from the command line -before it is added to the build action signature, +before it is added to the &buildsig; and the $( and @@ -6662,7 +6662,9 @@ echo Last build occurred $( $TODAY $). > $TARGET echo Last build occurred $TODAY. > $TARGET -but the command signature added to any target files would be: +but the command portion of the +the &buildsig; computed for any target files built +by this action would be: echo Last build occurred . > $TARGET @@ -6682,8 +6684,8 @@ Such a function must accept four arguments: env is the &consenv; to use for context, and for_signature is a Boolean value that tells the function -if it is being called for the purpose of generating a build signature. -Since the build signature is used for rebuild determination, +if it is being called for the purpose of generating a &buildsig;. +Since the &buildsig; is used for rebuild determination, the function should omit variable elements that do not affect whether a rebuild should be triggered (see $( @@ -6921,7 +6923,7 @@ directories when generating the dependency Nodes. To illustrate this, a C language source file may contain a line like #include "foo.h". However, there is no guarantee that foo.h exists in the current directory: -the contents of &cv-CPPPATH; is passed to the C preprocessor which +the contents of &cv-link-CPPPATH; is passed to the C preprocessor which will look in those places for the header, so the scanner function needs to look in those places as well in order to build Nodes with correct paths. @@ -7201,7 +7203,7 @@ to vary its initialization. Returns True if the tool can be called in the context of env. Usually this means looking up one or more -known programs using the PATH from the +known programs using the PATH from the supplied env, but the tool can make the "exists" decision in any way it chooses. diff --git a/doc/user/caching.xml b/doc/user/caching.xml index c7b3842..69368d7 100644 --- a/doc/user/caching.xml +++ b/doc/user/caching.xml @@ -22,7 +22,9 @@ -action="> -batch_key="> -cmdstr="> -exitstatfunc="> -strfunction="> -varlist="> +action="> +batch_key="> +cmdstr="> +exitstatfunc="> +strfunction="> +varlist="> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index 5a8851d..a53e70e 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -2,7 +2,7 @@ %scons; - + %builders-mod; @@ -81,14 +81,14 @@ -bld = Builder(action = 'foobuild < $SOURCE > $TARGET') +bld = Builder(action='foobuild < $SOURCE > $TARGET') All the above line does is create a free-standing &Builder; object. - The next section will show us how to actually use it. + The next section will show how to actually use it. @@ -105,7 +105,7 @@ bld = Builder(action = 'foobuild < $SOURCE > $TARGET') for files to be built. This is done through the &cv-link-BUILDERS; &consvar; in an environment. - The &cv-BUILDERS; variable is a Python dictionary + The &cv-link-BUILDERS; variable is a &Python; dictionary that maps the names by which you want to call various &Builder; objects to the objects themselves. For example, if we want to call the @@ -221,7 +221,7 @@ hello.c To be able to use both our own defined &Builder; objects and the default &Builder; objects in the same &consenv;, - you can either add to the &cv-BUILDERS; variable + you can either add to the &cv-link-BUILDERS; variable using the &Append; function: @@ -296,8 +296,8 @@ env.Program('hello.c') suffixes to the target and/or the source file. For example, rather than having to specify explicitly that you want the Foo - &Builder; to build the file.foo - target file from the file.input source file, + &Builder; to build the file.foo + target file from the file.input source file, you can give the .foo and .input suffixes to the &Builder;, making for more compact and readable calls to @@ -361,7 +361,7 @@ env.Foo('file2') In &SCons;, you don't have to call an external command to build a file. - You can, instead, define a Python function + You can, instead, define a &Python; function that a &Builder; object can invoke to build your target file (or files). Such a &buildfunc; definition looks like: @@ -383,7 +383,7 @@ def build_function(target, source, env): - target + target @@ -392,14 +392,14 @@ def build_function(target, source, env): the target or targets to be built by this function. The file names of these target(s) - may be extracted using the Python &str; function. + may be extracted using the &Python; &str; function. - source + source @@ -408,21 +408,21 @@ def build_function(target, source, env): the sources to be used by this function to build the targets. The file names of these source(s) - may be extracted using the Python &str; function. + may be extracted using the &Python; &str; function. - env + env The &consenv; used for building the target(s). The function may use any of the - environment's construction variables + environment's &consvars; in any way to affect how it builds the targets. @@ -446,7 +446,7 @@ def build_function(target, source, env): - Once you've defined the Python function + Once you've defined the &Python; function that will build your target file, defining a &Builder; object for it is as simple as specifying the name of the function, @@ -479,7 +479,7 @@ file.input And notice that the output changes slightly, - reflecting the fact that a Python function, + reflecting the fact that a &Python; function, not an external command, is now called to build the target file: @@ -497,8 +497,8 @@ file.input &SCons; Builder objects can create an action "on the fly" - by using a function called a &generator;. - (Note: this is not the same thing as a Python generator function + by using a function called a &Generator;. + (Note: this is not the same thing as a &Python; generator function described in PEP 255) This provides a great deal of flexibility to construct just the right list of commands @@ -521,7 +521,7 @@ def generate_actions(source, target, env, for_signature): - source + source @@ -531,7 +531,7 @@ def generate_actions(source, target, env, for_signature): by the command or other action generated by this function. The file names of these source(s) - may be extracted using the Python &str; function. + may be extracted using the &Python; &str; function. @@ -539,7 +539,7 @@ def generate_actions(source, target, env, for_signature): - target + target @@ -549,7 +549,7 @@ def generate_actions(source, target, env, for_signature): by the command or other action generated by this function. The file names of these target(s) - may be extracted using the Python &str; function. + may be extracted using the &Python; &str; function. @@ -557,14 +557,14 @@ def generate_actions(source, target, env, for_signature): - env + env The &consenv; used for building the target(s). - The generator may use any of the - environment's construction variables + The &generator; may use any of the + environment's &consvars; in any way to determine what command or other action to return. @@ -574,13 +574,13 @@ def generate_actions(source, target, env, for_signature): - for_signature + for_signature A flag that specifies whether the - generator is being called to contribute to a build signature, + &generator; is being called to contribute to a &buildsig;, as opposed to actually executing the command. @@ -604,8 +604,8 @@ def generate_actions(source, target, env, for_signature): Once you've defined a &generator;, you create a &Builder; to use it - by specifying the generator keyword argument - instead of action. + by specifying the generator keyword argument + instead of action. @@ -652,9 +652,9 @@ env.Foo('file') Note that it's illegal to specify both an - action + action and a - generator + generator for a &Builder;. @@ -672,7 +672,7 @@ env.Foo('file') that takes as its arguments the list of the targets passed to the builder, the list of the sources passed to the builder, - and the construction environment. + and the &consenv;. The emitter function should return the modified lists of targets that should be built and sources from which the targets will be built. @@ -739,7 +739,7 @@ env.Foo('file') - + And would yield the following output: @@ -751,16 +751,15 @@ env.Foo('file') One very flexible thing that you can do is - use a construction variable to specify - different emitter functions for different - construction variable. + use a &consvar; to specify + different emitter functions for different &consenvs;. To do this, specify a string - containing a construction variable + containing a &consvar; expansion as the emitter when you call the &f-link-Builder; function, - and set that construction variable to + and set that &consvar; to the desired emitter function - in different construction environments: + in different &consenvs;: @@ -827,9 +826,9 @@ cat is a powerful concept, but sometimes all you really want is to be able to use an existing builder but change its concept of what targets are created. - In this case, + In this case, trying to recreate the logic of an existing Builder to - supply a special emitter can be a lot of work. + supply a special emitter can be a lot of work. The typical case for this is when you want to use a compiler flag that causes additional files to be generated. For example the GNU linker accepts an option @@ -844,12 +843,12 @@ cat To help with this, &SCons; provides &consvars; which correspond - to a few standard builders: - &cv-link-PROGEMITTER; for &b-link-Program;; - &cv-link-LIBEMITTER; for &b-link-Library;; - &cv-link-SHLIBEMITTER; for &b-link-SharedLibrary; and + to a few standard builders: + &cv-link-PROGEMITTER; for &b-link-Program;; + &cv-link-LIBEMITTER; for &b-link-Library;; + &cv-link-SHLIBEMITTER; for &b-link-SharedLibrary; and &cv-link-LDMODULEEMITTER; for &b-link-LoadableModule;;. - Adding an emitter to one of these will cause it to be + Adding an emitter to one of these will cause it to be invoked in addition to any existing emitter for the corresponding builder. @@ -944,10 +943,10 @@ main() The site_scons directories give you a place to - put Python modules and packages that you can import into your &SConscript; files - (site_scons), + put &Python; modules and packages that you can import into your + &SConscript; files (at the top level) add-on tools that can integrate into &SCons; - (site_scons/site_tools), + (in a site_tools subdirectory), and a site_scons/site_init.py file that gets read before any &SConstruct; or &SConscript; file, allowing you to change &SCons;'s default behavior. @@ -957,8 +956,10 @@ main() Each system type (Windows, Mac, Linux, etc.) searches a canonical - set of directories for site_scons; see the man page for details. - The top-level SConstruct's site_scons dir is always searched last, + set of directories for site_scons; + see the man page for details. + The top-level SConstruct's site_scons dir + (that is, the one in the project) is always searched last, and its dir is placed first in the tool path so it overrides all others. @@ -969,8 +970,8 @@ main() If you get a tool from somewhere (the &SCons; wiki or a third party, for instance) and you'd like to use it in your project, a site_scons dir is the simplest place to put it. - Tools come in two flavors; either a Python function that operates on - an &Environment; or a Python module or package containing two functions, + Tools come in two flavors; either a &Python; function that operates on + an &Environment; or a &Python; module or package containing two functions, exists() and generate(). @@ -1023,7 +1024,7 @@ env.AddHeader('tgt', 'src') -