From 52773da0faddc808056ffec34ed0112e2b42b5f7 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Fri, 15 May 2020 23:31:41 -0400 Subject: use signature to check function signature instead of relying on TypeErrors --- SCons/Subst.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/SCons/Subst.py b/SCons/Subst.py index a1ef053..29698d5 100644 --- a/SCons/Subst.py +++ b/SCons/Subst.py @@ -30,7 +30,7 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" import collections import re - +from inspect import signature import SCons.Errors from SCons.Util import is_String, is_Sequence @@ -420,12 +420,13 @@ class StringSubber(object): return conv(substitute(l, lvars)) return list(map(func, s)) elif callable(s): - try: + if (s and + set(signature(s).parameters.keys()) == set(['target', 'source', 'env', 'for_signature'])): s = s(target=lvars['TARGETS'], source=lvars['SOURCES'], env=self.env, for_signature=(self.mode != SUBST_CMD)) - except TypeError: + else: # This probably indicates that it's a callable # object that doesn't match our calling arguments # (like an Action). -- cgit v0.12 From cffd40b44080dcce1d238d037e026051eaa7a60b Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Sun, 17 May 2020 15:41:12 -0400 Subject: cover other type of subber and add test --- SCons/Subst.py | 5 +++-- test/Subst/TypeError.py | 28 ++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/SCons/Subst.py b/SCons/Subst.py index 29698d5..fbb89b3 100644 --- a/SCons/Subst.py +++ b/SCons/Subst.py @@ -591,12 +591,13 @@ class ListSubber(collections.UserList): self.substitute(a, lvars, 1) self.next_word() elif callable(s): - try: + if (s and + set(signature(s).parameters.keys()) == set(['target', 'source', 'env', 'for_signature'])): s = s(target=lvars['TARGETS'], source=lvars['SOURCES'], env=self.env, for_signature=(self.mode != SUBST_CMD)) - except TypeError: + else: # This probably indicates that it's a callable # object that doesn't match our calling arguments # (like an Action). diff --git a/test/Subst/TypeError.py b/test/Subst/TypeError.py index 628db2f..b288961 100644 --- a/test/Subst/TypeError.py +++ b/test/Subst/TypeError.py @@ -85,8 +85,36 @@ expect = expect_build % (r' \[foo\.bar\]', r'\$\{func\(1\)\}') test.run(status=2, stderr=expect) +# callable exceptions: +test.write('foo.c', """\ +#include +#include +int +main(int argc, char *argv[]) +{ + argv[argc++] = "--"; + printf("foo.c"); + exit (0); +} +""") + +test.write('SConstruct', """\ +class TestCallable(object): + def __init__(self, thing, makePathsRelative = True, debug = False): + pass + def __call__(self, target, source, env, for_signature): + raise TypeError("User callable exception") + +env = Environment() +env["TESTCLASS"] = TestCallable +env["CCCOM"] = "$CC $_CCCOMCOM $CCFLAGS -o ${TESTCLASS('$TARGET')} -c ${TESTCLASS('$SOURCES')}" + +env.Program(target='foo', source='foo.c') +""") +test.run(status=2, stderr=r'.*TypeError\s:\sUser\scallable\sexception.*') +print(test.stdout()) test.pass_test() # Local Variables: -- cgit v0.12 From 2a9eb7778a553d44bb2103953b4d563c9dab59d7 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Sun, 17 May 2020 23:17:43 -0400 Subject: update CHANGES.txt --- CHANGES.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 431ecc1..e22dafd 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -10,12 +10,6 @@ NOTE: Please include a reference to any Issues resolved by your changes in the b RELEASE VERSION/DATE TO BE FILLED IN LATER - From Daniel Moody: - - Add no_progress (-Q) option as a set-able option. However, setting it in the - SConstruct/SConscript will still cause "scons: Reading SConscript files ..." to be - printed, since the option is not set when the build scripts first get read. - - Added check for SONAME in environment to setup symlinks correctly (Github Issue #3246) - From James Benton: - Improve Visual Studio solution/project generation code to add support for a per-variant cppflags. Intellisense can be affected by cppflags, @@ -86,6 +80,16 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER macro which is not located in a state TABLE. * Cleanup CPP expressions before evaluating (strip comments, carriage returns) + From Daniel Moody: + - Add no_progress (-Q) option as a set-able option. However, setting it in the + SConstruct/SConscript will still cause "scons: Reading SConscript files ..." to be + printed, since the option is not set when the build scripts first get read. + - Added check for SONAME in environment to setup symlinks correctly (Github Issue #3246) + - User callable's called during substition expansion could possibly throw a TypeError + exception, however SCons was using TypeError to detect if the callable had a different + signature than expected, and would silently fail to report user's exceptions. Fixed to + use signature module to detect function signature instead of TypeError. (Github Issue #3654) + From Andrew Morrow: - Fix Issue #3469 - Fixed improper reuse of temporary and compiled files by Configure when changing the order and/or number of tests. This is done by using the hash of the generated temporary files -- cgit v0.12 From 23a99693e3603a47f4bcb7b08351a774923b0f2e Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Mon, 18 May 2020 17:24:40 -0400 Subject: add check for SCons null class --- SCons/Subst.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/SCons/Subst.py b/SCons/Subst.py index fbb89b3..cc2eeab 100644 --- a/SCons/Subst.py +++ b/SCons/Subst.py @@ -420,7 +420,10 @@ class StringSubber(object): return conv(substitute(l, lvars)) return list(map(func, s)) elif callable(s): - if (s and + # SCons has the unusual Null class where any __getattr__ call returns it's self, + # which does not work the signature module, and the Null class returns an empty + # string if called on, so we make an exception in this condition for Null class + if (isinstance(s, SCons.Util.Null) or set(signature(s).parameters.keys()) == set(['target', 'source', 'env', 'for_signature'])): s = s(target=lvars['TARGETS'], source=lvars['SOURCES'], @@ -591,7 +594,10 @@ class ListSubber(collections.UserList): self.substitute(a, lvars, 1) self.next_word() elif callable(s): - if (s and + # SCons has the unusual Null class where any __getattr__ call returns it's self, + # which does not work the signature module, and the Null class returns an empty + # string if called on, so we make an exception in this condition for Null class + if (isinstance(s, SCons.Util.Null) or set(signature(s).parameters.keys()) == set(['target', 'source', 'env', 'for_signature'])): s = s(target=lvars['TARGETS'], source=lvars['SOURCES'], -- cgit v0.12 From deacd0898818a0358fc29e0edff387acda5b7bc5 Mon Sep 17 00:00:00 2001 From: Daniel Moody Date: Tue, 19 May 2020 17:14:41 -0400 Subject: used fixtures in test TypeError test --- test/Subst/TypeError.py | 32 +++--------------------- test/Subst/fixture/SConstruct.callable_exception | 11 ++++++++ 2 files changed, 15 insertions(+), 28 deletions(-) create mode 100644 test/Subst/fixture/SConstruct.callable_exception diff --git a/test/Subst/TypeError.py b/test/Subst/TypeError.py index b288961..c52434f 100644 --- a/test/Subst/TypeError.py +++ b/test/Subst/TypeError.py @@ -85,36 +85,12 @@ expect = expect_build % (r' \[foo\.bar\]', r'\$\{func\(1\)\}') test.run(status=2, stderr=expect) -# callable exceptions: -test.write('foo.c', """\ -#include -#include -int -main(int argc, char *argv[]) -{ - argv[argc++] = "--"; - printf("foo.c"); - exit (0); -} -""") - -test.write('SConstruct', """\ - -class TestCallable(object): - def __init__(self, thing, makePathsRelative = True, debug = False): - pass - def __call__(self, target, source, env, for_signature): - raise TypeError("User callable exception") - -env = Environment() -env["TESTCLASS"] = TestCallable -env["CCCOM"] = "$CC $_CCCOMCOM $CCFLAGS -o ${TESTCLASS('$TARGET')} -c ${TESTCLASS('$SOURCES')}" - -env.Program(target='foo', source='foo.c') -""") +# user callable exceptions (Github issue #3654): +test.file_fixture('test_main.c') +test.file_fixture('./fixture/SConstruct.callable_exception', 'SConstruct') test.run(status=2, stderr=r'.*TypeError\s:\sUser\scallable\sexception.*') -print(test.stdout()) + test.pass_test() # Local Variables: diff --git a/test/Subst/fixture/SConstruct.callable_exception b/test/Subst/fixture/SConstruct.callable_exception new file mode 100644 index 0000000..3f1b337 --- /dev/null +++ b/test/Subst/fixture/SConstruct.callable_exception @@ -0,0 +1,11 @@ +class TestCallable(object): + def __init__(self, thing, makePathsRelative = True, debug = False): + pass + def __call__(self, target, source, env, for_signature): + raise TypeError("User callable exception") + +env = Environment() +env["TESTCLASS"] = TestCallable +env["CCCOM"] = "$CC $_CCCOMCOM $CCFLAGS -o ${TESTCLASS('$TARGET')} -c ${TESTCLASS('$SOURCES')}" + +env.Program(target='test_main', source='test_main.c') \ No newline at end of file -- cgit v0.12 From df7422a008be9236cf7ded05d99704a6b7ce7459 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 23 May 2020 12:07:39 -0600 Subject: Set Tasks class as abstract needs_execut method set as an abstract method, meaning you can't instantiate Task itself, and derived classes must implement the methid. The former warning framework for this (deprecated) is disabled, and some unit tests that were not implementing needs_execute were fixed - by deriving from the AlwaysTask class. Signed-off-by: Mats Wichmann --- CHANGES.txt | 3 ++ SCons/Taskmaster.py | 23 ++++--------- SCons/TaskmasterTests.py | 9 ++--- test/Deprecated/TaskmasterNeedsExecute.py | 53 ------------------------------ test/Removed/BuildDir/README.md | 2 +- test/Removed/CacheDir/README.md | 2 +- test/Removed/Copy-Method/README.md | 2 +- test/Removed/Old/TaskmasterNeedsExecute.py | 53 ++++++++++++++++++++++++++++++ test/Removed/Old/sconstest.skip | 0 test/Removed/README.md | 13 ++++++++ test/Removed/SourceCode/README.md | 2 +- test/Removed/SourceSignatures/README.md | 2 +- test/Removed/TargetSignatures/README.md | 2 +- 13 files changed, 87 insertions(+), 79 deletions(-) delete mode 100644 test/Deprecated/TaskmasterNeedsExecute.py create mode 100644 test/Removed/Old/TaskmasterNeedsExecute.py create mode 100644 test/Removed/Old/sconstest.skip create mode 100644 test/Removed/README.md diff --git a/CHANGES.txt b/CHANGES.txt index ecf3255..f2f3179 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -150,6 +150,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - ParseFlags should not modify the user's passed in dict in case it's a compound data structure (e.g. values are lists) (issue #3665) - In Py3 classes no longer need to be listed as deriving from object. + - Remove deprecated check for Task subclasses needing a needs_execute + method - this is now enforced via an abstract base class, so the + check and test is no longer needed. diff --git a/SCons/Taskmaster.py b/SCons/Taskmaster.py index 147cbcd..bfb7dc1 100644 --- a/SCons/Taskmaster.py +++ b/SCons/Taskmaster.py @@ -54,10 +54,11 @@ __doc__ = """ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" -from itertools import chain import operator import sys import traceback +from abc import ABC, abstractmethod +from itertools import chain import SCons.Errors import SCons.Node @@ -115,10 +116,8 @@ def dump_stats(): print((fmt % n.attributes.stats.__dict__) + str(n)) - -class Task: - """ - Default SCons build engine task. +class Task(ABC): + """ SCons build engine abstract task class. This controls the interaction of the actual building of node and the rest of the engine. @@ -210,17 +209,9 @@ class Task: """ return self.node + @abstractmethod def needs_execute(self): - # TODO(deprecate): "return True" is the old default behavior; - # change it to NotImplementedError (after running through the - # Deprecation Cycle) so the desired behavior is explicitly - # determined by which concrete subclass is used. - #raise NotImplementedError - msg = ('Taskmaster.Task is an abstract base class; instead of\n' - '\tusing it directly, ' - 'derive from it and override the abstract methods.') - SCons.Warnings.warn(SCons.Warnings.TaskmasterNeedsExecuteWarning, msg) - return True + return def execute(self): """ @@ -577,7 +568,7 @@ class AlwaysTask(Task): dependencies) can use this as follows: class MyTaskSubclass(SCons.Taskmaster.Task): - needs_execute = SCons.Taskmaster.Task.execute_always + needs_execute = SCons.Taskmaster.AlwaysTask.needs_execute """ return True diff --git a/SCons/TaskmasterTests.py b/SCons/TaskmasterTests.py index 961910a..43a5047 100644 --- a/SCons/TaskmasterTests.py +++ b/SCons/TaskmasterTests.py @@ -291,7 +291,7 @@ class TaskmasterTestCase(unittest.TestCase): built_text = "up to date: " top_node = n3 - class MyTask(SCons.Taskmaster.Task): + class MyTask(SCons.Taskmaster.AlwaysTask): def execute(self): global built_text if self.targets[0].get_state() == SCons.Node.up_to_date: @@ -542,10 +542,11 @@ class TaskmasterTestCase(unittest.TestCase): """ ood = [] def TaskGen(tm, targets, top, node, ood=ood): - class MyTask(SCons.Taskmaster.Task): + class MyTask(SCons.Taskmaster.AlwaysTask): def make_ready(self): SCons.Taskmaster.Task.make_ready(self) self.ood.extend(self.out_of_date) + t = MyTask(tm, targets, top, node) t.ood = ood return t @@ -585,7 +586,7 @@ class TaskmasterTestCase(unittest.TestCase): def test_make_ready_exception(self): """Test handling exceptions from Task.make_ready() """ - class MyTask(SCons.Taskmaster.Task): + class MyTask(SCons.Taskmaster.AlwaysTask): def make_ready(self): raise MyException("from make_ready()") @@ -599,7 +600,7 @@ class TaskmasterTestCase(unittest.TestCase): def test_make_ready_all(self): """Test the make_ready_all() method""" - class MyTask(SCons.Taskmaster.Task): + class MyTask(SCons.Taskmaster.AlwaysTask): make_ready = SCons.Taskmaster.Task.make_ready_all n1 = Node("n1") diff --git a/test/Deprecated/TaskmasterNeedsExecute.py b/test/Deprecated/TaskmasterNeedsExecute.py deleted file mode 100644 index 9f7ade1..0000000 --- a/test/Deprecated/TaskmasterNeedsExecute.py +++ /dev/null @@ -1,53 +0,0 @@ -#!/usr/bin/env python -# -# __COPYRIGHT__ -# -# 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. -# - -__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" - -""" -Verify the message about the deprecated Taskmaster.needs_task() -method, and the ability to suppress it. -""" - -import TestSCons - -test = TestSCons.TestSCons(match = TestSCons.match_re_dotall) - -test.write('SConscript', """ -import SCons.Taskmaster -tm = SCons.Taskmaster.Taskmaster() -task = SCons.Taskmaster.Task(tm, [], True, None) -task.needs_execute() -""") - -msg ="""Taskmaster.Task is an abstract base class; instead of -\tusing it directly, derive from it and override the abstract methods.""" -test.deprecated_warning('taskmaster-needs-execute', msg) - -test.pass_test() - -# Local Variables: -# tab-width:4 -# indent-tabs-mode:nil -# End: -# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/test/Removed/BuildDir/README.md b/test/Removed/BuildDir/README.md index c4fd879..131e67b 100644 --- a/test/Removed/BuildDir/README.md +++ b/test/Removed/BuildDir/README.md @@ -1,6 +1,6 @@ BuildDir/Old contains old tests which used the now removed BuildDir function, env.BuildDir method, and build_dir argument to SConscript, -preserved here for reference; the presence of an scontest.skip file +preserved here for reference; the presence of an sconstest.skip file means they are never executed. The "new" tests verify failure using these symbols. diff --git a/test/Removed/CacheDir/README.md b/test/Removed/CacheDir/README.md index c5b75bf..46fcbc0 100644 --- a/test/Removed/CacheDir/README.md +++ b/test/Removed/CacheDir/README.md @@ -1,4 +1,4 @@ CacheDir/Old contains old tests of CacheDir which used the now removed SourceSignatures and TargetSignatures methods, preserved here for -reference; the presence of an scontest.skip file means they are never +reference; the presence of an sconstest.skip file means they are never executed. diff --git a/test/Removed/Copy-Method/README.md b/test/Removed/Copy-Method/README.md index 609c6e4..6352522 100644 --- a/test/Removed/Copy-Method/README.md +++ b/test/Removed/Copy-Method/README.md @@ -2,5 +2,5 @@ Copy-Method.py is the "new" test for env.Copy, making sure we get an AttributeError. The Old directory is the former tests from the deprecated state, -preserved here for reference; the presence of an scontest.skip file +preserved here for reference; the presence of an sconstest.skip file means they are never executed. diff --git a/test/Removed/Old/TaskmasterNeedsExecute.py b/test/Removed/Old/TaskmasterNeedsExecute.py new file mode 100644 index 0000000..9f7ade1 --- /dev/null +++ b/test/Removed/Old/TaskmasterNeedsExecute.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python +# +# __COPYRIGHT__ +# +# 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. +# + +__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" + +""" +Verify the message about the deprecated Taskmaster.needs_task() +method, and the ability to suppress it. +""" + +import TestSCons + +test = TestSCons.TestSCons(match = TestSCons.match_re_dotall) + +test.write('SConscript', """ +import SCons.Taskmaster +tm = SCons.Taskmaster.Taskmaster() +task = SCons.Taskmaster.Task(tm, [], True, None) +task.needs_execute() +""") + +msg ="""Taskmaster.Task is an abstract base class; instead of +\tusing it directly, derive from it and override the abstract methods.""" +test.deprecated_warning('taskmaster-needs-execute', msg) + +test.pass_test() + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/test/Removed/Old/sconstest.skip b/test/Removed/Old/sconstest.skip new file mode 100644 index 0000000..e69de29 diff --git a/test/Removed/README.md b/test/Removed/README.md new file mode 100644 index 0000000..be3f9b9 --- /dev/null +++ b/test/Removed/README.md @@ -0,0 +1,13 @@ +This tree contains tests for formerly deprecated behaviors +that have since been removed. + +If there is a runnable test (i.e. a test that verifies a +particular old behavior actually fails if called), it is +here or in a subdirectory and is left selectable by the +test framework. + +If there is a test that cannot be run, it will be in a +subdirectory named Old, which will contain a sconstest.skip +file, ensuring those test files are never loaded by the +test framework. + diff --git a/test/Removed/SourceCode/README.md b/test/Removed/SourceCode/README.md index c584dc9..61feaad 100644 --- a/test/Removed/SourceCode/README.md +++ b/test/Removed/SourceCode/README.md @@ -2,5 +2,5 @@ SourceCode.py is the "new" test for SourceCode making sure we get a NameError. The Old directory is the former tests from the deprecated state, -preserved here for reference; the presence of an scontest.skip file +preserved here for reference; the presence of an sconstest.skip file means they are never executed. diff --git a/test/Removed/SourceSignatures/README.md b/test/Removed/SourceSignatures/README.md index 05d8d05..4714a68 100644 --- a/test/Removed/SourceSignatures/README.md +++ b/test/Removed/SourceSignatures/README.md @@ -2,5 +2,5 @@ SourceSignatures.py is the "new" test, only makes sure scons actually fails in the presence of the method or setoption call. The Old directory is the former tests from the deprecated state, -preserved here for reference; the presence of an scontest.skip file +preserved here for reference; the presence of an sconstest.skip file means they are never executed. diff --git a/test/Removed/TargetSignatures/README.md b/test/Removed/TargetSignatures/README.md index 00a8b6b..db00b8c 100644 --- a/test/Removed/TargetSignatures/README.md +++ b/test/Removed/TargetSignatures/README.md @@ -2,5 +2,5 @@ TargetSignatures.py is the "new" test, only makes sure scons actually fails in the presence of the method or setoption call. The Old directory is the former tests from the deprecated state, -preserved here for reference; the presence of an scontest.skip file +preserved here for reference; the presence of an sconstest.skip file means they are never executed. -- cgit v0.12 From 9623c19fb4c51d6dd9c15ac270f44fd3298f4be5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 27 May 2020 06:45:25 -0600 Subject: [PR #3669] add unit test for abstract Task Make sure a subclass of Task really does fail when instantiated if it does not implement needs_execute(). Signed-off-by: Mats Wichmann --- SCons/TaskmasterTests.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/SCons/TaskmasterTests.py b/SCons/TaskmasterTests.py index 43a5047..ea673a5 100644 --- a/SCons/TaskmasterTests.py +++ b/SCons/TaskmasterTests.py @@ -597,6 +597,19 @@ class TaskmasterTestCase(unittest.TestCase): assert exc_type == MyException, repr(exc_type) assert str(exc_value) == "from make_ready()", exc_value + def test_needs_execute(self): + """Test that we can't instantiate a Task subclass without needs_execute + + We should be getting: + TypeError: Can't instantiate abstract class MyTask with abstract methods needs_execute + """ + class MyTask(SCons.Taskmaster.Task): + pass + + n1 = Node("n1") + tm = SCons.Taskmaster.Taskmaster(targets=[n1], tasker=MyTask) + with self.assertRaises(TypeError): + t = tm.next_task() def test_make_ready_all(self): """Test the make_ready_all() method""" -- cgit v0.12 From 8662a4efdf65dd5be31315c23338dc13d898498b Mon Sep 17 00:00:00 2001 From: "Andrii Doroshenko (Xrayez)" Date: Wed, 27 May 2020 19:43:13 +0300 Subject: Extend `Environment.Dump()` to select serialization format Environment.Dump() produces pretty-printable results only, so the usefulness of this method is limited to debugging purposes. The existing method is extended to allow selecting a serialization format to use via a `format` parameter. Namely, it's now possible to serialize variables as a JSON-formatted string, which makes it possible for automated external tools to inspect the environment more easily. --- CHANGES.txt | 3 +++ SCons/Environment.py | 36 ++++++++++++++++++++++++++---------- SCons/Environment.xml | 27 +++++++++++++++++++++++++-- SCons/EnvironmentTests.py | 12 ++++++++++++ 4 files changed, 66 insertions(+), 12 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index ecf3255..4774881 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -54,6 +54,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Reorganized source tree. Moved src/engine/SCons to SCons to be more in line with current Python source tree organization practices. + From Andrii Doroshenko: + - Extended `Environment.Dump()` to select a format to serialize construction variables (pretty, json). + From Jeremy Elson: - Updated design doc to use the correct syntax for Depends() diff --git a/SCons/Environment.py b/SCons/Environment.py index 0b4be1b..cd52ee5 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1517,26 +1517,42 @@ class Base(SubstitutionEnvironment): return dlist - def Dump(self, key=None): - """ Return pretty-printed string of construction variables. + def Dump(self, key=None, format='pretty'): + """ Serialize the construction variables to a string. :param key: if None, format the whole dict of variables. Else look up and format just the value for key. + + :param format: specify the format of the variables to be serialized: + - pretty: pretty-printed string. + - json: JSON-formatted string. """ - import pprint - pp = pprint.PrettyPrinter(indent=2) if key: cvars = self.Dictionary(key) else: cvars = self.Dictionary() - # TODO: pprint doesn't do a nice job on path-style values - # if the paths contain spaces (i.e. Windows), because the - # algorithm tries to break lines on spaces, while breaking - # on the path-separator would be more "natural". Is there - # a better way to format those? - return pp.pformat(cvars) + fmt = format.lower() + + if fmt == 'pretty': + import pprint + pp = pprint.PrettyPrinter(indent=2) + + # TODO: pprint doesn't do a nice job on path-style values + # if the paths contain spaces (i.e. Windows), because the + # algorithm tries to break lines on spaces, while breaking + # on the path-separator would be more "natural". Is there + # a better way to format those? + return pp.pformat(cvars) + + elif fmt == 'json': + import json + def non_serializable(obj): + return str(type(obj).__qualname__) + return json.dumps(cvars, indent=4, default=non_serializable) + else: + raise ValueError("Unsupported serialization format: %s." % fmt) def FindIxes(self, paths, prefix, suffix): diff --git a/SCons/Environment.xml b/SCons/Environment.xml index d13d560..898dc5d 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -1393,11 +1393,34 @@ for more information. -([key]) +([key], [format]) -Returns a pretty printable representation of the environment. +Serializes the construction variables to a string. +The method supports the following formats specified by +format: + + +pretty + + +Returns a pretty printable representation of the environment (if +format +is not specified, this is the default). + + + + +json + + +Returns a JSON-formatted string representation of the environment. + + + + + key, if not None, diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py index ef12a6f..6dcf3c1 100644 --- a/SCons/EnvironmentTests.py +++ b/SCons/EnvironmentTests.py @@ -2941,6 +2941,18 @@ def generate(env): assert env.Dump('FOO') == "'foo'", env.Dump('FOO') assert len(env.Dump()) > 200, env.Dump() # no args version + assert env.Dump('FOO', 'json') == '"foo"' # JSON key version + import json + env_dict = json.loads(env.Dump(format = 'json')) + assert env_dict['FOO'] == 'foo' # full JSON version + + try: + env.Dump(format = 'markdown') + except ValueError as e: + assert str(e) == "Unsupported serialization format: markdown." + else: + self.fail("Did not catch expected ValueError.") + def test_Environment(self): """Test the Environment() method""" env = self.TestEnvironment(FOO = 'xxx', BAR = 'yyy') -- cgit v0.12 From 46810dae9a306c934f89ad6b3f37cc82eb2026a5 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 29 May 2020 11:14:49 -0600 Subject: Close scons logfiles on completion Files written to in logging operations could remain unclosed: more modern Pythons grumble about this; given the type of Python build, could emit ResourceWarning messages which cause tests to fail. Close by registering calls with atexit. Affects Trace, cache debug, taskmastertrace, configure. Signed-off-by: Mats Wichmann --- CHANGES.txt | 2 ++ SCons/CacheDir.py | 7 ++++++- SCons/Debug.py | 34 ++++++++++++++++++++++++++-------- SCons/SConf.py | 10 ++++++++-- SCons/Script/Main.py | 5 +++++ 5 files changed, 47 insertions(+), 11 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index ecf3255..88b8d6f 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -150,6 +150,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - ParseFlags should not modify the user's passed in dict in case it's a compound data structure (e.g. values are lists) (issue #3665) - In Py3 classes no longer need to be listed as deriving from object. + - Close various logfiles (trace, cache, taskmastertrace, configure) + when done using atexit calls. diff --git a/SCons/CacheDir.py b/SCons/CacheDir.py index 5ecbc6f..3bb6671 100644 --- a/SCons/CacheDir.py +++ b/SCons/CacheDir.py @@ -27,13 +27,14 @@ __doc__ = """ CacheDir support """ +import atexit import json import os import stat import sys -import SCons import SCons.Action +import SCons.Errors import SCons.Warnings cache_enabled = True @@ -202,7 +203,11 @@ class CacheDir: if cache_debug == '-': self.debugFP = sys.stdout elif cache_debug: + def debug_cleanup(debugFP): + debugFP.close() + self.debugFP = open(cache_debug, 'w') + atexit.register(debug_cleanup, self.debugFP) else: self.debugFP = None self.current_cache_debug = cache_debug diff --git a/SCons/Debug.py b/SCons/Debug.py index 706b4c4..10cd2f5 100644 --- a/SCons/Debug.py +++ b/SCons/Debug.py @@ -33,6 +33,7 @@ caller_trace() __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" +import atexit import os import sys import time @@ -66,7 +67,7 @@ def string_to_classes(s): def fetchLoggedInstances(classes="*"): classnames = string_to_classes(classes) return [(cn, len(tracked_classes[cn])) for cn in classnames] - + def countLoggedInstances(classes, file=sys.stdout): for classname in string_to_classes(classes): file.write("%s: %d\n" % (classname, len(tracked_classes[classname]))) @@ -201,22 +202,39 @@ if sys.platform == 'win32': TraceDefault = 'con' else: TraceDefault = '/dev/tty' - -TimeStampDefault = None +TimeStampDefault = False StartTime = time.time() PreviousTime = StartTime -def Trace(msg, file=None, mode='w', tstamp=None): - """Write a trace message to a file. Whenever a file is specified, - it becomes the default for the next call to Trace().""" +def Trace(msg, filename=None, mode='w', tstamp=False): + """Write a trace message. + + Write messages when debugging which do not interfere with stdout. + Useful in tests, which monitor stdout and would break with + unexpected output. Trace messages can go to the console (which is + opened as a file), or to a disk file; the file argument persists + across calls unless overridden. + + Args: + filename: file to write trace message to. If omitted, + write to the previous trace file (default: console). + mode: file open mode (default: 'w') + tstamp: write relative timestamps with trace. Outputs time since + scons was started, and time since last trace (default: False) + + """ global TraceDefault global TimeStampDefault global PreviousTime + + def traace_cleanup(traceFP): + traceFP.close() + if file is None: file = TraceDefault else: TraceDefault = file - if tstamp is None: + if not tstamp: tstamp = TimeStampDefault else: TimeStampDefault = tstamp @@ -225,6 +243,7 @@ def Trace(msg, file=None, mode='w', tstamp=None): except KeyError: try: fp = TraceFP[file] = open(file, mode) + atexit.register(trace_cleanup, fp) except TypeError: # Assume we were passed an open file pointer. fp = file @@ -234,7 +253,6 @@ def Trace(msg, file=None, mode='w', tstamp=None): PreviousTime = now fp.write(msg) fp.flush() - fp.close() # Local Variables: # tab-width:4 diff --git a/SCons/SConf.py b/SCons/SConf.py index 42bfa8c..efa9e5b 100644 --- a/SCons/SConf.py +++ b/SCons/SConf.py @@ -37,6 +37,7 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" import SCons.compat +import atexit import io import os import re @@ -750,11 +751,16 @@ class SConfBase: _ac_config_logs[self.logfile] = None log_mode = "w" fp = open(str(self.logfile), log_mode) + + def conflog_cleanup(logf): + logf.close() + + atexit.register(conflog_cleanup, fp) self.logstream = SCons.Util.Unbuffered(fp) # logfile may stay in a build directory, so we tell - # the build system not to override it with a eventually + # the build system not to override it with an eventually # existing file with the same name in the source directory - self.logfile.dir.add_ignore( [self.logfile] ) + self.logfile.dir.add_ignore([self.logfile]) tb = traceback.extract_stack()[-3-self.depth] old_fs_dir = SConfFS.getcwd() diff --git a/SCons/Script/Main.py b/SCons/Script/Main.py index ac29712..d7b07a2 100644 --- a/SCons/Script/Main.py +++ b/SCons/Script/Main.py @@ -40,6 +40,7 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" import SCons.compat +import atexit import importlib.util import os import re @@ -1262,10 +1263,14 @@ def _build_targets(fs, options, targets, target_top): """Leave the order of dependencies alone.""" return dependencies + def tmtrace_cleanup(tfile): + tfile.close() + if options.taskmastertrace_file == '-': tmtrace = sys.stdout elif options.taskmastertrace_file: tmtrace = open(options.taskmastertrace_file, 'w') + atexit.register(tmtrace_cleanup, tmtrace) else: tmtrace = None taskmaster = SCons.Taskmaster.Taskmaster(nodes, task_class, order, tmtrace) -- cgit v0.12 From 5708798e8443376cb52819dc1bcae3a59ed94ea6 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 29 May 2020 12:25:45 -0600 Subject: Fix typo in new trace_cleanup interior func Spotted by sider Signed-off-by: Mats Wichmann --- SCons/Debug.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Debug.py b/SCons/Debug.py index 10cd2f5..2212eb8 100644 --- a/SCons/Debug.py +++ b/SCons/Debug.py @@ -227,7 +227,7 @@ def Trace(msg, filename=None, mode='w', tstamp=False): global TimeStampDefault global PreviousTime - def traace_cleanup(traceFP): + def trace_cleanup(traceFP): traceFP.close() if file is None: -- cgit v0.12 From 430d6ab06d6ecaf66eb08c7d39a81f3a8f8103e0 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Fri, 29 May 2020 12:42:07 -0700 Subject: Update LDC Version to 1.21.0, remove py27 logic, add rpm install --- .travis/install.sh | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/.travis/install.sh b/.travis/install.sh index 64a300b..597af4c 100755 --- a/.travis/install.sh +++ b/.travis/install.sh @@ -19,6 +19,9 @@ else sudo ln -s /usr/local/clang-5.0.0/bin/clang++ /usr/bin/clang++ fi + # dependencies for rpm packaging tests + sudo apt-get -y install rpm + # dependencies for gdc tests sudo apt-get -y install gdc @@ -42,17 +45,11 @@ else sudo apt-get update && sudo apt-get -y --allow-unauthenticated install dmd-bin # dependencies for ldc tests - wget https://github.com/ldc-developers/ldc/releases/download/v1.15.0/ldc2-1.15.0-linux-x86_64.tar.xz - tar xf ldc2-1.15.0-linux-x86_64.tar.xz - sudo cp -rf ldc2-1.15.0-linux-x86_64/* / - - ls -l /usr/lib/*python*{so,a}* - - # For now skip swig if py27 - if [[ "$PYVER" == 27 ]]; then - # dependencies for swig tests - wget https://github.com/swig/swig/archive/rel-3.0.12.tar.gz - tar xzf rel-3.0.12.tar.gz - cd swig-rel-3.0.12 && ./autogen.sh && ./configure --prefix=/usr && make && sudo make install && cd .. - fi + export SCONS_LDC_VERSION=1.21.0 + wget https://github.com/ldc-developers/ldc/releases/download/v${SCONS_LDC_VERSION}/ldc2-${SCONS_LDC_VERSION}-linux-x86_64.tar.xz +# wget https://github.com/ldc-developers/ldc/releases/download/v1.15.0/ldc2-1.15.0-linux-x86_64.tar.xz + tar xf ldc2-${SCONS_LDC_VERSION}-linux-x86_64.tar.xz + sudo cp -rf ldc2-${SCONS_LDC_VERSION}-linux-x86_64/* / + + ls -l /usr/lib*/*python*{so,a}* fi -- cgit v0.12 From 19f6d2c0d64928e87383a76146981dbfee1fee1c Mon Sep 17 00:00:00 2001 From: William Deegan Date: Fri, 29 May 2020 12:44:30 -0700 Subject: Quite sider warning about unused variable in test --- SCons/TaskmasterTests.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/TaskmasterTests.py b/SCons/TaskmasterTests.py index ea673a5..c11d8e8 100644 --- a/SCons/TaskmasterTests.py +++ b/SCons/TaskmasterTests.py @@ -609,7 +609,7 @@ class TaskmasterTestCase(unittest.TestCase): n1 = Node("n1") tm = SCons.Taskmaster.Taskmaster(targets=[n1], tasker=MyTask) with self.assertRaises(TypeError): - t = tm.next_task() + _ = tm.next_task() def test_make_ready_all(self): """Test the make_ready_all() method""" -- cgit v0.12 From 615c04fae3b647cd433efa4fb05eb5f62207f462 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 27 May 2020 07:14:40 -0600 Subject: Updates to shared docs [ci skip] Mostly update markup to more "standard" markup conventions. There are some substantive wording changes to CacheDir descriptions in Environment, and to the AddOption/Help descriptions in Main and SConscript files. Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 539 +++++++++++++++++++++----------------------- SCons/Script/Main.xml | 261 +++++++++++---------- SCons/Script/SConscript.xml | 26 ++- 3 files changed, 418 insertions(+), 408 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 898dc5d..bc1864f 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -242,28 +242,25 @@ that are part of this construction environment. -Creates an Action object for +A factory function to create an Action object for the specified -action. +action. See the manpage section "Action Objects" for a complete explanation of the arguments and behavior. -Note that the -env.Action() +Note that the &f-env-Action; form of the invocation will expand construction variables in any argument strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Action() -was called. -The -Action() +&f-env-Action; was called. +The &f-Action; global function form delays all variable expansion until the Action object is actually used. @@ -283,27 +280,26 @@ When called with the AddMethod() form, adds the specified -function +function to the specified -object +object as the specified method -name. -When called with the -env.AddMethod() -form, +name. +When called using the +&f-env-AddMethod; form, adds the specified -function +function to the construction environment -env +env as the specified method -name. +name. In both cases, if -name +name is omitted or -None, +None, the name of the specified -function +function itself is used for the method name. @@ -341,10 +337,10 @@ env.other_method_name('another arg') Arranges for the specified -action +action to be performed after the specified -target +target has been built. The specified action(s) may be an Action object, or anything that @@ -369,10 +365,10 @@ one or more targets in the list. Arranges for the specified -action +action to be performed before the specified -target +target is built. The specified action(s) may be an Action object, or anything that @@ -428,7 +424,7 @@ file into an object file. Creates one or more phony targets that expand to one or more other targets. An optional -action +action (command) or list of actions can be specified that will be executed @@ -470,7 +466,7 @@ env.Alias('update', ['file1', 'file2'], "update_database $SOURCES") Marks each given -target +target so that it is always assumed to be out of date, and will always be rebuilt if needed. Note, however, that @@ -544,7 +540,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the end; it will stay where it is in the list. @@ -605,7 +601,7 @@ env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) Creates a Builder object for the specified -action. +action. See the manpage section "Builder Objects" for a complete explanation of the arguments and behavior. @@ -616,14 +612,13 @@ Note that the form of the invocation will expand construction variables in any arguments strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Builder() -was called. +&f-env-Builder; was called. The &f-Builder; form delays all variable expansion @@ -638,68 +633,61 @@ until after the Builder object is actually called. -Specifies that +Direct &scons; -will maintain a cache of derived files in -cache_dir. +to use a derived-file cache in +cache_dir. The derived files in the cache will be shared -among all the builds using the same -&f-CacheDir; -call. +among all the builds specifying the same +cache_dir. Specifying a -cache_dir +cache_dir of -None +None disables derived file caching. -Calling -env.CacheDir() -will only affect targets built +Calling the environment method +&f-link-env-CacheDir; +limits the effect to targets built through the specified construction environment. -Calling -&f-CacheDir; +Calling the global function +&f-link-CacheDir; sets a global default that will be used by all targets built through construction environments -that do -not -have an -env.CacheDir() -specified. +that do not set up environment-specific +caching by calling &f-env-CacheDir;. -When a -CacheDir() +When cachin +cache_dir 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 -derived file has already been built -from identical input files and an identical build action -(as incorporated into the MD5 build signature). -If so, -&scons; -will retrieve the file from the cache. +file with matching build signature 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. If the derived file is not present in the cache, &scons; -will rebuild it and -then place a copy of the built file in the cache -(identified by its MD5 build signature), -so that it may be retrieved by other -builds that need to build the same derived file -from identical inputs. +will build it and +then place a copy of the built file in the cache, +identified by its build signature, for future use. -Use of a specified -&f-CacheDir; +Derived-file caching may be disabled for any invocation -by using the +of &scons; by giving the -option. +command line option. +Cache updating may be disabled, leaving cache +fetching enabled, by giving the +. @@ -713,32 +701,31 @@ derived files in the cache, even if they already existed and were not built by this invocation. This is useful to populate a cache -the first time -&f-CacheDir; -is added to a build, -or after using the - -option. +the first time a +cache_dir +is used for a build, +or to bring a cache up to date after +a build with cache updating disabled +( +or ) +has been done. When using &f-CacheDir;, &scons; -will report, -"Retrieved `file' from cache," +will report +Retrieved `file' from cache unless the option is being used. -When the +With the -option is used, -&scons; -will print the action that -would -have been used to build the file, -without any indication that -the file was actually retrieved from the cache. +option, &scons; +will print the action that would +have been used to build the file +whether or not it was retreived from the cache. This is useful to generate build logs that are equivalent regardless of whether a given derived file has been built in-place @@ -854,7 +841,7 @@ env4 = env.Clone(tools = ['msvc', MyTool]) The -parse_flags +parse_flags keyword argument is also recognized to allow merging command-line style arguments into the appropriate construction variables (see &f-link-env-MergeFlags;). @@ -890,21 +877,23 @@ for the calling syntax and details. -Executes a specific action +Executes a specific action (or list of actions) -to build a target file or files. +to build a target file or files +from a source file or files. This is more convenient than defining a separate Builder object for a single special-case build. -&b-Command; builder accepts -source_scanner, -target_scanner, -source_factory, and -target_factory -keyword arguments. The *_scanner args can +The +&Command; function accepts +source_scanner, +target_scanner, +source_factory, and +target_factory +keyword arguments. These arguments can be used to specify a Scanner object that will be used to apply a custom @@ -916,12 +905,12 @@ if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder of function calls. -The *_factory args take a factory function that the -Command will use to turn any sources or targets +The *_factory arguments take a factory function that +&Command; will use to turn any sources or targets specified as strings into SCons Nodes. -See the sections "Builder Objects" -below, for more information about how these -args work in a Builder. +See the manpage section "Builder Objects" +for more information about how these +arguments work in a Builder. @@ -936,13 +925,11 @@ or a callable Python object; see the manpage section "Action Objects" for more complete information. Also note that a string specifying an external command -may be preceded by an -@ -(at-sign) +may be preceded by an at-sign +(@) to suppress printing the command in question, -or by a -- -(hyphen) +or by a hyphen +(-) to ignore the exit status of the external command. @@ -951,26 +938,35 @@ Examples: -env.Command('foo.out', 'foo.in', - "$FOO_BUILD < $SOURCES > $TARGET") +env.Command( + target='foo.out', + source='foo.in', + action="$FOO_BUILD < $SOURCES > $TARGET" +) + +env.Command( + target='bar.out', + source='bar.in', + action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], + ENV={'PATH': '/usr/local/bin/'}, +) -env.Command('bar.out', 'bar.in', - ["rm -f $TARGET", - "$BAR_BUILD < $SOURCES > $TARGET"], - ENV={'PATH': '/usr/local/bin/'}) +import os def rename(env, target, source): - import os os.rename('.tmp', str(target[0])) -env.Command('baz.out', 'baz.in', - ["$BAZ_BUILD < $SOURCES > .tmp", - rename]) + +env.Command( + target='baz.out', + source='baz.in', + action=["$BAZ_BUILD < $SOURCES > .tmp", rename], +) Note that the -&f-Command; +&Command; function will usually assume, by default, that the specified targets and/or sources are Files, if no other part of the configuration @@ -981,7 +977,7 @@ be treated as directories by using the &f-link-Dir; or -env.Dir +&f-link-env-Dir; functions. @@ -1021,18 +1017,6 @@ for a complete explanation of the arguments and behavior. - - -([key=val, ...]) - - - -A now-deprecated synonym for -env.Clone(). - - - - (function) @@ -1042,9 +1026,8 @@ A now-deprecated synonym for Specifies that all up-to-date decisions for targets built through this construction environment will be handled by the specified -function. -The -function +function. +function can be one of the following strings that specify the type of decision function to be performed: @@ -1053,7 +1036,7 @@ to be performed: -timestamp-newer +"timestamp-newer" Specifies that a target shall be considered out of date and rebuilt @@ -1067,7 +1050,7 @@ can be used a synonym for -timestamp-match +"timestamp-match" Specifies that a target shall be considered out of date and rebuilt @@ -1084,7 +1067,7 @@ timestamp, such as can happen when restoring files from backup archives. -MD5 +"MD5" Specifies that a target shall be considered out of date and rebuilt @@ -1101,7 +1084,7 @@ can be used as a synonym for -MD5-timestamp +"MD5-timestamp" Specifies that a target shall be considered out of date and rebuilt @@ -1148,7 +1131,7 @@ env.Decider('content') In addition to the above already-available functions, the -function +function argument may be a Python function you supply. Such a function must accept the following four arguments: @@ -1161,10 +1144,10 @@ Such a function must accept the following four arguments: The Node (file) which should cause the -target +target to be rebuilt if it has "changed" since the last tme -target +target was built. @@ -1177,7 +1160,7 @@ The Node (file) being built. In the normal case, this is what should get rebuilt if the -dependency +dependency has "changed." @@ -1187,9 +1170,9 @@ has "changed." Stored information about the state of the -dependency +dependency the last time the -target +target was built. This can be consulted to match various file characteristics @@ -1203,11 +1186,11 @@ size, or content signature. If set, use this Node instead of the one specified by -dependency +dependency to determine if the dependency has changed. This argument is optional so should be written as a default argument (typically it would be -written as repo_node=None). +written as repo_node=None). A caller will normally only set this if the target only exists in a Repository. @@ -1219,14 +1202,14 @@ target only exists in a Repository. The -function +function should return a value which evaluates True if the -dependency +dependency has "changed" since the last time the -target +target was built (indicating that the target should @@ -1264,15 +1247,15 @@ env.Decider(my_decider) Specifies an explicit dependency; the -target +target will be rebuilt whenever the -dependency +dependency has changed. Both the specified -target +target and -dependency +dependency can be a string (usually the path name of a file or directory) or Node objects, @@ -1317,9 +1300,9 @@ Find an executable from one or more choices: Returns the first value from progs that was found, or None. Executable is searched by checking the paths specified -by env['ENV']['PATH']. +by env['ENV']['PATH']. On Windows systems, additionally applies the filename suffixes found in -env['ENV']['PATHEXT'] +env['ENV']['PATHEXT'] but will not include any such extension in the return value. &f-env-Detect; is a wrapper around &f-link-env-WhereIs;. @@ -1359,24 +1342,24 @@ cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') Returns Directory Node(s). A Directory Node is an object that represents a directory. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1397,7 +1380,7 @@ for more information. -Serializes the construction variables to a string. +Serializes &cpnsvars; to a string. The method supports the following formats specified by format: @@ -1405,7 +1388,7 @@ The method supports the following formats specified by pretty -Returns a pretty printable representation of the environment (if +Returns a pretty printed representation of the environment (if format is not specified, this is the default). @@ -1421,10 +1404,11 @@ Returns a JSON-formatted string representation of the environment. -key, -if not -None, -should be a string containing the name of the variable of interest. +If key is +None (the default) the entire +dictionary of &consvars; is serialized. +If supplied, it is taken as the name of a &consvar; +whose value is serialized. @@ -1476,7 +1460,7 @@ will print: Return a new construction environment initialized with the specified -key=value +key=value pairs. @@ -1490,16 +1474,20 @@ pairs. Executes an Action object. The specified -action +action may be an Action object (see manpage section "Action Objects" -for a complete explanation of the arguments and behavior), +for an explanation of behavior), or it may be a command-line string, list of commands, or executable Python function, each of which will be converted into an Action object and then executed. +Any additional arguments to &f-Execute; +(strfunction, varlist) +are passed on to the &f-link-Action; factory function +which actually creates the Action object. The exit value of the command or return value of the Python function will be returned. @@ -1509,7 +1497,7 @@ will be returned. Note that &scons; will print an error message if the executed -action +action fails--that is, exits with or returns a non-zero value. &scons; @@ -1518,7 +1506,7 @@ will however, automatically terminate the build if the specified -action +action fails. If you want the build to stop in response to a failed &f-Execute; @@ -1544,24 +1532,24 @@ if Execute("mkdir sub/dir/ectory"): Returns File Node(s). A File Node is an object that represents a file. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1583,10 +1571,10 @@ for more information. Search for -file +file in the path specified by -dirs. -dirs +dirs. +dirs may be a list of directory names or a single directory name. In addition to searching for files that exist in the filesystem, this function also searches for derived files @@ -1650,9 +1638,9 @@ FindInstalledFiles() Returns the list of nodes which serve as the source of the built files. It does so by inspecting the dependency tree starting at the optional argument -node +node which defaults to the '"."'-node. It will then return all leaves of -node. +node. These are all children which have no further children. @@ -1721,7 +1709,7 @@ Program(source = objects) # If you need to manipulate the list directly using Python, you need to # call Flatten() yourself, or otherwise handle nested lists: for object in Flatten(objects): - print str(object) + print(str(object)) @@ -1735,10 +1723,10 @@ for object in Flatten(objects): Returns the &scons; path name (or names) for the specified -file +file (or files). The specified -file +file or files may be &scons; @@ -1754,21 +1742,20 @@ Nodes or strings representing path names. Returns Nodes (or strings) that match the specified -pattern, +pattern, relative to the directory of the current &SConscript; file. -The -env.Glob() -form performs string substition on -pattern +The evironment method form (&f-env-Glob;) +performs string substition on +pattern and returns whatever matches the resulting expanded pattern. The specified -pattern +pattern uses Unix shell style metacharacters for matching: @@ -1802,14 +1789,14 @@ function) and returns a Node (or string, if so configured) in the local (SConscript) directory -if matching Node is found +if a matching Node is found anywhere in a corresponding repository or source directory. The -ondisk +ondisk argument may be set to a value which evaluates False to disable the search for matches on disk, @@ -1822,7 +1809,7 @@ for any on-disk matches found. The -source +source argument may be set to a value which evaluates True to specify that, @@ -1835,7 +1822,7 @@ not the local directory. The -strings +strings argument may be set to a value which evaluates True to have the @@ -1861,7 +1848,7 @@ directory.) The -exclude +exclude argument may be set to a pattern or a list of patterns (following the same Unix shell semantics) which must be filtered out of returned elements. @@ -1890,7 +1877,7 @@ sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \ When -flag +flag is non-zero, adds the names of the default builders (Program, Library, etc.) @@ -1898,7 +1885,7 @@ to the global name space so they can be called without an explicit construction environment. (This is the default.) When -flag +flag is zero, the names of the default builders are removed from the global name space @@ -1956,7 +1943,7 @@ env.Ignore('bar','bar/foobar.obj') The specified -string +string will be preserved as-is and not have construction variables expanded. @@ -1970,7 +1957,7 @@ and not have construction variables expanded. The specified -targets +targets will have copies made in the local tree, even if an already up-to-date copy exists in a repository. @@ -1987,14 +1974,14 @@ Returns a list of the target Node or Nodes. Merges the elements of the specified -arg, +arg, which must be a dictionary, to the construction environment's copy of the shell environment in env['ENV']. (This is the environment which is passed to subshells spawned by SCons.) Note that -arg +arg must be a single value, so multiple strings must be passed in as a list, @@ -2011,7 +1998,7 @@ since this function calls or &f-link-PrependENVPath; depending on the -prepend +prepend argument. See those functions for more details. @@ -2036,17 +2023,17 @@ env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) Merges the specified -arg +arg values to the construction environment's construction variables. If the -arg +arg argument is not a dictionary, it is converted to one by calling &f-link-env-ParseFlags; on the argument before the values are merged. Note that -arg +arg must be a single value, so multiple strings must be passed in as a list, @@ -2198,11 +2185,11 @@ NoClean(env.Program('hello', 'hello.c')) Calls the specified -function +function to modify the environment as specified by the output of -command. +command. The default -function +function is &f-link-env-MergeFlags;, which expects the output of a typical @@ -2240,7 +2227,7 @@ for a table of options and construction variables. Parses the contents of the specified -filename +filename as a list of dependencies in the style of &Make; or @@ -2252,10 +2239,10 @@ and explicitly establishes all of the listed dependencies. By default, it is not an error if the specified -filename +filename does not exist. The optional -must_exist +must_exist argument may be set to a non-zero value to have scons @@ -2266,7 +2253,7 @@ or is otherwise inaccessible. The optional -only_one +only_one argument may be set to a non-zero value to have scons @@ -2288,7 +2275,7 @@ file. The -filename +filename and all of the files listed therein will be interpreted relative to the directory of the @@ -2417,7 +2404,7 @@ env = Environment(platform = Platform('win32')) The &f-env-Platform; form applies the callable object for the specified platform -string +string to the environment through which the method was called. @@ -2502,7 +2489,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the beginning; it will stay where it is in the list. @@ -2570,16 +2557,16 @@ env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) This returns a Directory Node similar to Dir. The python module / package is looked up and if located the directory is returned for the location. -modulename +modulename Is a named python package / module to lookup the directory for it's location. If -modulename +modulename is a list, SCons returns a list of Dir nodes. Construction variables are expanded in -modulename. +modulename. @@ -2611,7 +2598,7 @@ env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') Specifies that -directory +directory is a repository to be searched for files. Multiple calls to &f-Repository; @@ -2695,7 +2682,7 @@ env.Requires('foo', 'file-that-must-be-built-before-foo') Creates a Scanner object for the specified -function. +function. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior. @@ -2760,18 +2747,18 @@ This tells &scons; to store all file signatures in the specified database -file. +file. If the -file +file name is omitted, .sconsign is used by default. (The actual file name(s) stored on disk may have an appropriated suffix appended by the - dbm_module.) +dbm_module.) If -file +file is not an absolute path name, the file is placed in the same directory as the top-level &SConstruct; @@ -2780,9 +2767,9 @@ file. If -file +file is -None, +None, then &scons; will store file signatures @@ -2796,7 +2783,7 @@ prior to SCons 0.96.91 and 0.97.) The optional -dbm_module +dbm_module argument can be used to specify which Python database module The default is to use a custom @@ -2856,13 +2843,13 @@ if 'FOO' not in env: env['FOO'] = 'foo' Declares -side_effect +side_effect as a side effect of building -target. +target. Both -side_effect +side_effect and -target +target can be a list, a file name, or a node. A side effect is a target file that is created or updated as a side effect of building other targets. @@ -2884,23 +2871,23 @@ multiple build commands. Because multiple build commands may update the same side effect file, by default the -side_effect +side_effect target is not automatically removed when the -target +target is removed by the option. (Note, however, that the -side_effect +side_effect might be removed as part of cleaning the directory in which it lives.) If you want to make sure the -side_effect +side_effect is cleaned whenever a specific -target +target is cleaned, you must specify this explicitly with the @@ -2917,13 +2904,13 @@ function. Returns a list of file names or other objects. -If arg is a string, +If arg is a string, it will be split on strings of white-space characters within the string, making it easier to write long lists of file names. -If arg is already a list, +If arg is already a list, the list will be returned untouched. -If arg is any other type of object, +If arg is any other type of object, it will be returned as a list containing just the object. @@ -2952,7 +2939,7 @@ files = Split(""" Performs construction variable interpolation on the specified string or sequence argument -input. +input. @@ -2967,14 +2954,14 @@ and $) character sequences will be stripped from the returned string, The optional -raw +raw argument may be set to 1 if you want to preserve white space and $(-$) sequences. The -raw +raw argument may be set to 2 if you want to strip @@ -2997,9 +2984,9 @@ and the results will be returned as a list. The optional -target +target and -source +source keyword arguments must be set to lists of target and source nodes, respectively, @@ -3021,7 +3008,7 @@ as an SCons action. Returned string values or sequence elements are converted to their string representation by default. The optional -conv +conv argument may specify a conversion function that will be used in place of @@ -3100,7 +3087,7 @@ as part of the tools keyword argument, or it can be called directly, passing a &consenv; to update as the argument. Either approach will also update the -TOOLS &consvar;. +&cv-TOOLS; &consvar;. @@ -3128,17 +3115,17 @@ u(env) # adds 'opengl' to the TOOLS variable Returns a Node object representing the specified Python value. Value Nodes can be used as dependencies of targets. If the result of calling -str(value) +str(value) changes between SCons runs, any targets depending on -Value(value) +Value(value) will be rebuilt. (This is true even when using timestamps to decide if files are up-to-date.) When using timestamp source signatures, Value Nodes' timestamps are equal to the system time when the Node is created. -name can be provided as an alternative name +name can be provided as an alternative name for the resulting Value node; this is advised -if the value parameter can't be converted to +if the value parameter can't be converted to a string. @@ -3148,7 +3135,7 @@ The returned Value Node object has a method that can be used to "build" a Value Node by setting a new value. The optional -built_value +built_value argument can be specified when the Value Node is created to indicate the Node should already be considered @@ -3208,11 +3195,11 @@ Use the &f-VariantDir; function to create a copy of your sources in another location: if a name under -variant_dir +variant_dir is not found but exists under -src_dir, +src_dir, the file or directory is copied to -variant_dir. +variant_dir. Target files can be built in a different directory than the original sources by simply refering to the sources (and targets) within the variant tree. @@ -3221,15 +3208,15 @@ within the variant tree. &f-VariantDir; can be called multiple times with the same -src_dir +src_dir to set up multiple builds with different options -(variants). +(variants). The -src_dir +src_dir location must be in or underneath the SConstruct file's directory, and -variant_dir +variant_dir may not be underneath -src_dir. +src_dir. -&f-SetOption; is not currently supported for -options added with &f-AddOption;. -Any specified -help= -strings for the new option(s) -will be displayed by the - -or - -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -&f-AddOption; -will appear below the SCons options themselves, -under a separate -Local Options -heading. -The options will appear in the help text -in the order in which the +Help text for an option is a combination +of the string supplied in the +help keyword +argument to &f-AddOption; and information +collected from the other keyword arguments. +Such help is displayed if the + command line option +is used (but not with ). +Help for all local options is displayed +under the separate heading +Local Options. +The options are unsorted - they will appear +in the help text in the order in which the &f-AddOption; calls occur. @@ -138,27 +133,50 @@ Example: -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) +AddOption( + '--prefix', + dest='prefix', + nargs=1, + type='string', + action='store', + metavar='DIR', + help='installation prefix', +) +env = Environment(PREFIX=GetOption('prefix')) +For that example, +the following help text would be produced: + + +Local Options: + --prefix=DIR installation prefix + + + +Help text for local options may be unavailable if +the &f-link-Help; function has been called, +see the &f-Help; documentation for details. + + -While &AddOption; behaves like -add_option, -from the optparse module, +As an artifact of the internal implementation, the behavior of options added by &AddOption; -which take arguments is underfined in -scons if whitespace +which take option arguments is undefined +if whitespace (rather than an = sign) is used as -the separator on the command line when -the option is invoked. -Such usage should be avoided. +the separator on the command line. +Users should avoid such usage; it is recommended +to add a note to this effect to project documentation +if the situation is likely to arise. +In addition, if the nargs +keyword is used to specify more than one following +option argument (that is, with a value of 2 +or greater), such arguments would necessarily +be whitespace separated, triggering the issue. +Developers should not use &AddOption; this way. +Future versions of &SCons; will likely forbid such usage. @@ -582,22 +600,21 @@ evaluating Nodes (e.g. files). If the first specified argument is a Python callable (a function or an object that has a -__call__() -method), +__call__ method), the function will be called once every interval -times a Node is evaluated. +times a Node is evaluated (default 1). The callable will be passed the evaluated Node as its only argument. (For future compatibility, it's a good idea to also add -*args +*args and -**kw -as arguments to your function or method. +**kwargs +as arguments to your function or method signatures. This will prevent the code from breaking -if SCons ever changes the interface +if &SCons; ever changes the interface to call the function with additional arguments in the future.) @@ -608,7 +625,7 @@ every 10 Nodes: -def my_progress_function(node, *args, **kw): +def my_progress_function(node, *args, **kwargs): print('Evaluating node %s!' % node) Progress(my_progress_function, interval=10) @@ -626,8 +643,7 @@ will overwrite itself on a display: import sys - -class ProgressCounter: +class ProgressCounter(object): count = 0 def __call__(self, node, *args, **kw): self.count += 100 @@ -637,18 +653,28 @@ Progress(ProgressCounter(), interval=100) -If the first argument -&f-link-Progress; -is a string, -the string will be displayed -every +If the first argument to +&f-Progress; is a string or list of strings, +it is taken as text to be displayed every +interval +evaluated Nodes. +If the first argument is a list of strings, +then each string in the list will be displayed +in rotating fashion every interval evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream + + + +The default is to print the string on standard output. +An alternate output stream may be specified with the -file= -argument. +file +keyword argument, which the +caller must pass already opened. + + + The following will print a series of dots on the error output, one dot for every 100 evaluated Nodes: @@ -661,7 +687,7 @@ Progress('.', interval=100, file=sys.stderr) If the string contains the verbatim substring -&cv-TARGET;, +$TARGET;, it will be replaced with the Node. Note that, for performance reasons, this is not @@ -670,12 +696,13 @@ so you can not use other variables or use curly braces. The following example will print the name of every evaluated Node, -using a -\r -(carriage return) to cause each line to overwritten by the next line, +using a carriage return) +(\r) +to cause each line to overwritten by the next line, and the -overwrite= -keyword argument to make sure the previously-printed +overwrite +keyword argument (default False) +to make sure the previously-printed file name is overwritten with blank spaces: @@ -685,15 +712,9 @@ Progress('$TARGET\r', overwrite=True) -If the first argument to -&f-Progress; -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: +A list of strings can be used to implement a "spinner" +on the user's screen as follows, changing every +five evaluated Nodes: diff --git a/SCons/Script/SConscript.xml b/SCons/Script/SConscript.xml index 9c383f8..03efcfb 100644 --- a/SCons/Script/SConscript.xml +++ b/SCons/Script/SConscript.xml @@ -248,22 +248,24 @@ file is found. -This specifies help text to be printed if the +Specifies a local help message to be printed if the argument is given to &scons;. -If -&f-Help; -is called multiple times, the text is appended together in the order that +Subsequent calls to &f-Help; -is called. With append set to False, any -&f-Help; -text generated with -&f-AddOption; -is clobbered. If append is True, the AddOption help is prepended to the help -string, thus preserving the - -message. +append text to the previously +defined local help text. + + +For the first call to &f-Help; only, +if append is False +(the default) +any local help message generated through +&f-link-AddOption; calls is replaced. +If append is True, +text is appended to +the existing help text. -- cgit v0.12 From 77b7f15937bd601fe20f50938be6804ae5ab128b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 27 May 2020 07:22:02 -0600 Subject: [PR #3671] fix typo; add missed file [ci skip] Sider detected a misspelled tag Failed to "add" one changed doc file, Defaults.xml. Added. Signed-off-by: Mats Wichmann --- SCons/Defaults.xml | 27 ++++++++++++++++----------- SCons/Environment.xml | 2 +- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/SCons/Defaults.xml b/SCons/Defaults.xml index bd41cdf..8f3fe12 100644 --- a/SCons/Defaults.xml +++ b/SCons/Defaults.xml @@ -572,20 +572,25 @@ searching the repositories. -Creates and returns the default &consenv; object. -The default &consenv; is used internally by SCons +Instantiates and returns the default &consenv; object. +The &defenv; is used internally by SCons in order to execute many of the global functions in this list -(i.e. those not called as methods of a specific -&consenv;), and to fetch source files transparently -from source code management systems. -The default environment is a singleton, so the keyword +(that is, those not called as methods of a specific &consenv;). +It is not mandatory to call &f-DefaultEnvironment;: +the &defenv; will be instantiated automatically when the +build phase begins if the function has not been called, +however calling it explicitly gives the opportunity to +affect and examine the contents of the &defenv;. + + +The &defenv; is a singleton, so the keyword arguments affect it only on the first call, on subsequent calls the already-constructed object is returned and -any arguments are ignored. -The default environment can be modified in the same way -as any &consenv;. -Modifying the &defenv; has no effect on the environment -constructed by a subsequent &f-Environment; call. +any keyword arguments are silently ignored. +The &defenv; can be modified after instantiation +in the same way as any &consenv;. +Modifying the &defenv; has no effect on the &consenv; +constructed by an &f-link-Environment; or &f-link-Clone; call. diff --git a/SCons/Environment.xml b/SCons/Environment.xml index bc1864f..fe7841a 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -905,7 +905,7 @@ if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder of function calls. -The *_factory arguments take a factory function that +The *_factory arguments take a factory function that &Command; will use to turn any sources or targets specified as strings into SCons Nodes. See the manpage section "Builder Objects" -- cgit v0.12 From 0f89d1bacbfb8f3983a705c1a507916e9260f93b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 30 May 2020 07:33:27 -0600 Subject: Docstring changes from Sphinx conversion [ci skip] These changes are prompted by complaints Sphinx makes about existing docstrings; split from the Sphinx-build PR to make for easier reviewing. Signed-off-by: Mats Wichmann --- SCons/Environment.py | 45 ++++++++++++++--------- SCons/Errors.py | 87 +++++++++++++++++++++----------------------- SCons/Platform/__init__.py | 25 ++++++++----- SCons/Script/SConsOptions.py | 36 +++++++++--------- SCons/Tool/dmd.py | 45 +++++++++++++++++------ SCons/Tool/intelc.py | 16 ++++---- SCons/Tool/packaging/rpm.py | 29 ++++++++------- SCons/Util.py | 30 +++++++++------ SCons/Variables/__init__.py | 50 +++++++++++++------------ SCons/cpp.py | 3 +- SCons/dblite.py | 1 + 11 files changed, 208 insertions(+), 159 deletions(-) diff --git a/SCons/Environment.py b/SCons/Environment.py index cd52ee5..f9af099 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1502,11 +1502,16 @@ class Base(SubstitutionEnvironment): def Dictionary(self, *args): """Return construction variables from an environment. - :param *args: (optional) variable names to look up - :returns: if args omitted, the dictionary of all constr. vars. - If one arg, the corresponding value is returned. - If more than one arg, a list of values is returned. - :raises KeyError: if any of *args is not in the construction env. + Args: + \*args (optional): variable names to look up + + Returns: + If `args` omitted, the dictionary of all construction variables. + If one arg, the corresponding value is returned. + If more than one arg, a list of values is returned. + + Raises: + KeyError: if any of `args` is not in the construction environment. """ if not args: @@ -1518,14 +1523,15 @@ class Base(SubstitutionEnvironment): def Dump(self, key=None, format='pretty'): - """ Serialize the construction variables to a string. + """ Return construction variables serialized to a string. - :param key: if None, format the whole dict of variables. - Else look up and format just the value for key. - - :param format: specify the format of the variables to be serialized: - - pretty: pretty-printed string. - - json: JSON-formatted string. + Args: + key (optional): if None, format the whole dict of variables. + Else format the value of `key` (Default value = None) + format (optional): specify the format to serialize to. + `"pretty"` generates a pretty-printed string, + `"json"` a JSON-formatted string. + (Default value = None, equivalent to `"pretty"`) """ if key: @@ -1556,12 +1562,15 @@ class Base(SubstitutionEnvironment): def FindIxes(self, paths, prefix, suffix): - """ - Search a list of paths for something that matches the prefix and suffix. + """Search a list of paths for something that matches the prefix and suffix. + + Args: + paths: the list of paths or nodes. + prefix: construction variable for the prefix. + suffix: construction variable for the suffix. + + Returns: the matched path or None - paths - the list of paths or nodes. - prefix - construction variable for the prefix. - suffix - construction variable for the suffix. """ suffix = self.subst('$'+suffix) @@ -2017,7 +2026,7 @@ class Base(SubstitutionEnvironment): pass else: del kw['target_factory'] - + bld = SCons.Builder.Builder(**bkw) return bld(self, target, source, **kw) diff --git a/SCons/Errors.py b/SCons/Errors.py index a3a891f..ea94501 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -35,57 +35,53 @@ import SCons.Util class BuildError(Exception): - """ Errors occurring while building. + """SCons Errors that can occur while building. - BuildError have the following attributes: - ========================================= + Attributes: + Information about the cause of the build error : - Information about the cause of the build error: - ----------------------------------------------- + errstr: a description of the error message - errstr : a description of the error message + status: the return code of the action that caused the build error. + Must be set to a non-zero value even if the build error is not due + to an action returning a non-zero returned code. - status : the return code of the action that caused the build error. - Must be set to a non-zero value even if the build error is not due - to an action returning a non-zero returned code. + exitstatus: SCons exit status due to this build error. + Must be nonzero unless due to an explicit Exit() + call. Not always the same as status, since + actions return a status code that should be + respected, but SCons typically exits with 2 + irrespective of the return value of the failed + action. - exitstatus : SCons exit status due to this build error. - Must be nonzero unless due to an explicit Exit() - call. Not always the same as status, since - actions return a status code that should be - respected, but SCons typically exits with 2 - irrespective of the return value of the failed - action. + filename: The name of the file or directory that caused the + build error. Set to None if no files are associated with + this error. This might be different from the target + being built. For example, failure to create the + directory in which the target file will appear. It + can be None if the error is not due to a particular + filename. - filename : The name of the file or directory that caused the - build error. Set to None if no files are associated with - this error. This might be different from the target - being built. For example, failure to create the - directory in which the target file will appear. It - can be None if the error is not due to a particular - filename. + exc_info: Info about exception that caused the build + error. Set to (None, None, None) if this build + error is not due to an exception. - exc_info : Info about exception that caused the build - error. Set to (None, None, None) if this build - error is not due to an exception. + Information about the what caused the build error : + node: the error occured while building this target node(s) - Information about the cause of the location of the error: - --------------------------------------------------------- + executor: the executor that caused the build to fail (might + be None if the build failures is not due to the + executor failing) - node : the error occured while building this target node(s) + action: the action that caused the build to fail (might be + None if the build failures is not due to the an + action failure) - executor : the executor that caused the build to fail (might - be None if the build failures is not due to the - executor failing) + command: the command line for the action that caused the + build to fail (might be None if the build failures + is not due to the an action failure) - action : the action that caused the build to fail (might be - None if the build failures is not due to the an - action failure) - - command : the command line for the action that caused the - build to fail (might be None if the build failures - is not due to the an action failure) """ def __init__(self, @@ -138,14 +134,15 @@ class ExplicitExit(Exception): Exception.__init__(self, *args) def convert_to_BuildError(status, exc_info=None): - """ - Convert any return code a BuildError Exception. - - :Parameters: - - `status`: can either be a return code or an Exception. + """Convert a return code to a BuildError Exception. - The buildError.status we set here will normally be + The `buildError.status` we set here will normally be used as the exit status of the "scons" process. + + Args: + status: can either be a return code or an Exception. + exc_info (tuple, optional): explicit exception information. + """ if not exc_info and isinstance(status, Exception): diff --git a/SCons/Platform/__init__.py b/SCons/Platform/__init__.py index 12db824..e2a7b1e 100644 --- a/SCons/Platform/__init__.py +++ b/SCons/Platform/__init__.py @@ -56,10 +56,10 @@ import SCons.Tool def platform_default(): - """Return the platform string for our execution environment. + r"""Return the platform string for our execution environment. The returned value should map to one of the SCons/Platform/*.py - files. Since we're architecture independent, though, we don't + files. Since scons is architecture independent, though, we don't care about the machine architecture. """ osname = os.name @@ -131,26 +131,33 @@ class PlatformSpec: class TempFileMunge: - """A callable class. You can set an Environment variable to this, - then call it with a string argument, then it will perform temporary - file substitution on it. This is used to circumvent the long command - line limitation. + """Convert long command lines to use a temporary file. + + You can set an Environment variable (usually `TEMPFILE`) to this, + then call it with a string argument, and it will perform temporary + file substitution on it. This is used to circumvent limitations on + the length of command lines. Example:: - Example usage: env["TEMPFILE"] = TempFileMunge env["LINKCOM"] = "${TEMPFILE('$LINK $TARGET $SOURCES','$LINKCOMSTR')}" By default, the name of the temporary file used begins with a prefix of '@'. This may be configured for other tool chains by - setting '$TEMPFILEPREFIX': + setting the TEMPFILEPREFIX variable. Example:: + env["TEMPFILEPREFIX"] = '-@' # diab compiler env["TEMPFILEPREFIX"] = '-via' # arm tool chain env["TEMPFILEPREFIX"] = '' # (the empty string) PC Lint You can configure the extension of the temporary file through the TEMPFILESUFFIX variable, which defaults to '.lnk' (see comments - in the code below): + in the code below). Example:: + env["TEMPFILESUFFIX"] = '.lnt' # PC Lint + + Entries in the temporary file are separated by the value of the + TEMPFILEARGJOIN variable, which defaults to an OS-appropriate value. + """ def __init__(self, cmd, cmdstr = None): self.cmd = cmd diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py index 10600b6..9fee74e 100644 --- a/SCons/Script/SConsOptions.py +++ b/SCons/Script/SConsOptions.py @@ -332,29 +332,27 @@ class SConsOptionParser(optparse.OptionParser): option.process(opt, value, values, self) def reparse_local_options(self): - """ - Re-parse the leftover command-line options stored - in self.largs, so that any value overridden on the - command line is immediately available if the user turns - around and does a GetOption() right away. + """ Re-parse the leftover command-line options. - We mimic the processing of the single args - in the original OptionParser._process_args(), but here we - allow exact matches for long-opts only (no partial - argument names!). + Parse options stored in `self.largs`, so that any value + overridden on the command line is immediately available + if the user turns around and does a :func:`GetOption` right away. - Else, this would lead to problems in add_local_option() + We mimic the processing of the single args + in the original OptionParser :func:`_process_args`, but here we + allow exact matches for long-opts only (no partial argument names!). + Otherwise there could be problems in :func:`add_local_option` below. When called from there, we try to reparse the command-line arguments that - 1. haven't been processed so far (self.largs), but - 2. are possibly not added to the list of options yet. - - So, when we only have a value for "--myargument" yet, - a command-line argument of "--myarg=test" would set it. - Responsible for this behaviour is the method - _match_long_opt(), which allows for partial matches of - the option name, as long as the common prefix appears to - be unique. + + 1. haven't been processed so far (`self.largs`), but + 2. are possibly not added to the list of options yet. + + So, when we only have a value for "--myargument" so far, + a command-line argument of "--myarg=test" would set it, + per the behaviour of :func:`_match_long_opt`, + which allows for partial matches of the option name, + as long as the common prefix appears to be unique. This would lead to further confusion, because we might want to add another option "--myarg" later on (see issue #2929). diff --git a/SCons/Tool/dmd.py b/SCons/Tool/dmd.py index 3cc4ed0..ba12131 100644 --- a/SCons/Tool/dmd.py +++ b/SCons/Tool/dmd.py @@ -10,22 +10,43 @@ Evolved by Russel Winder (russel@winder.org.uk) 2010-02-07 onwards Compiler variables: - DC - The name of the D compiler to use. Defaults to dmd or gdmd, - whichever is found. - DPATH - List of paths to search for import modules. - DVERSIONS - List of version tags to enable when compiling. - DDEBUG - List of debug tags to enable when compiling. + +DC + The name of the D compiler to use. + Defaults to dmd or gdmd, whichever is found. + +DPATH + List of paths to search for import modules. + +DVERSIONS + List of version tags to enable when compiling. + +DDEBUG + List of debug tags to enable when compiling. Linker related variables: - LIBS - List of library files to link in. - DLINK - Name of the linker to use. Defaults to dmd or gdmd, - whichever is found. - DLINKFLAGS - List of linker flags. + +LIBS + List of library files to link in. + +DLINK + Name of the linker to use. + Defaults to dmd or gdmd, whichever is found. + +DLINKFLAGS + List of linker flags. Lib tool variables: - DLIB - Name of the lib tool to use. Defaults to lib. - DLIBFLAGS - List of flags to pass to the lib tool. - LIBS - Same as for the linker. (libraries to pull into the .lib) + +DLIB + Name of the lib tool to use. Defaults to lib. + +DLIBFLAGS + List of flags to pass to the lib tool. + +LIBS + Same as for the linker. (libraries to pull into the .lib) + """ # diff --git a/SCons/Tool/intelc.py b/SCons/Tool/intelc.py index 0880976..f555d22 100644 --- a/SCons/Tool/intelc.py +++ b/SCons/Tool/intelc.py @@ -387,13 +387,15 @@ def get_intel_compiler_top(version, abi): def generate(env, version=None, abi=None, topdir=None, verbose=0): r"""Add Builders and construction variables for Intel C/C++ compiler to an Environment. - args: - version: (string) compiler version to use, like "80" - abi: (string) 'win32' or whatever Itanium version wants - topdir: (string) compiler top dir, like - "c:\Program Files\Intel\Compiler70" - If topdir is used, version and abi are ignored. - verbose: (int) if >0, prints compiler version used. + + Args: + version (str): compiler version to use, like "80" + abi (str): 'win32' or whatever Itanium version wants + topdir (str): directory containing compiler tree, e.g. + "c:\\Program Files\\Intel\\Compiler70". + If `topdir` is used, `version` and `abi` are ignored. + verbose: if >0, prints compiler version used. + """ if not (is_mac or is_linux or is_windows): # can't handle this platform diff --git a/SCons/Tool/packaging/rpm.py b/SCons/Tool/packaging/rpm.py index 0e44bf9..a026e45 100644 --- a/SCons/Tool/packaging/rpm.py +++ b/SCons/Tool/packaging/rpm.py @@ -302,21 +302,24 @@ def build_specfile_filesection(spec, files): return str class SimpleTagCompiler: - """ This class is a simple string substition utility: - the replacement specfication is stored in the tagset dictionary, something - like: - { "abc" : "cdef %s ", - "abc_" : "cdef %s %s" } - - the compile function gets a value dictionary, which may look like: - { "abc" : "ghij", - "abc_gh" : "ij" } - - The resulting string will be: - "cdef ghij cdef gh ij" + """ Compile RPM tags by doing simple string substitution. + + The replacement specfication is stored in the *tagset* dictionary, + something like:: + + {"abc" : "cdef %s ", "abc_": "cdef %s %s"} + + The :func:`compile` function gets a value dictionary, which may look like:: + + {"abc": "ghij", "abc_gh": "ij"} + + The resulting string will be:: + + "cdef ghij cdef gh ij" + """ def __init__(self, tagset, mandatory=1): - self.tagset = tagset + self.tagset = tagset self.mandatory = mandatory def compile(self, values): diff --git a/SCons/Util.py b/SCons/Util.py index 1ec0cf8..ae204a1 100644 --- a/SCons/Util.py +++ b/SCons/Util.py @@ -1611,16 +1611,21 @@ def cmp(a, b): def get_env_bool(env, name, default=False): - """Get a value of env[name] converted to boolean. The value of env[name] is - interpreted as follows: 'true', 'yes', 'y', 'on' (case insensitive) and - anything convertible to int that yields non-zero integer are True values; - '0', 'false', 'no', 'n' and 'off' (case insensitive) are False values. For - all other cases, default value is returned. - - :Parameters: - - `env` - dict or dict-like object, a convainer with variables - - `name` - name of the variable in env to be returned - - `default` - returned when env[name] does not exist or can't be converted to bool + """Convert a construction variable to bool. + + If the value of *name* in *env* is 'true', 'yes', 'y', 'on' (case + insensitive) or anything convertible to int that yields non-zero then + return True; if 'false', 'no', 'n', 'off' (case insensitive) + or a number that converts to integer zero return False. + Otherwise, return *default*. + + Args: + env: construction environment, or any dict-like object + name: name of the variable + default: value to return if *name* not in *env* or cannot + be converted (default: False) + Returns: + bool: the "truthiness" of *name* """ try: var = env[name] @@ -1638,7 +1643,10 @@ def get_env_bool(env, name, default=False): def get_os_env_bool(name, default=False): - """Same as get_env_bool(os.environ, name, default).""" + """Convert an environment variable to bool. + + Conversion is the same as for :func:`get_env_bool`. + """ return get_env_bool(os.environ, name, default) # Local Variables: diff --git a/SCons/Variables/__init__.py b/SCons/Variables/__init__.py index 59b63eb..ce9335b 100644 --- a/SCons/Variables/__init__.py +++ b/SCons/Variables/__init__.py @@ -48,17 +48,21 @@ class Variables: """ Holds all the options, updates the environment with the variables, and renders the help text. - """ - instance=None - def __init__(self, files=None, args=None, is_global=1): - """ - files - [optional] List of option configuration files to load - (backward compatibility) If a single string is passed it is - automatically placed in a file list - args - dictionary to override values set from files. - """ + If is_global is True, this is a singleton, create only once. + Args: + files (optional): List of option configuration files to load + (backward compatibility). If a single string is passed it is + automatically placed in a file list (Default value = None) + args (optional): dictionary to override values set from *files*. + (Default value = None) + is_global (optional): global instance? (Default value = True) + + """ + instance = None + + def __init__(self, files=None, args=None, is_global=True): if args is None: args = {} self.options = [] @@ -112,18 +116,19 @@ class Variables: return [o.key for o in self.options] def Add(self, key, help="", default=None, validator=None, converter=None, **kw): - """ - Add an option. + """Add an option. + + Args: + key: the name of the variable, or a list or tuple of arguments + help: optional help text for the options (Default value = "") + default: optional default value for option (Default value = None) + validator: optional function called to validate the option's value + (Default value = None) + converter: optional function to be called to convert the option's + value before putting it in the environment. (Default value = None) + \*\*kw: keyword args, unused. - - @param key: the name of the variable, or a list or tuple of arguments - @param help: optional help text for the options - @param default: optional default value - @param validator: optional function that is called to validate the option's value - @type validator: Called with (key, value, environment) - @param converter: optional function that is called to convert the option's value before putting it in the environment. """ - if SCons.Util.is_List(key) or isinstance(key, tuple): self._do_add(*key) return @@ -144,10 +149,9 @@ class Variables: Example:: opt.AddVariables( - ('debug', '', 0), - ('CC', 'The C compiler'), - ('VALIDATE', 'An option for testing validation', 'notset', - validator, None), + ('debug', '', 0), + ('CC', 'The C compiler'), + ('VALIDATE', 'An option for testing validation', 'notset', validator, None), ) """ diff --git a/SCons/cpp.py b/SCons/cpp.py index 1113be5..0811c71 100644 --- a/SCons/cpp.py +++ b/SCons/cpp.py @@ -603,8 +603,7 @@ class PreProcessor: This handles recursive expansion of values without "" or <> surrounding the name until an initial " or < is found, to handle - #include FILE - where FILE is a #define somewhere else. + #include FILE where FILE is a #define somewhere else. """ s = t[1].strip() while not s[0] in '<"': diff --git a/SCons/dblite.py b/SCons/dblite.py index b9269f1..338dcc7 100644 --- a/SCons/dblite.py +++ b/SCons/dblite.py @@ -37,6 +37,7 @@ class dblite: See the discussion at: http://mail.python.org/pipermail/python-bugs-list/2003-March/016877.html + """ _open = open -- cgit v0.12 From 34f3bb7409982f847f14e506133b0290809abd31 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 30 May 2020 11:09:29 -0600 Subject: [PR #3675] fix doc typo from sider [ci skip] Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 10 +++++----- SCons/Errors.py | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index fe7841a..f06fda1 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -662,7 +662,7 @@ caching by calling &f-env-CacheDir;. -When cachin +When a cache_dir is being used and &scons; @@ -1027,10 +1027,10 @@ Specifies that all up-to-date decisions for targets built through this construction environment will be handled by the specified function. -function -can be one of the following strings -that specify the type of decision function -to be performed: +function can be the name of +a function or one of the following strings +that specify the predefined decision function +that will be applied: diff --git a/SCons/Errors.py b/SCons/Errors.py index a3a891f..1f6c240 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -73,7 +73,7 @@ class BuildError(Exception): Information about the cause of the location of the error: --------------------------------------------------------- - node : the error occured while building this target node(s) + node : the error occurred while building this target node(s) executor : the executor that caused the build to fail (might be None if the build failures is not due to the -- cgit v0.12 From 332a744ba0ae805316e1433ceddea2ff1f30536a Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 30 May 2020 11:13:47 -0600 Subject: [PR #3675] fix doc typo from sider [ci skip] Signed-off-by: Mats Wichmann --- SCons/Errors.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Errors.py b/SCons/Errors.py index ea94501..887afcf 100644 --- a/SCons/Errors.py +++ b/SCons/Errors.py @@ -68,7 +68,7 @@ class BuildError(Exception): Information about the what caused the build error : - node: the error occured while building this target node(s) + node: the error occurred while building this target node(s) executor: the executor that caused the build to fail (might be None if the build failures is not due to the -- cgit v0.12 From 285c28af96dbf536e63211c8d12bdfc75d522c9e Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 30 May 2020 19:13:22 -0700 Subject: change use back to maintain --- SCons/Environment.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index f06fda1..1b00e32 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -635,7 +635,7 @@ until after the Builder object is actually called. Direct &scons; -to use a derived-file cache in +to maintain a derived-file cache in cache_dir. The derived files in the cache will be shared among all the builds specifying the same -- cgit v0.12 From 39f1d3b19cc5724b768577fb2459deb139e0a8dc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 10:49:26 -0600 Subject: Update manpage Extending section [ci skip] Extending SCons: this is mainly syntax: adding/adjusting markup, reformatting code examples, adding the word "Example:" in a few places, moving a paragraph outside a list since it applies to the whole list, not to the last item of the list. A list is reformatted to a for a shorter layout. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 276 ++++++++++++++++++++++-------------------------------- 1 file changed, 114 insertions(+), 162 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..72f8667 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -4005,7 +4005,7 @@ int main(int argc, char **argv) { return ret env = Environment() -conf = Configure(env, custom_tests = {'CheckQt': CheckQt}) +conf = Configure(env, custom_tests={'CheckQt': CheckQt}) if not conf.CheckQt('/usr/lib/qt'): print('We really need qt!') Exit(1) @@ -4989,7 +4989,7 @@ or directory target. MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) env = Environment() -env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) +env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder}) env.MakeDirectory('new_directory', []) @@ -5025,7 +5025,7 @@ or directories (or both) as sources. CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) env = Environment() -env.Append(BUILDERS = {'Collect':CollectBuilder}) +env.Append(BUILDERS={'Collect': CollectBuilder}) env.Collect('archive', ['directory_name', 'file_name']) @@ -5076,14 +5076,14 @@ b = Builder("my_build < $TARGET > $SOURCE", emitter = [e, e2]) # Calling an emitter function through a &consvar;. -env = Environment(MY_EMITTER = e) +env = Environment(MY_EMITTER=e) b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$MY_EMITTER') + emitter='$MY_EMITTER') # Calling a list of emitter functions through a &consvar;. -env = Environment(EMITTER_LIST = [e, e2]) +env = Environment(EMITTER_LIST=[e, e2]) b = Builder("my_build < $TARGET > $SOURCE", - emitter = '$EMITTER_LIST') + emitter='$EMITTER_LIST') # Associating multiple emitters with different file # suffixes using a dictionary. @@ -5092,8 +5092,8 @@ def e_suf1(target, source, env): 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}) + emitter={'.suf1' : e_suf1, + '.suf2' : e_suf2}) @@ -5227,7 +5227,7 @@ and b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, source_ext_match = None) -env = Environment(BUILDERS = {'MyBuild':b}) +env = Environment(BUILDERS={'MyBuild':b}) env.MyBuild('foo.out', ['foo.in', 'foo.extra']) @@ -5247,8 +5247,8 @@ used to call the Builder for the target file.) b = Builder(action="build < $SOURCE > $TARGET") -env = Environment(BUILDERS = {'MyBuild' : b}) -env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') +env = Environment(BUILDERS={'MyBuild' : b}) +env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy') @@ -5300,7 +5300,7 @@ targets and source. b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", chdir=1) -env = Environment(BUILDERS = {'MyBuild' : b}) +env = Environment(BUILDERS={'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') @@ -5483,19 +5483,19 @@ or return a non-zero exit status to indicate an unsuccessful build. -def build_it(target = None, source = None, env = None): +def build_it(target=None, source=None, env=None): # build the target from the source return 0 a = Action(build_it) -If the action argument is not one of the above, -None is returned. +If the action argument is not one of the above, +None is returned. The second argument to &f-Action; is optional and is used to define the output @@ -5510,13 +5510,14 @@ The argument must be either a Python function or a string. it's a function that returns a string to be printed to describe the action being executed. The function may also be specified by the -strfunction= +strfunction keyword argument. Like a function to build a file, -this function must accept three keyword arguments: +the strfunction function +must accept three keyword arguments: - source - + source - a Node object representing the source file. target - a Node object representing the target file. @@ -5531,8 +5532,8 @@ arguments may be lists of Node objects if there is more than one target file or source file. In the second case, you provide the string itself. -The string may also be specified by the -cmdstr= +This string may also be specified using the +cmdstr keyword argument. The string typically contains variables, notably $TARGET(S) and $SOURCE(S), @@ -5566,8 +5567,8 @@ l = Action(build_it, '$STRINGIT') may either be a &consvar; or a list of &consvars; whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. -The variables may also be specified by a -varlist= +The variables may also be specified using the +varlist keyword parameter; if both are present, they are combined. This is necessary whenever you want a target to be rebuilt @@ -5580,7 +5581,8 @@ the value of a &consvar; when generating the command line. def build_it(target, source, env): # build the target from the 'XXX' construction variable - open(target[0], 'w').write(env['XXX']) + with open(target[0], 'w') as f: + f.write(env['XXX']) return 0 # Use positional arguments. @@ -5638,7 +5640,7 @@ expansions like and ${SOURCE.file} to use just the filename portion of the -targets and source. +targets and source. Example: a = Action("build < ${SOURCE.file} > ${TARGET.file}", @@ -5661,7 +5663,7 @@ to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, -consider that the action always suceeds: +consider that the action always suceeds. Example: def always_succeed(s): @@ -5696,9 +5698,8 @@ Command lines will typically want to use the &cv-CHANGED_SOURCES; &consvar; (and possibly &cv-CHANGED_TARGETS; as well) to only pass to the command line those sources that -have actually changed since their targets were built. - -Example: +have actually changed since their targets were built. +Example: a = Action('build $CHANGED_SOURCES', batch_key=True) @@ -5829,12 +5830,17 @@ external commands: -env = Environment(TMPBUILD = '/tmp/builddir') -env.Command('foo.out', 'foo.in', - [Mkdir('$TMPBUILD'), - Copy('$TMPBUILD', '${SOURCE.dir}'), - "cd $TMPBUILD && make", - Delete('$TMPBUILD')]) +env = Environment(TMPBUILD='/tmp/builddir') +env.Command( + target='foo.out', + source='foo.in', + action=[ + Mkdir('$TMPBUILD'), + Copy('$TMPBUILD', '${SOURCE.dir}'), + "cd $TMPBUILD && make", + Delete('$TMPBUILD'), + ], +) @@ -5977,7 +5983,7 @@ Examples: Execute(Touch('file_to_be_touched')) -env.Command('marker', 'input_file', +env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')]) @@ -5994,7 +6000,7 @@ env.Command('marker', 'input_file', performs &consvar; substitution on the string that makes up the command line of the builder. &Consvars; to be interpolated are indicated in the -string with a leading +string with a leading $, to distinguish them from plain text which is not to be substituted. Besides regular &consvars;, scons provides the following @@ -6110,117 +6116,58 @@ have the following modifiers appended within the enclosing curly braces to access properties of the interpolated string: - - - base - -The base path of the file name, -including the directory path -but excluding any suffix. - - - - - dir - -The name of the directory in which the file exists. - - - - - file - -The file name, -minus any directory portion. - - - - - filebase - -Like file -but minus its suffix.. - - - - - suffix - -Just the file suffix. - - - - - abspath - -The absolute path name of the file. - - - - - posix - -The path with directories separated by forward slashes -(/). -Sometimes necessary on Windows systems -when a path references a file on other (POSIX) systems. - - - - - windows - -The path with directories separated by backslashes. -(\\). -Sometimes necessary on POSIX-style systems -when a path references a file on other (Windows) systems. -win32 is a (deprecated) synonym for -windows. - - - - - srcpath - -The directory and file name to the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory and filename unchanged. - - - - - srcdir - -The directory containing the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory part of the filename. - - - - - rsrcpath - -The directory and file name to the source file linked to this file through -VariantDir(). -If the file does not exist locally but exists in a Repository, -the path in the Repository is returned. -If this file isn't linked, it just returns the -directory and filename unchanged. - - - - - rsrcdir - -The Repository directory containing the source file linked to this file through -VariantDir(). -If this file isn't linked, -it just returns the directory part of the filename. - - - + + base - + The base path of the file name, + including the directory path + but excluding any suffix. + + dir - The name of the directory in which the file exists. + file - The file name, minus any directory portion. + filebase - Like file but minus its suffix. + suffix - Just the file suffix. + abspath - The absolute path name of the file. + posix - + The path with directories separated by forward slashes + (/). + Sometimes necessary on Windows systems + when a path references a file on other (POSIX) systems. + + windows - + The path with directories separated by backslashes + (\\). + Sometimes necessary on POSIX-style systems + when a path references a file on other (Windows) systems. + win32 is a (deprecated) synonym for + windows. + + srcpath - + The directory and file name to the source file linked to this file through + &f-VariantDir;(). + If this file isn't linked, + it just returns the directory and filename unchanged. + + srcdir - + The directory containing the source file linked to this file through + &f-VariantDir;(). + If this file isn't linked, + it just returns the directory part of the filename. + + rsrcpath - + The directory and file name to the source file linked to this file through + &f-VariantDir;(). + If the file does not exist locally but exists in a Repository, + the path in the Repository is returned. + If this file isn't linked, it just returns the + directory and filename unchanged. + + rsrcdir - + The Repository directory containing the source file linked to this file through + &VariantDir;(). + If this file isn't linked, + it just returns the directory part of the filename. + + For example, the specified target will expand as follows for the corresponding modifiers: @@ -6701,19 +6648,19 @@ issues waiting to trap the unwary. .C file suffix &scons; handles the upper-case -.C +.C file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, &scons; treats a file with a -.C +.C suffix as a C++ source file. On a case-insensitive system such as Windows, &scons; treats a file with a -.C +.C suffix as a C source file. @@ -6721,21 +6668,21 @@ suffix as a C source file. .F file suffix &scons; handles the upper-case -.F +.F file suffix differently, depending on the capabilities of the underlying system. On a case-sensitive system such as Linux or UNIX, &scons; treats a file with a -.F +.F suffix as a Fortran source file that is to be first run through the standard C preprocessor. On a case-insensitive system such as Windows, &scons; treats a file with a -.F +.F suffix as a Fortran source file that should not be run through the C preprocessor. @@ -6782,11 +6729,11 @@ to run &scons;. -Windows: scons.bat file +Windows: <filename>scons.bat</filename> file On Windows systems, &scons; is executed via a wrapper -scons.bat +scons.bat file. This has (at least) two ramifications: @@ -6806,23 +6753,26 @@ as an &scons; command issued at the command-line prompt. You can work around this either by executing -scons.bat +scons.bat from the Cygwin command line, or by creating a wrapper shell script named -scons. +scons. MinGW -The MinGW bin directory must be in your PATH environment variable or the -PATH variable under the ENV &consvar; for &scons; +The MinGW bin +directory must be in your PATH +environment variable or the +ENV['PATH'] &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows Python interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin -directories in the PATH variable. If you have both MSVC and MinGW +directories in the PATH variable. +If you have both MSVC and MinGW installed and you want to use MinGW instead of MSVC, then you must explicitly tell &scons; to use MinGW by passing tools=['mingw'] @@ -6836,7 +6786,9 @@ over the MinGW tools. EXAMPLES To help you get started using &scons;, -this section contains a brief overview of some common tasks. +this section contains a brief overview of some common tasks. +See the &SCons; User Guide for many more examples. + -- cgit v0.12 From 5608c66d57570ed462e1dc7a263b34d6b1917871 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 10:58:28 -0600 Subject: Update manpage Examples section [ci skip] Examples: mainly syntax: adding/adjusting markup, reformatting code examples, etc. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 218 +++++++++++++++++++++++++++++------------------------- 1 file changed, 119 insertions(+), 99 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..1b400f9 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -6836,7 +6836,9 @@ over the MinGW tools. EXAMPLES To help you get started using &scons;, -this section contains a brief overview of some common tasks. +this section contains a brief overview of some common tasks. +See the &SCons; User Guide for many more examples. + @@ -6844,13 +6846,14 @@ this section contains a brief overview of some common tasks. env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') Note: Build the file by specifying the target as an argument -("scons foo" or "scons foo.exe"). -or by specifying a dot ("scons ."). +(scons foo or scons foo.exe) +or by specifying the current directory as the target +(scons .). @@ -6859,7 +6862,7 @@ or by specifying a dot ("scons ."). env = Environment() -env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) +env.Program(target='foo', source=Split('f1.c f2.c f3.c')) @@ -6868,8 +6871,8 @@ env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) Setting a Compilation Flag -env = Environment(CCFLAGS = '-g') -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CCFLAGS='-g') +env.Program(target='foo', source='foo.c') @@ -6879,12 +6882,14 @@ env.Program(target = 'foo', source = 'foo.c') Note: You do not -need to set CCFLAGS to specify -I options by hand. -&scons; will construct the right options from CPPPATH. +need to set CCFLAGS to specify + options by hand. +&scons; will construct the right +options from the contents of CPPPATH. -env = Environment(CPPPATH = ['.']) -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CPPPATH=['.']) +env.Program(target='foo', source='foo.c') @@ -6893,8 +6898,8 @@ env.Program(target = 'foo', source = 'foo.c') Search Multiple Directories For .h Files -env = Environment(CPPPATH = ['include1', 'include2']) -env.Program(target = 'foo', source = 'foo.c') +env = Environment(CPPPATH=['include1', 'include2']) +env.Program(target='foo', source='foo.c') @@ -6904,8 +6909,8 @@ env.Program(target = 'foo', source = 'foo.c') env = Environment() -env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) -env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) +env.StaticLibrary(target='foo', source=Split('l1.c l2.c')) +env.StaticLibrary(target='bar', source=['l3.c', 'l4.c']) @@ -6915,8 +6920,8 @@ env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) env = Environment() -env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) -env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) +env.SharedLibrary(target='foo', source=['l5.c', 'l6.c']) +env.SharedLibrary(target='bar', source=Split('l7.c l8.c')) @@ -6925,9 +6930,9 @@ env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) Linking a Local Library Into a Program -env = Environment(LIBS = 'mylib', LIBPATH = ['.']) -env.Library(target = 'mylib', source = Split('l1.c l2.c')) -env.Program(target = 'prog', source = ['p1.c', 'p2.c']) +env = Environment(LIBS='mylib', LIBPATH=['.']) +env.Library(target='mylib', source=Split('l1.c l2.c')) +env.Program(target='prog', source=['p1.c', 'p2.c']) @@ -6940,23 +6945,24 @@ you can leave off the target file suffix, and &scons; will add it automatically. -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') -env = Environment(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') +bld = Builder( + action='pdftex < $SOURCES > $TARGET', + suffix='.pdf', + src_suffix='.tex' +) +env = Environment(BUILDERS={'PDFBuilder': bld}) +env.PDFBuilder(target='foo.pdf', source='foo.tex') # The following creates "bar.pdf" from "bar.tex" -env.PDFBuilder(target = 'bar', source = 'bar') +env.PDFBuilder(target='bar', source='bar') -Note also that the above initialization -overwrites the default Builder objects, -so the Environment created above -can not be used call Builders like -env.Program, -env.Object, -env.StaticLibrary etc. +Note that the above initialization +replaces the default dictionary of Builders, +so this &consenv; can not be used call Builders like +&b-link-Program;, &b-link-Object;, &b-link-StaticLibrary; etc. +See the next example for an alternative. + @@ -6964,13 +6970,15 @@ can not be used call Builders like Adding Your Own Builder Object to an Environment -bld = Builder(action = 'pdftex < $SOURCES > $TARGET' - suffix = '.pdf', - src_suffix = '.tex') +bld = Builder( + action='pdftex < $SOURCES > $TARGET' + suffix='.pdf', + src_suffix='.tex' +) env = Environment() -env.Append(BUILDERS = {'PDFBuilder' : bld}) -env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex') -env.Program(target = 'bar', source = 'bar.c') +env.Append(BUILDERS={'PDFBuilder': bld}) +env.PDFBuilder(target='foo.pdf', source='foo.tex') +env.Program(target='bar', source='bar.c') You also can use other Pythonic techniques to add @@ -6986,13 +6994,12 @@ env['BUILDERS]['PDFBuilder'] = bld Defining Your Own Scanner Object -The following example shows adding an extremely simple scanner (the -kfile_scan() -function) +The following example shows adding an extremely simple scanner +(kfile_scan) that doesn't use a search path at all and simply returns the file names present on any -include +include lines in the scanned file. This would implicitly assume that all included files live in the top-level directory: @@ -7007,10 +7014,12 @@ def kfile_scan(node, env, path, arg): includes = include_re.findall(contents) return env.File(includes) -kscan = Scanner(name = 'kfile', - function = kfile_scan, - argument = None, - skeys = ['.k']) +kscan = Scanner( + name='kfile', + function=kfile_scan, + argument=None, + skeys=['.k'], +) scanners = DefaultEnvironment()['SCANNERS'] scanners.append(kscan) @@ -7025,29 +7034,28 @@ bar_in.target_scanner = kscan It is important to note that you have to return a list of File nodes from the scan function, simple -strings for the file names won't do. As in the examples we are showing here, -you can use the -File() -function of your current Environment in order to create nodes on the fly from +strings for the file names won't do. As in the examples shown here, +you can use the &f-link-env-File; +function of your current &consenv; in order to create nodes on the fly from a sequence of file names with relative paths. Here is a similar but more complete example that adds a scanner which searches a path of directories (specified as the -MYPATH -&consvar;) +MYPATH &consvar;) for files that actually exist: import re import os + include_re = re.compile(r'^include\s+(\S+)$', re.M) def my_scan(node, env, path, arg): contents = node.get_text_contents() includes = include_re.findall(contents) - if includes == []: + if not includes: return [] results = [] for inc in includes: @@ -7058,12 +7066,13 @@ def my_scan(node, env, path, arg): break return env.File(results) -scanner = Scanner(name='myscanner', - function=my_scan, - argument=None, - skeys=['.x'], - path_function=FindPathDirs('MYPATH') - ) +scanner = Scanner( + name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=FindPathDirs('MYPATH'), +) scanners = DefaultEnvironment()['SCANNERS'] scanners.append(scanner) @@ -7073,12 +7082,12 @@ env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') The -FindPathDirs() +&f-link-FindPathDirs; function used in the previous example returns a function (actually a callable Python object) that will return a list of directories specified in the -$MYPATH +MYPATH &consvar;. It lets &scons; detect the file incs/foo.inc, even if @@ -7088,7 +7097,7 @@ contains the line only. If you need to customize how the search path is derived, you would provide your own -path_function +path_function argument when creating the Scanner object, as follows: @@ -7102,12 +7111,14 @@ def pf(env, dir, target, source, arg): results.append(top_dir + os.sep + p) return results -scanner = Scanner(name='myscanner', - function=my_scan, - argument=None, - skeys=['.x'], - path_function=pf - ) + +scanner = Scanner( + name='myscanner', + function=my_scan, + argument=None, + skeys=['.x'], + path_function=pf +) @@ -7116,14 +7127,13 @@ scanner = Scanner(name='myscanner', Creating a Hierarchical Build Notice that the file names specified in a subdirectory's -SConscript -file are relative to that subdirectory. +SConscript file are relative to that subdirectory. SConstruct: env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') SConscript('sub/SConscript') @@ -7133,7 +7143,7 @@ SConscript('sub/SConscript') env = Environment() # Builds sub/foo from sub/foo.c -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') SConscript('dir/SConscript') @@ -7143,7 +7153,7 @@ SConscript('dir/SConscript') env = Environment() # Builds sub/dir/foo from sub/dir/foo.c -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') @@ -7151,14 +7161,15 @@ env.Program(target = 'foo', source = 'foo.c') Sharing Variables Between SConscript Files -You must explicitly call &Export; and &Import; for variables that +You must explicitly call &f-link-Export; and &f-link-Import; +for variables that you want to share between SConscript files. SConstruct: env = Environment() -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') Export("env") SConscript('subdirectory/SConscript') @@ -7168,7 +7179,7 @@ SConscript('subdirectory/SConscript') Import("env") -env.Program(target = 'foo', source = 'foo.c') +env.Program(target='foo', source='foo.c') @@ -7176,8 +7187,8 @@ env.Program(target = 'foo', source = 'foo.c') Building Multiple Variants From the Same Source -Use the variant_dir keyword argument to -the &SConscriptFunc; function to establish +Use the variant_dir keyword argument to +the &f-link-SConscript; function to establish one or more separate variant build directory trees for a given source directory: @@ -7197,12 +7208,12 @@ SConscript('src/SConscript', variant_dir='bar') Import("cppdefines") -env = Environment(CPPDEFINES = cppdefines) -env.Program(target = 'src', source = 'src.c') +env = Environment(CPPDEFINES=cppdefines) +env.Program(target='src', source='src.c') -Note the use of the &Export; method -to set the "cppdefines" variable to a different +Note the use of the &f-link-Export; method +to set the cppdefines variable to a different value each time we call the &SConscriptFunc; function. @@ -7249,8 +7260,9 @@ top-level directory, so they don't turn into used in Main/SConscript Specifying only 'a' and 'b' for the library names -allows &scons; to append the appropriate library -prefix and suffix for the current platform +allows &scons; to attach the appropriate library +prefix and suffix for the current platform in +creating the library filename (for example, liba.a on POSIX systems, a.lib on Windows). @@ -7264,7 +7276,7 @@ line or in the file custom.py. vars = Variables('custom.py') -vars.Add('CC', help='The C compiler.') +vars.Add('CC', 'The C compiler.') env = Environment(variables=vars) Help(vars.GenerateHelpText(env)) @@ -7296,14 +7308,19 @@ CC: The C compiler. Using Microsoft Visual C++ precompiled headers -Since windows.h includes everything and the kitchen sink, it can take quite +Since windows.h includes everything +and the kitchen sink, it can take quite some time to compile it over and over again for a bunch of object files, so Microsoft provides a mechanism to compile a set of headers once and then include the previously compiled headers in any object file. This -technology is called precompiled headers. The general recipe is to create a -file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and -then include every header you want to precompile in "StdAfx.h", and finally -include "StdAfx.h" as the first header in all the source files you are +technology is called precompiled headers (PCH). +The general recipe is to create a +file named StdAfx.cpp +that includes a single header named StdAfx.h, +and then include every header you want to precompile in +StdAfx.h, +and finally include "StdAfx.h +as the first header in all the source files you are compiling to object files. For example: StdAfx.h: @@ -7344,9 +7361,11 @@ env['PCH'] = env.PCH('StdAfx.cpp')[0] env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -For more information see the document for the PCH builder, and the PCH and -PCHSTOP &consvars;. To learn about the details of precompiled -headers consult the MSDN documentation for /Yc, /Yu, and /Yp. +For more information see the documentation for the &b-link-PCH; builder, +and the &cv-link-PCH; and &cv-link-PCHSTOP; &consvars;. +To learn about the details of precompiled +headers consult the MSDN documentation for +, , and . @@ -7355,9 +7374,9 @@ headers consult the MSDN documentation for /Yc, /Yu, and /Yp. Since including debugging information in programs and shared libraries can cause their size to increase significantly, Microsoft provides a mechanism -for including the debugging information in an external file called a PDB -file. &scons; supports PDB files through the PDB construction -variable. +for including the debugging information in an external file called a +PDB file. +&scons; supports PDB files through the &cv-PDB; &consvar;. SConstruct: @@ -7367,7 +7386,8 @@ env['PDB'] = 'MyApp.pdb' env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) -For more information see the document for the PDB &consvar;. +For more information see the documentation for the +&cv-link-PDB; &consvar;. @@ -7430,7 +7450,7 @@ Remove the cache file in case of problems with this. &scons; will ignore failures reading or writing the file and will silently revert to non-cached behavior in such cases. -Since &scons; 3.1 (experimental). +Available since &scons; 3.1 (experimental). -- cgit v0.12 From e1b67497b7af73f39af4854c841fd6e84f1bf237 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 11:40:35 -0600 Subject: [PR #3676] fix doc typo detected by sider [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 72f8667..6f526c0 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -5663,12 +5663,13 @@ to specify that an Action object's return value should be ignored under special conditions and SCons should, therefore, -consider that the action always suceeds. Example: +consider that the action always succeeds. Example: def always_succeed(s): # Always return 0, which indicates success. return 0 + a = Action("build < ${SOURCE.file} > ${TARGET.file}", exitstatfunc=always_succeed) -- cgit v0.12 From f503caeef8048b5b601338d57eda5048b7edaf4f Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 11:52:10 -0600 Subject: Update manpage Configuration File section [ci skip] CONFIGURATION FILE REFERENCE: markup added/updated, examples reformatted. A chunk of text followed the included "GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS" which describes how to access consvars, this was moved before the inclusion for better flow. A bit was added to the final paragraph before that inclusion to remind that actual consvars are based on which tools were actually able to initialize. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 276 +++++++++++++++++++++++++++++------------------------- 1 file changed, 147 insertions(+), 129 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..c1fa045 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2082,21 +2082,20 @@ repositories are searched in the order specified. Construction Environments -A &ConsEnv; is the basic means by which the SConscript +A &ConsEnv; is the basic means by which SConscript files communicate build information to &scons;. A new &consenv; is created using the -&Environment; +&f-link-Environment; function: env = Environment() -Variables, called -&ConsVars; -may be set in a &consenv; -either by specifying them as keywords when the object is created +&Consenv; attributes called +&ConsVars; may be set +either by specifying them as keyword arguments when the object is created or by assigning them a value after the object is created: @@ -2104,6 +2103,27 @@ env = Environment(FOO='foo') env['BAR'] = 'bar' + + + +An existing &consenv; can be duplicated by calling the &f-link-env-Clone; +method. Without arguments, it will be a copy with the same +settings. Otherwise, &f-env-Clone; takes the same arguments as &f-Environment;, +and uses the arguments to create a modified copy. + + + +&SCons; also provides a special &consenv; called the +&DefEnv;. +The &defenv; is used only for global functions, that is, +construction activities called without the context of a regular &consenv;. +See &f-link-DefaultEnvironment; for more information. + + As a convenience, &consvars; may also be set or modified by the parse_flags @@ -2113,7 +2133,7 @@ method (described below) to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read from a control file) -or if the flags are distributed to a number of &consvars;. +or if the flags need to be distributed to a number of &consvars;. env = Environment(parse_flags='-Iinclude -DEBUG -lm') @@ -2134,15 +2154,15 @@ are distributed to &consvars;. initialized with a set of builder methods and &consvars; that are appropriate for the current platform. -An optional platform keyword argument may be -used to specify that an environment should +An optional platform keyword argument may be +used to specify that the &consenv; should be initialized for a different platform: -env = Environment(platform = 'cygwin') -env = Environment(platform = 'os2') -env = Environment(platform = 'posix') -env = Environment(platform = 'win32') +env = Environment(platform='cygwin') +env = Environment(platform='os2') +env = Environment(platform='posix') +env = Environment(platform='win32') Specifying a platform initializes the appropriate @@ -2397,9 +2417,9 @@ env.SomeTool(targets, sources) Builder Methods You tell &scons; what to build -by calling Builders, functions which know to take a -particular action when given files of a particular type -to produce a particular result type. &scons; +by calling Builders, functions which know to take a +particular action to produce a particular result type +when given source files of a particular type. &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 @@ -2430,14 +2450,14 @@ keyword arguments, described below. Because long lists of file names can lead to a lot of quoting, &scons; -supplies a &Split; +supplies a &f-link-Split; global function and a same-named environment method -that split a single string -into a list, separated on -strings of white-space characters. -(These are similar to the Python string split -method, but work even if the input isn't a string.) +that splits a single string +into a list, using +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.) The target and source arguments to a builder method @@ -2491,7 +2511,7 @@ to a relative or absolute path first. Target and source pathnames can be absolute, relative, or top-relative. Relative pathnames are searched considering the -directory of the SConscript +directory of the SConscript file currently being processed as the "current directory". @@ -2550,14 +2570,14 @@ env.Program('bar.c') As a convenience, a -srcdir +srcdir keyword argument may be specified when calling a Builder. When specified, all source file strings that are not absolute paths or top-relative paths will be interpreted relative to the specified -srcdir. +srcdir. The following example will build the build/prog (or @@ -2573,7 +2593,7 @@ and env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') -It is possible to override (replace or add) +It is possible to override (replace or add) &consvars; when calling a builder method by passing them as keyword arguments. These overrides @@ -2593,13 +2613,14 @@ env.SharedLibrary('word', 'word.cpp', LIBSUFFIXES=['.ocx']) -Note that both the $SHLIBSUFFIX and $LIBSUFFIXES -variables must be set if you want SCons to search automatically +Note that both the &cv-link-SHLIBSUFFIX; +and &cv-link-LIBSUFFIXES; +variables must be set if you want &scons; to search automatically for dependencies on the non-standard library names; -see the descriptions of these variables, below, for more information. +see the descriptions below of these variables for more information. It is also possible to use the -parse_flags +parse_flags keyword argument in an override, to merge command-line style arguments into the appropriate &consvars; @@ -2645,15 +2666,14 @@ from SCons.Script import * All builder methods return a list-like object containing Nodes that will be built. -A -Node +A Node is an internal SCons object which represents build targets or sources. The returned Node-list object can be passed to other builder methods as source(s) -or passed to any SCons function or method +or passed to any &SCons; function or method where a filename would normally be accepted. For example, if it were necessary to add a specific preprocessor define @@ -2673,7 +2693,7 @@ when calling the &Program; builder method. Builder calls will automatically "flatten" lists passed as source and target, so they are free to contain elements which are themselves lists, such as -bar_obj_list +bar_obj_list returned by the &StaticObject; call above. If you need to manipulate a list of lists returned by builders directly in Python code, @@ -2687,7 +2707,7 @@ for obj in objects: print(str(obj)) -Or you can use the &Flatten; +Or you can use the &f-link-Flatten; function supplied by &scons; to create a list containing just the Nodes, which may be more convenient: @@ -2700,7 +2720,7 @@ for obj in objects: print(str(obj)) -SCons builder calls return +&SCons; builder calls return a list-like object, not an actual Python list, so it is not appropriate to use the Python add operator (+ or +=) @@ -2747,18 +2767,18 @@ to get at the Node that actually represents the object file. Builder calls support a -chdir +chdir keyword argument that specifies that the Builder's action(s) should be executed after changing directory. If the -chdir +chdir argument is a string or a directory Node, scons will change to the specified directory. If the -chdir +chdir is not a string or Node and is non-zero, then scons will change to the @@ -2779,14 +2799,14 @@ env.Command('sub/dir/foo.out', 'sub/dir/foo.in', chdir=1) -Note that scons will +Note that &SCons; will not automatically modify its expansion of &consvars; like -$TARGET +$TARGET and -$SOURCE +$SOURCE when using the chdir keyword argument--that is, the expanded file names @@ -2798,9 +2818,9 @@ If you use the chdir keyword argument, you will typically need to supply a different command line using expansions like -${TARGET.file} +${TARGET.file} and -${SOURCE.file} +${SOURCE.file} to use just the filename portion of the targets and source. @@ -2837,7 +2857,7 @@ not all builders may be available to that targets of builder methods automatically depend on their sources. An explicit dependency can be specified using the -Depends +&f-link-env-Depends; method of a &consenv; (see below). In addition, @@ -2849,18 +2869,18 @@ By default, SCons can C source files, C++ source files, Fortran source files with -.F +.F (POSIX systems only), -.fpp, +.fpp, or -.FPP +.FPP file extensions, and assembly language files with -.S +.S (POSIX systems only), -.spp, +.spp, or -.SPP +.SPP files extensions for C preprocessor dependencies. SCons also has default support @@ -2869,19 +2889,16 @@ You can also write your own Scanners to add support for additional source file types. These can be added to the default Scanner object used by the -Object(), -StaticObject(), -and -SharedObject() +&b-link-Object;, &b-link-StaticObject; and &b-link-SharedObject; Builders by adding them to the -SourceFileScanner +SourceFileScanner object. See for more information about defining your own Scanner objects and using the -SourceFileScanner +SourceFileScanner object. @@ -2899,19 +2916,19 @@ manipulate the build configuration. and global function with the same name both exist for convenience. In the following list, the global function -is documented like: +is documented in this style: -Function(arguments) +Function(arguments, [optional arguments]) and the &consenv; method looks like: -env.Function(arguments) +env.Function(arguments, [optional arguments]) -If you can call the function in both ways, +If the function can be called both ways, then both forms are listed. The global function and same-named @@ -2922,26 +2939,25 @@ First, many of the &consenv; methods affect only that global effect. Second, where appropriate, calling the functionality through a &consenv; will substitute &consvars; into -any supplied strings, while the global function doesn't have the +any supplied string arguments, while the global function doesn't have the context of a &consenv; to pick variables from, so it cannot perform the substitution. For example: -env = Environment(FOO = 'foo') Default('$FOO') + +env = Environment(FOO='foo') env.Default('$FOO') In the above example, -the first call to the global -Default() -function will actually add a target named +the call to the global &f-Default; +function will add a target named $FOO to the list of default targets, -while the second call to the -env.Default() -&consenv; method +while the call to the +&f-env-Default; &consenv; method will expand the value and add a target named foo @@ -2959,7 +2975,7 @@ from SCons.Script import * &Consenv; methods -and global functions supported by +and global functions provided by &scons; include: @@ -3009,19 +3025,18 @@ and value elements of the tuple can be accessed by -subscripting for element +subscripting for elements [0] and [1] -of the tuple, respectively. - -Example: +of the tuple, or, more readably, by using tuple unpacking. +Example: print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]) print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]) -third_tuple = ARGLIST[2] -print("third keyword, value =", third_tuple[0], third_tuple[1]) +key, value = ARGLIST[2] +print("third keyword, value =", key, value) for key, value in ARGLIST: # process key and value @@ -3046,7 +3061,7 @@ dictionary. if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') + env = Environment(CCFLAGS='-g') else: env = Environment() @@ -3061,12 +3076,13 @@ else: has been asked to build. The contents will be either those targets listed on the command line, or, if none, those targets set -via calls to the &Default; function or method. +via calls to the &f-link-Default; function. It does not -contain any not-specified dependent targets that &scons; +contain any dependent targets that &scons; selects for building as a result of making the sure the -specified targets are up to date. +specified targets are up to date, if those targets +did not appear on the command line. The list is empty if neither command line targets or &Default; calls are present. @@ -3074,16 +3090,15 @@ command line targets or &Default; calls are present. The elements of this list may be strings or nodes, so you should run the list through the Python -str +str function to make sure any Node path names are converted to strings. Because this list may be taken from the list of targets specified using the -&Default; function or method, +&Default; function, the contents of the list may change -on each successive call to -Default(). +on each successive call to &Default;. See the &DEFAULT_TARGETS; list, below, for additional information. @@ -3128,13 +3143,13 @@ if 'special/program' in COMMAND_LINE_TARGETS: A list of the target nodes that have been specified using the -Default() -function or method. If there are no command line +&f-link-Default; +function. If there are no command line targets, this list will have the same contents as &BUILD_TARGETS;. Since the elements of the list are nodes, you need to call the Python -str +str function on them to get the path name for each Node. Example: @@ -3146,10 +3161,9 @@ if 'foo' in [str(t) for t in DEFAULT_TARGETS]: The contents of the -DEFAULT_TARGETS +&DEFAULT_TARGETS; list change on on each successive call to the -Default() -function: +&Default; function: print([str(t) for t in DEFAULT_TARGETS]) # originally [] @@ -3162,10 +3176,9 @@ print([str(t) for t in DEFAULT_TARGETS]) # back to [] Consequently, be sure to use -DEFAULT_TARGETS +&DEFAULT_TARGETS; only after you've made all of your -Default() -calls, +&Default;() calls, or else simply be careful of the order of these statements in your SConscript files so that you don't look for a specific @@ -3207,15 +3220,51 @@ from SCons.Script import * A &consenv; has an associated dictionary of &consvars; that are used by built-in or user-supplied build rules. -&Consvars; must follow the same rules for +&Consvar; naming must follow the same rules as for Python identifiers: the initial character must be an underscore or letter, followed by any number of underscores, letters, or digits. +A &consenv; is not a Python dictionary, +but it can be indexed like one to access a +&consvar;: + + +env["CC"] = "cc" + + +&Consvars; can also be retrieved and set +by using the &f-link-Dictionary; +method of the &consenv; to create an actual +dictionary: + + +cvars = env.Dictionary() +cvars["CC"] = "cc" + + +&Consvars; can also be passed to the &consenv; +constructor: + + +env = Environment(CC="cc") + + +or when copying a &consenv; using the +&f-link-Clone; method: + + +env2 = env.Clone(CC="cl.exe") + + A number of useful &consvars; are automatically defined by scons for each supported platform, and additional &consvars; -can be defined by the user. The following is a list of the automatically -defined &consvars;: +can be defined by the user. The following is a list of the possible +automatically defined &consvars;. The actual list available +at execution time will not include all of these, as the ones +detected as not being useful (wrong platform, necessary +external command or files not installed, etc.) will not be set up. +: @@ -3237,37 +3286,6 @@ defined &consvars;: - -&Consvars; can be retrieved and set using the -Dictionary -method of the &consenv;: - - -cvars = env.Dictionary() -cvars["CC"] = "cc" - - -or using the key lookup operator [] -directly on the &consenv;: - - -env["CC"] = "cc" - - -&Consvars; can also be passed to the &consenv; -constructor: - - -env = Environment(CC="cc") - - -or when copying a &consenv; using the -&f-link-Clone; method: - - -env2 = env.Clone(CC="cl.exe") - - @@ -3303,9 +3321,9 @@ discovered while running tests. The context includes a local &consenv; which is used when running the tests and which can be updated with the check results. Only one context may be active -at a time (since 4.0, &scons; will raise an exception +at a time (since 4.0, &scons; will raise an exception on an attempt to create a new context when there is -an active context), but a new context can be created +an active context), but a new context can be created after the active one is completed. For the global function form, the required env describes the initial values for the context's local &consenv;; -- cgit v0.12 From 502fa36ca74899cf200c455f844d3cc9721fc585 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 12:26:18 -0600 Subject: Update manpage Options section [ci skip] OPTIONS: add/change markup. A few comments modified on CacheDir usage, and on Help. Dropped a reference to SCCS/RCS retrieval. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 129 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 58 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index b58e14f..f9372bb 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -266,11 +266,6 @@ supports the ability to define new scanners for unknown input file types. &scons; -knows how to fetch files automatically from -SCCS or RCS subdirectories -using SCCS, RCS or BitKeeper. - -&scons; is normally executed in a top-level directory containing an &SConstruct; file. When &scons; is invoked, @@ -295,7 +290,7 @@ the build in any way: if ARGUMENTS.get('debug', 0): - env = Environment(CCFLAGS = '-g') + env = Environment(CCFLAGS='-g') else: env = Environment() @@ -521,18 +516,17 @@ Will not remove any targets specified by the &NoClean; function. - -Print debug information about the &CacheDir; +Write debug information about derived-file caching to the specified file. If file -is -- -(a hyphen), +is a hyphen +(-), the debug information is printed to the standard output. The printed messages describe what signature-file names are being looked for in, retrieved from, or written to the -&CacheDir; directory tree. +derived-file cache specified by &f-link-CacheDir;. @@ -542,11 +536,13 @@ are being looked for in, retrieved from, or written to the -Disable the derived-file caching specified by -&CacheDir;. +Disable derived-file caching. &scons; will neither retrieve files from the cache -nor copy files to the cache. +nor copy files to the cache. This option can +be used to temporarily disable the cache without +modifying the build scripts. + @@ -556,9 +552,9 @@ nor copy files to the cache. -When using &CacheDir;, -populate a cache by copying any already-existing, up-to-date -derived files to the cache, +When using &f-link-CacheDir;, +populate a derived-file cache by copying any already-existing, +up-to-date derived files to the cache, in addition to files built by this invocation. This is useful to populate a new cache with all the current derived files, @@ -572,8 +568,9 @@ option. -Use the cache (if enabled) for reading, but do not not update the -cache with changed files. +Use the derived-file cache, if enabled, to retrieve files, +but do not not update the cache with any files actually +built during this invocation. @@ -581,13 +578,13 @@ cache with changed files. -When using &CacheDir; -and retrieving a derived file from the cache, +When using a derived-file cache +and retrieving a file from it, show the command -that would have been executed to build the file, -instead of the usual report, -"Retrieved `file' from cache." -This will produce consistent output for build logs, +that would have been executed to build the file. +Without this option, &scons; reports +"Retrieved `file' from cache.". +This allows producing consistent output for build logs, regardless of whether a target file was rebuilt or retrieved from the cache. @@ -722,7 +719,7 @@ each command, shows the absolute start and end times. This may be useful in debugging parallel builds. Implies the option. -Since &scons; 3.1. +Available since &scons; 3.1. @@ -739,7 +736,7 @@ This is not supported when SCons is executed with the Python or when the SCons modules have been compiled with optimization (that is, when executing from -*.pyo +*.pyo files). @@ -1054,12 +1051,20 @@ will read all of the specified files. -Print a local help message for this build, if one is defined in -the SConscript files, plus a line that describes the - -option for command-line option help. If no local help message -is defined, prints the standard help message about command-line -options. Exits after displaying the appropriate message. +Print a local help message for this project, +if one is defined in the SConscript files +(see the &f-link-Help; function), +plus a line that refers to the standard &SCons; help message. +If no local help message is defined, +prints the standard &SCons; help message +(as for the option) +plus help for any local options defined through &f-link-AddOption;. +Exits after displaying the appropriate message. + +Note that use of this option requires &SCons; to process +the SConscript files, so syntax errors may cause +the help message not to be displayed. + @@ -1069,8 +1074,8 @@ options. Exits after displaying the appropriate message. -Print the standard help message about command-line options and -exit. +Print the standard help message about &SCons; +command-line options and exit. @@ -1172,7 +1177,7 @@ underneath path. Starts SCons in interactive mode. The SConscript files are read once and a -scons>>> +scons>>> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt without having to re-read the SConscript files @@ -1182,7 +1187,7 @@ and re-initialize the dependency graph from scratch. - build[OPTIONS] [TARGETS] ... + build [OPTIONS] [TARGETS] ... Builds the specified TARGETS @@ -1229,7 +1234,7 @@ which only happens once at the beginning of interactive mode). - clean[OPTIONS] [TARGETS] ... + clean [OPTIONS] [TARGETS] ... Cleans the specified TARGETS @@ -1244,17 +1249,25 @@ This command is itself a synonym for - exit + exit Exits SCons interactive mode. You can also exit by terminating input -(CTRL+D on UNIX or Linux systems, -CTRL+Z on Windows systems). +( +Ctrl +D + +UNIX or Linux systems, +( +Ctrl +Z + +on Windows systems). - help[COMMAND] + help [COMMAND] Provides a help message about the commands available in SCons interactive mode. @@ -1269,13 +1282,13 @@ are synonyms. - shell[COMMANDLINE] + shell [COMMANDLINE] Executes the specified -COMMANDLINE +COMMANDLINE in a subshell. If no -COMMANDLINE +COMMANDLINE is specified, executes the interactive command interpreter specified in the @@ -1283,7 +1296,7 @@ specified in the environment variable (on UNIX and Linux systems) or the -COMSPEC +COMSPEC environment variable (on Windows systems). sh @@ -1294,7 +1307,7 @@ are synonyms. - version + version Prints SCons version information. @@ -1721,7 +1734,7 @@ specified alone, without any type, it behaves as if all had been specified. -Since &scons; 4.0. +Available since &scons; 4.0. @@ -1845,9 +1858,9 @@ specifies the type of warnings to be enabled or disabled: cache-version -Warnings about the cache directory not using -the latest configuration information -CacheDir(). +Warnings about the derived-file cache directory +specified by &f-link-CacheDir; not using +the latest configuration information. These warnings are enabled by default. @@ -1857,7 +1870,7 @@ These warnings are enabled by default. Warnings about errors trying to write a copy of a built file to a specified -CacheDir(). +derived-file cache specified by &f-link-CacheDir;. These warnings are disabled by default. @@ -1866,7 +1879,7 @@ These warnings are disabled by default. corrupt-sconsign Warnings about unfamiliar signature data in -.sconsign +.sconsign files. These warnings are enabled by default. @@ -1943,14 +1956,14 @@ that may require changes to the configuration. Warnings about the use of two commonly misspelled keywords -targets +targets and -sources -to &Builder; calls. The correct spelling is the +sources +to &f-link-Builder; calls. The correct spelling is the singular form, even though -target +target and -source +source can themselves refer to lists of names or nodes. -- cgit v0.12 From 4e5f9d227c99d54d1498fc80d7f59044e6979d90 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 16:46:22 -0600 Subject: Fix two errors in Environment.xml [ci skip] Recent changes introduced two xml errors that were not caught by docs-validate, because that script only validates xml under the doc directory, not the SCons source directory. A little further tweaking of CacheDir discussion is done - one of the errors was there and it got me looking... Signed-off-by: Mats Wichmann --- SCons/Environment.xml | 47 ++++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/SCons/Environment.xml b/SCons/Environment.xml index 1b00e32..f9c9304 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -662,8 +662,7 @@ caching by calling &f-env-CacheDir;. -When a -cache_dir +When derived-file caching is being used and &scons; finds a derived file that needs to be rebuilt, @@ -672,6 +671,10 @@ file with matching build signature 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. +&scons; +will report +Retrieved `file' from cache +instead of the normal build message. If the derived file is not present in the cache, &scons; will build it and @@ -680,6 +683,21 @@ identified by its build signature, for future use. +The +Retrieved `file' from cache +messages are useful for human consumption, +but less so when comparing log files between +&scons; runs which will show differences that are +noisy and not actually significant. +To disable, +use the option. +With this option, &scons; +will print the action that would +have been used to build the file without +considering cache retrieval. + + + Derived-file caching may be disabled for any invocation of &scons; by giving the @@ -712,27 +730,6 @@ has been done. -When using -&f-CacheDir;, -&scons; -will report -Retrieved `file' from cache -unless the - -option is being used. -With the - -option, &scons; -will print the action that would -have been used to build the file -whether or not it was retreived from the cache. -This is useful to generate build logs -that are equivalent regardless of whether -a given derived file has been built in-place -or retrieved from the cache. - - - The &f-link-NoCache; method can be used to disable caching of specific files. This can be @@ -880,7 +877,7 @@ for the calling syntax and details. Executes a specific action (or list of actions) to build a target file or files -from a source file or files. +from a source file or files. This is more convenient than defining a separate Builder object for a single special-case build. @@ -1380,7 +1377,7 @@ for more information. -Serializes &cpnsvars; to a string. +Serializes &consvars; to a string. The method supports the following formats specified by format: -- cgit v0.12 From a81a838085a35ddfeb12d9bbcdb4cf514b5744da Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 1 Jun 2020 19:16:49 -0600 Subject: User Guide: update markup for cmdline section [ci skip] Update the markup in the cmdline chapter. Also checked in two generated docs which were changed by a couple of earlier changesets. Signed-off-by: Mats Wichmann --- doc/generated/functions.gen | 889 +++++++++++++++++++++++--------------------- doc/generated/functions.mod | 4 - doc/user/command-line.xml | 172 +++++---- 3 files changed, 567 insertions(+), 498 deletions(-) diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index c0b325e..bfe63e8 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -16,28 +16,25 @@ Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]) env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]) -Creates an Action object for +A factory function to create an Action object for the specified -action. +action. See the manpage section "Action Objects" for a complete explanation of the arguments and behavior. -Note that the -env.Action() +Note that the env.Action form of the invocation will expand construction variables in any argument strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Action() -was called. -The -Action() +env.Action was called. +The Action global function form delays all variable expansion until the Action object is actually used. @@ -51,27 +48,26 @@ When called with the AddMethod() form, adds the specified -function +function to the specified -object +object as the specified method -name. -When called with the -env.AddMethod() -form, +name. +When called using the +env.AddMethod form, adds the specified -function +function to the construction environment -env +env as the specified method -name. +name. In both cases, if -name +name is omitted or -None, +None, the name of the specified -function +function itself is used for the method name. @@ -104,59 +100,59 @@ env.other_method_name('another arg') AddOption(arguments) -This function adds a new command-line option to be recognized. -The specified -arguments -are the same as supported by the add_option -method in the standard Python library module optparse, -with a few additional capabilities noted below; -see the documentation for +Adds a local (project-specific) command-line option. +arguments +are the same as those supported by the add_option +method in the standard Python library module optparse, +with a few additional capabilities noted below. +See the documentation for optparse for a thorough discussion of its option-processing capabities. In addition to the arguments and values supported by the -optparse.add_option() -method, -the SCons -AddOption -function allows you to set the -nargs +optparse +add_option +method, AddOption +allows setting the +nargs keyword value to -'?' -(a string with just the question mark) -to indicate that the specified long option(s) take(s) an -optional -argument. -When -nargs = '?' -is passed to the -AddOption -function, the -const -keyword argument -may be used to supply the "default" -value that should be used when the -option is specified on the command line -without an explicit argument. - - - -If no -default= -keyword argument is supplied when calling -AddOption, -the option will have a default value of -None. - - - -Unlike regular optparse, option names -added via AddOption must be matched -exactly, the automatic matching of abbreviations on the -command line for long options is not supported. -To allow specific abbreviations, +a string consisting of a question mark +('?') +to indicate that the option argument for +that option string is optional. +If the option string is present on the +command line but has no matching option +argument, the value of the +const +keyword argument is produced as the value +of the option. +If the option string is omitted from +the command line, the value of the +default +keyword argument is produced, as usual; +if there is no +default +keyword argument in the AddOption call, +None is produced. + + + +optparse recognizes +abbreviations of long option names, +as long as they can be unambiguously resolved. +For example, if +add_option is called to +define a option, +it will recognize , + +and so forth as long as there is no other option +which could also match to the same abbreviation. +Options added via +AddOption do not support +the automatic recognition of abbreviations. +Instead, to allow specific abbreviations, include them in the AddOption call. @@ -164,45 +160,40 @@ include them in the AddOption call. Once a new command-line option has been added with AddOption, the option value may be accessed using -GetOption +GetOption or -env.GetOption(). - -SetOption is not currently supported for -options added with AddOption. -Any specified -help= -strings for the new option(s) -will be displayed by the - -or - -options -(the latter only if no other help text is -specified in the SConscript files). -The help text for the local options specified by -AddOption -will appear below the SCons options themselves, -under a separate -Local Options -heading. -The options will appear in the help text -in the order in which the +Help text for an option is a combination +of the string supplied in the +help keyword +argument to AddOption and information +collected from the other keyword arguments. +Such help is displayed if the + command line option +is used (but not with ). +Help for all local options is displayed +under the separate heading +Local Options. +The options are unsorted - they will appear +in the help text in the order in which the AddOption calls occur. @@ -212,27 +203,50 @@ Example: -AddOption('--prefix', - dest='prefix', - nargs=1, type='string', - action='store', - metavar='DIR', - help='installation prefix') -env = Environment(PREFIX = GetOption('prefix')) +AddOption( + '--prefix', + dest='prefix', + nargs=1, + type='string', + action='store', + metavar='DIR', + help='installation prefix', +) +env = Environment(PREFIX=GetOption('prefix')) +For that example, +the following help text would be produced: + + +Local Options: + --prefix=DIR installation prefix + + + +Help text for local options may be unavailable if +the Help function has been called, +see the Help documentation for details. + + -While AddOption behaves like -add_option, -from the optparse module, +As an artifact of the internal implementation, the behavior of options added by AddOption -which take arguments is underfined in -scons if whitespace +which take option arguments is undefined +if whitespace (rather than an = sign) is used as -the separator on the command line when -the option is invoked. -Such usage should be avoided. +the separator on the command line. +Users should avoid such usage; it is recommended +to add a note to this effect to project documentation +if the situation is likely to arise. +In addition, if the nargs +keyword is used to specify more than one following +option argument (that is, with a value of 2 +or greater), such arguments would necessarily +be whitespace separated, triggering the issue. +Developers should not use AddOption this way. +Future versions of SCons will likely forbid such usage. @@ -243,10 +257,10 @@ Such usage should be avoided. env.AddPostAction(target, action) Arranges for the specified -action +action to be performed after the specified -target +target has been built. The specified action(s) may be an Action object, or anything that @@ -268,10 +282,10 @@ one or more targets in the list. env.AddPreAction(target, action) Arranges for the specified -action +action to be performed before the specified -target +target is built. The specified action(s) may be an Action object, or anything that @@ -324,7 +338,7 @@ file into an object file. Creates one or more phony targets that expand to one or more other targets. An optional -action +action (command) or list of actions can be specified that will be executed @@ -405,7 +419,7 @@ AllowSubstExceptions(IndexError, NameError, ZeroDivisionError) env.AlwaysBuild(target, ...) Marks each given -target +target so that it is always assumed to be out of date, and will always be rebuilt if needed. Note, however, that @@ -471,7 +485,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the end; it will stay where it is in the list. @@ -525,7 +539,7 @@ env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy']) Creates a Builder object for the specified -action. +action. See the manpage section "Builder Objects" for a complete explanation of the arguments and behavior. @@ -536,14 +550,13 @@ Note that the form of the invocation will expand construction variables in any arguments strings, including the -action +action argument, at the time it is called using the construction variables in the -env +env construction environment through which -env.Builder() -was called. +env.Builder was called. The Builder form delays all variable expansion @@ -555,68 +568,79 @@ until after the Builder object is actually called. CacheDir(cache_dir) env.CacheDir(cache_dir) -Specifies that +Direct scons -will maintain a cache of derived files in -cache_dir. +to maintain a derived-file cache in +cache_dir. The derived files in the cache will be shared -among all the builds using the same -CacheDir -call. +among all the builds specifying the same +cache_dir. Specifying a -cache_dir +cache_dir of -None +None disables derived file caching. -Calling -env.CacheDir() -will only affect targets built +Calling the environment method +env.CacheDir +limits the effect to targets built through the specified construction environment. -Calling -CacheDir +Calling the global function +CacheDir sets a global default that will be used by all targets built through construction environments -that do -not -have an -env.CacheDir() -specified. +that do not set up environment-specific +caching by calling env.CacheDir. -When a -CacheDir() +When derived-file caching 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 -derived file has already been built -from identical input files and an identical build action -(as incorporated into the MD5 build signature). -If so, +file with matching build signature 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. scons -will retrieve the file from the cache. +will report +Retrieved `file' from cache +instead of the normal build message. If the derived file is not present in the cache, scons -will rebuild it and -then place a copy of the built file in the cache -(identified by its MD5 build signature), -so that it may be retrieved by other -builds that need to build the same derived file -from identical inputs. +will build it and +then place a copy of the built file in the cache, +identified by its build signature, for future use. -Use of a specified -CacheDir +The +Retrieved `file' from cache +messages are useful for human consumption, +but less so when comparing log files between +scons runs which will show differences that are +noisy and not actually significant. +To disable, +use the option. +With this option, scons +will print the action that would +have been used to build the file without +considering cache retrieval. + + + +Derived-file caching may be disabled for any invocation -by using the +of scons by giving the -option. +command line option. +Cache updating may be disabled, leaving cache +fetching enabled, by giving the +. @@ -630,36 +654,14 @@ derived files in the cache, even if they already existed and were not built by this invocation. This is useful to populate a cache -the first time -CacheDir -is added to a build, -or after using the - -option. - - - -When using -CacheDir, -scons -will report, -"Retrieved `file' from cache," -unless the - -option is being used. -When the - -option is used, -scons -will print the action that -would -have been used to build the file, -without any indication that -the file was actually retrieved from the cache. -This is useful to generate build logs -that are equivalent regardless of whether -a given derived file has been built in-place -or retrieved from the cache. +the first time a +cache_dir +is used for a build, +or to bring a cache up to date after +a build with cache updating disabled +( +or ) +has been done. @@ -764,7 +766,7 @@ env4 = env.Clone(tools = ['msvc', MyTool]) The -parse_flags +parse_flags keyword argument is also recognized to allow merging command-line style arguments into the appropriate construction variables (see env.MergeFlags). @@ -780,21 +782,23 @@ wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags') Command(target, source, action, [key=val, ...]) env.Command(target, source, action, [key=val, ...]) -Executes a specific action +Executes a specific action (or list of actions) -to build a target file or files. +to build a target file or files +from a source file or files. This is more convenient than defining a separate Builder object for a single special-case build. -Command builder accepts -source_scanner, -target_scanner, -source_factory, and -target_factory -keyword arguments. The *_scanner args can +The +Command function accepts +source_scanner, +target_scanner, +source_factory, and +target_factory +keyword arguments. These arguments can be used to specify a Scanner object that will be used to apply a custom @@ -806,12 +810,12 @@ if any of the sources will be directories that must be scanned on-disk for changes to files that aren't already specified in other Builder of function calls. -The *_factory args take a factory function that the -Command will use to turn any sources or targets +The *_factory arguments take a factory function that +Command will use to turn any sources or targets specified as strings into SCons Nodes. -See the sections "Builder Objects" -below, for more information about how these -args work in a Builder. +See the manpage section "Builder Objects" +for more information about how these +arguments work in a Builder. @@ -826,13 +830,11 @@ or a callable Python object; see the manpage section "Action Objects" for more complete information. Also note that a string specifying an external command -may be preceded by an -@ -(at-sign) +may be preceded by an at-sign +(@) to suppress printing the command in question, -or by a -- -(hyphen) +or by a hyphen +(-) to ignore the exit status of the external command. @@ -841,21 +843,30 @@ Examples: -env.Command('foo.out', 'foo.in', - "$FOO_BUILD < $SOURCES > $TARGET") +env.Command( + target='foo.out', + source='foo.in', + action="$FOO_BUILD < $SOURCES > $TARGET" +) + +env.Command( + target='bar.out', + source='bar.in', + action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"], + ENV={'PATH': '/usr/local/bin/'}, +) -env.Command('bar.out', 'bar.in', - ["rm -f $TARGET", - "$BAR_BUILD < $SOURCES > $TARGET"], - ENV={'PATH': '/usr/local/bin/'}) +import os def rename(env, target, source): - import os os.rename('.tmp', str(target[0])) -env.Command('baz.out', 'baz.in', - ["$BAZ_BUILD < $SOURCES > .tmp", - rename]) + +env.Command( + target='baz.out', + source='baz.in', + action=["$BAZ_BUILD < $SOURCES > .tmp", rename], +) @@ -871,7 +882,7 @@ be treated as directories by using the Dir or -env.Dir +env.Dir functions. @@ -904,14 +915,6 @@ for a complete explanation of the arguments and behavior. - - env.Copy([key=val, ...]) - -A now-deprecated synonym for -env.Clone(). - - - Decider(function) env.Decider(function) @@ -919,18 +922,17 @@ A now-deprecated synonym for Specifies that all up-to-date decisions for targets built through this construction environment will be handled by the specified -function. -The -function -can be one of the following strings -that specify the type of decision function -to be performed: +function. +function can be the name of +a function or one of the following strings +that specify the predefined decision function +that will be applied: -timestamp-newer +"timestamp-newer" Specifies that a target shall be considered out of date and rebuilt @@ -944,7 +946,7 @@ can be used a synonym for -timestamp-match +"timestamp-match" Specifies that a target shall be considered out of date and rebuilt @@ -961,7 +963,7 @@ timestamp, such as can happen when restoring files from backup archives. -MD5 +"MD5" Specifies that a target shall be considered out of date and rebuilt @@ -978,7 +980,7 @@ can be used as a synonym for -MD5-timestamp +"MD5-timestamp" Specifies that a target shall be considered out of date and rebuilt @@ -1025,7 +1027,7 @@ env.Decider('content') In addition to the above already-available functions, the -function +function argument may be a Python function you supply. Such a function must accept the following four arguments: @@ -1038,10 +1040,10 @@ Such a function must accept the following four arguments: The Node (file) which should cause the -target +target to be rebuilt if it has "changed" since the last tme -target +target was built. @@ -1054,7 +1056,7 @@ The Node (file) being built. In the normal case, this is what should get rebuilt if the -dependency +dependency has "changed." @@ -1064,9 +1066,9 @@ has "changed." Stored information about the state of the -dependency +dependency the last time the -target +target was built. This can be consulted to match various file characteristics @@ -1080,11 +1082,11 @@ size, or content signature. If set, use this Node instead of the one specified by -dependency +dependency to determine if the dependency has changed. This argument is optional so should be written as a default argument (typically it would be -written as repo_node=None). +written as repo_node=None). A caller will normally only set this if the target only exists in a Repository. @@ -1096,14 +1098,14 @@ target only exists in a Repository. The -function +function should return a value which evaluates True if the -dependency +dependency has "changed" since the last time the -target +target was built (indicating that the target should @@ -1197,20 +1199,25 @@ see below. DefaultEnvironment([**kwargs]) -Creates and returns the default construction environment object. -The default construction environment is used internally by SCons +Instantiates and returns the default construction environment object. +The default environment is used internally by SCons in order to execute many of the global functions in this list -(i.e. those not called as methods of a specific -construction environment), and to fetch source files transparently -from source code management systems. -The default environment is a singleton, so the keyword +(that is, those not called as methods of a specific construction environment). +It is not mandatory to call DefaultEnvironment: +the default environment will be instantiated automatically when the +build phase begins if the function has not been called, +however calling it explicitly gives the opportunity to +affect and examine the contents of the default environment. + + +The default environment is a singleton, so the keyword arguments affect it only on the first call, on subsequent calls the already-constructed object is returned and -any arguments are ignored. -The default environment can be modified in the same way -as any construction environment. -Modifying the default environment has no effect on the environment -constructed by a subsequent Environment call. +any keyword arguments are silently ignored. +The default environment can be modified after instantiation +in the same way as any construction environment. +Modifying the default environment has no effect on the construction environment +constructed by an Environment or Clone call. @@ -1220,15 +1227,15 @@ constructed by a subsequent Environment call. Specifies an explicit dependency; the -target +target will be rebuilt whenever the -dependency +dependency has changed. Both the specified -target +target and -dependency +dependency can be a string (usually the path name of a file or directory) or Node objects, @@ -1269,9 +1276,9 @@ Find an executable from one or more choices: Returns the first value from progs that was found, or None. Executable is searched by checking the paths specified -by env['ENV']['PATH']. +by env['ENV']['PATH']. On Windows systems, additionally applies the filename suffixes found in -env['ENV']['PATHEXT'] +env['ENV']['PATHEXT'] but will not include any such extension in the return value. env.Detect is a wrapper around env.WhereIs. @@ -1304,24 +1311,24 @@ cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM') Returns Directory Node(s). A Directory Node is an object that represents a directory. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1336,13 +1343,37 @@ for more information. - env.Dump([key]) + env.Dump([key], [format]) -Returns a pretty printable representation of the environment. -key, -if not -None, -should be a string containing the name of the variable of interest. +Serializes construction variables to a string. +The method supports the following formats specified by +format: + + +pretty + + +Returns a pretty printed representation of the environment (if +format +is not specified, this is the default). + + + + +json + + +Returns a JSON-formatted string representation of the environment. + + + + + +If key is +None (the default) the entire +dictionary of construction variables is serialized. +If supplied, it is taken as the name of a construction variable +whose value is serialized. @@ -1438,7 +1469,7 @@ EnsureSConsVersion(0,96,90) Return a new construction environment initialized with the specified -key=value +key=value pairs. @@ -1449,16 +1480,20 @@ pairs. Executes an Action object. The specified -action +action may be an Action object (see manpage section "Action Objects" -for a complete explanation of the arguments and behavior), +for an explanation of behavior), or it may be a command-line string, list of commands, or executable Python function, each of which will be converted into an Action object and then executed. +Any additional arguments to Execute +(strfunction, varlist) +are passed on to the Action factory function +which actually creates the Action object. The exit value of the command or return value of the Python function will be returned. @@ -1468,7 +1503,7 @@ will be returned. Note that scons will print an error message if the executed -action +action fails--that is, exits with or returns a non-zero value. scons @@ -1477,7 +1512,7 @@ will however, automatically terminate the build if the specified -action +action fails. If you want the build to stop in response to a failed Execute @@ -1572,24 +1607,24 @@ See the description below. Returns File Node(s). A File Node is an object that represents a file. -name +name can be a relative or absolute path or a list of such paths. -directory +directory is an optional directory that will be used as the parent directory. If no -directory +directory is specified, the current script's directory is used as the parent. If -name +name is a single pathname, the corresponding node is returned. If -name +name is a list, SCons returns a list of nodes. Construction variables are expanded in -name. +name. @@ -1608,10 +1643,10 @@ for more information. env.FindFile(file, dirs) Search for -file +file in the path specified by -dirs. -dirs +dirs. +dirs may be a list of directory names or a single directory name. In addition to searching for files that exist in the filesystem, this function also searches for derived files @@ -1729,9 +1764,9 @@ scanner = Scanner(name = 'myscanner', Returns the list of nodes which serve as the source of the built files. It does so by inspecting the dependency tree starting at the optional argument -node +node which defaults to the '"."'-node. It will then return all leaves of -node. +node. These are all children which have no further children. @@ -1797,7 +1832,7 @@ Program(source = objects) # If you need to manipulate the list directly using Python, you need to # call Flatten() yourself, or otherwise handle nested lists: for object in Flatten(objects): - print str(object) + print(str(object)) @@ -1931,10 +1966,10 @@ atexit.register(print_build_failures) Returns the scons path name (or names) for the specified -file +file (or files). The specified -file +file or files may be scons @@ -2233,21 +2268,20 @@ option. env.Glob(pattern, [ondisk, source, strings, exclude]) Returns Nodes (or strings) that match the specified -pattern, +pattern, relative to the directory of the current SConscript file. -The -env.Glob() -form performs string substition on -pattern +The evironment method form (env.Glob) +performs string substition on +pattern and returns whatever matches the resulting expanded pattern. The specified -pattern +pattern uses Unix shell style metacharacters for matching: @@ -2281,14 +2315,14 @@ function) and returns a Node (or string, if so configured) in the local (SConscript) directory -if matching Node is found +if a matching Node is found anywhere in a corresponding repository or source directory. The -ondisk +ondisk argument may be set to a value which evaluates False to disable the search for matches on disk, @@ -2301,7 +2335,7 @@ for any on-disk matches found. The -source +source argument may be set to a value which evaluates True to specify that, @@ -2314,7 +2348,7 @@ not the local directory. The -strings +strings argument may be set to a value which evaluates True to have the @@ -2340,7 +2374,7 @@ directory.) The -exclude +exclude argument may be set to a pattern or a list of patterns (following the same Unix shell semantics) which must be filtered out of returned elements. @@ -2364,22 +2398,24 @@ sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \ Help(text, append=False) env.Help(text, append=False) -This specifies help text to be printed if the +Specifies a local help message to be printed if the argument is given to scons. -If -Help -is called multiple times, the text is appended together in the order that -Help -is called. With append set to False, any +Subsequent calls to Help -text generated with -AddOption -is clobbered. If append is True, the AddOption help is prepended to the help -string, thus preserving the - -message. +append text to the previously +defined local help text. + + +For the first call to Help only, +if append is False +(the default) +any local help message generated through +AddOption calls is replaced. +If append is True, +text is appended to +the existing help text. @@ -2458,7 +2494,7 @@ Import("*") env.Literal(string) The specified -string +string will be preserved as-is and not have construction variables expanded. @@ -2469,7 +2505,7 @@ and not have construction variables expanded. env.Local(targets) The specified -targets +targets will have copies made in the local tree, even if an already up-to-date copy exists in a repository. @@ -2481,17 +2517,17 @@ Returns a list of the target Node or Nodes. env.MergeFlags(arg, [unique]) Merges the specified -arg +arg values to the construction environment's construction variables. If the -arg +arg argument is not a dictionary, it is converted to one by calling env.ParseFlags on the argument before the values are merged. Note that -arg +arg must be a single value, so multiple strings must be passed in as a list, @@ -2633,11 +2669,11 @@ NoClean(env.Program('hello', 'hello.c')) env.ParseConfig(command, [function, unique]) Calls the specified -function +function to modify the environment as specified by the output of -command. +command. The default -function +function is env.MergeFlags, which expects the output of a typical @@ -2672,7 +2708,7 @@ for a table of options and construction variables. env.ParseDepends(filename, [must_exist, only_one]) Parses the contents of the specified -filename +filename as a list of dependencies in the style of Make or @@ -2684,10 +2720,10 @@ and explicitly establishes all of the listed dependencies. By default, it is not an error if the specified -filename +filename does not exist. The optional -must_exist +must_exist argument may be set to a non-zero value to have scons @@ -2698,7 +2734,7 @@ or is otherwise inaccessible. The optional -only_one +only_one argument may be set to a non-zero value to have scons @@ -2720,7 +2756,7 @@ file. The -filename +filename and all of the files listed therein will be interpreted relative to the directory of the @@ -2841,7 +2877,7 @@ env = Environment(platform = Platform('win32')) The env.Platform form applies the callable object for the specified platform -string +string to the environment through which the method was called. @@ -2932,7 +2968,7 @@ string, in which case a list will be returned instead of a string. If -delete_existing +delete_existing is 0, then adding a path that already exists will not move it to the beginning; it will stay where it is in the list. @@ -2999,22 +3035,21 @@ evaluating Nodes (e.g. files). If the first specified argument is a Python callable (a function or an object that has a -__call__() -method), +__call__ method), the function will be called once every interval -times a Node is evaluated. +times a Node is evaluated (default 1). The callable will be passed the evaluated Node as its only argument. (For future compatibility, it's a good idea to also add -*args +*args and -**kw -as arguments to your function or method. +**kwargs +as arguments to your function or method signatures. This will prevent the code from breaking -if SCons ever changes the interface +if SCons ever changes the interface to call the function with additional arguments in the future.) @@ -3025,7 +3060,7 @@ every 10 Nodes: -def my_progress_function(node, *args, **kw): +def my_progress_function(node, *args, **kwargs): print('Evaluating node %s!' % node) Progress(my_progress_function, interval=10) @@ -3043,8 +3078,7 @@ will overwrite itself on a display: import sys - -class ProgressCounter: +class ProgressCounter(object): count = 0 def __call__(self, node, *args, **kw): self.count += 100 @@ -3054,18 +3088,28 @@ Progress(ProgressCounter(), interval=100) -If the first argument -Progress -is a string, -the string will be displayed -every +If the first argument to +Progress is a string or list of strings, +it is taken as text to be displayed every +interval +evaluated Nodes. +If the first argument is a list of strings, +then each string in the list will be displayed +in rotating fashion every interval evaluated Nodes. -The default is to print the string on standard output; -an alternate output stream + + + +The default is to print the string on standard output. +An alternate output stream may be specified with the -file= -argument. +file +keyword argument, which the +caller must pass already opened. + + + The following will print a series of dots on the error output, one dot for every 100 evaluated Nodes: @@ -3078,7 +3122,7 @@ Progress('.', interval=100, file=sys.stderr) If the string contains the verbatim substring -$TARGET, +$TARGET;, it will be replaced with the Node. Note that, for performance reasons, this is not @@ -3087,12 +3131,13 @@ so you can not use other variables or use curly braces. The following example will print the name of every evaluated Node, -using a -\r -(carriage return) to cause each line to overwritten by the next line, +using a carriage return) +(\r) +to cause each line to overwritten by the next line, and the -overwrite= -keyword argument to make sure the previously-printed +overwrite +keyword argument (default False) +to make sure the previously-printed file name is overwritten with blank spaces: @@ -3102,15 +3147,9 @@ Progress('$TARGET\r', overwrite=True) -If the first argument to -Progress -is a list of strings, -then each string in the list will be displayed -in rotating fashion every -interval -evaluated Nodes. -This can be used to implement a "spinner" -on the user's screen as follows: +A list of strings can be used to implement a "spinner" +on the user's screen as follows, changing every +five evaluated Nodes: @@ -3142,16 +3181,16 @@ Multiple targets can be passed in to a single call to This returns a Directory Node similar to Dir. The python module / package is looked up and if located the directory is returned for the location. -modulename +modulename Is a named python package / module to lookup the directory for it's location. If -modulename +modulename is a list, SCons returns a list of Dir nodes. Construction variables are expanded in -modulename. +modulename. @@ -3176,7 +3215,7 @@ env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx') env.Repository(directory) Specifies that -directory +directory is a repository to be searched for files. Multiple calls to Repository @@ -3307,7 +3346,7 @@ Return('val1 val2') Creates a Scanner object for the specified -function. +function. See manpage section "Scanner Objects" for a complete explanation of the arguments and behavior. @@ -3604,18 +3643,18 @@ This tells scons to store all file signatures in the specified database -file. +file. If the -file +file name is omitted, .sconsign is used by default. (The actual file name(s) stored on disk may have an appropriated suffix appended by the - dbm_module.) +dbm_module.) If -file +file is not an absolute path name, the file is placed in the same directory as the top-level SConstruct @@ -3624,9 +3663,9 @@ file. If -file +file is -None, +None, then scons will store file signatures @@ -3640,7 +3679,7 @@ prior to SCons 0.96.91 and 0.97.) The optional -dbm_module +dbm_module argument can be used to specify which Python database module The default is to use a custom @@ -3817,13 +3856,13 @@ SetOption('max_drift', 1) env.SideEffect(side_effect, target) Declares -side_effect +side_effect as a side effect of building -target. +target. Both -side_effect +side_effect and -target +target can be a list, a file name, or a node. A side effect is a target file that is created or updated as a side effect of building other targets. @@ -3845,23 +3884,23 @@ multiple build commands. Because multiple build commands may update the same side effect file, by default the -side_effect +side_effect target is not automatically removed when the -target +target is removed by the option. (Note, however, that the -side_effect +side_effect might be removed as part of cleaning the directory in which it lives.) If you want to make sure the -side_effect +side_effect is cleaned whenever a specific -target +target is cleaned, you must specify this explicitly with the @@ -3877,13 +3916,13 @@ function. env.Split(arg) Returns a list of file names or other objects. -If arg is a string, +If arg is a string, it will be split on strings of white-space characters within the string, making it easier to write long lists of file names. -If arg is already a list, +If arg is already a list, the list will be returned untouched. -If arg is any other type of object, +If arg is any other type of object, it will be returned as a list containing just the object. @@ -3908,7 +3947,7 @@ files = Split(""" Performs construction variable interpolation on the specified string or sequence argument -input. +input. @@ -3923,14 +3962,14 @@ and $) character sequences will be stripped from the returned string, The optional -raw +raw argument may be set to 1 if you want to preserve white space and $(-$) sequences. The -raw +raw argument may be set to 2 if you want to strip @@ -3953,9 +3992,9 @@ and the results will be returned as a list. The optional -target +target and -source +source keyword arguments must be set to lists of target and source nodes, respectively, @@ -3977,7 +4016,7 @@ as an SCons action. Returned string values or sequence elements are converted to their string representation by default. The optional -conv +conv argument may specify a conversion function that will be used in place of @@ -4076,7 +4115,7 @@ as part of the tools keyword argument, or it can be called directly, passing a construction environment to update as the argument. Either approach will also update the -TOOLS construction variable. +$TOOLS construction variable. @@ -4101,17 +4140,17 @@ u(env) # adds 'opengl' to the TOOLS variable Returns a Node object representing the specified Python value. Value Nodes can be used as dependencies of targets. If the result of calling -str(value) +str(value) changes between SCons runs, any targets depending on -Value(value) +Value(value) will be rebuilt. (This is true even when using timestamps to decide if files are up-to-date.) When using timestamp source signatures, Value Nodes' timestamps are equal to the system time when the Node is created. -name can be provided as an alternative name +name can be provided as an alternative name for the resulting Value node; this is advised -if the value parameter can't be converted to +if the value parameter can't be converted to a string. @@ -4121,7 +4160,7 @@ The returned Value Node object has a method that can be used to "build" a Value Node by setting a new value. The optional -built_value +built_value argument can be specified when the Value Node is created to indicate the Node should already be considered @@ -4178,11 +4217,11 @@ Use the VariantDir function to create a copy of your sources in another location: if a name under -variant_dir +variant_dir is not found but exists under -src_dir, +src_dir, the file or directory is copied to -variant_dir. +variant_dir. Target files can be built in a different directory than the original sources by simply refering to the sources (and targets) within the variant tree. @@ -4191,15 +4230,15 @@ within the variant tree. VariantDir can be called multiple times with the same -src_dir +src_dir to set up multiple builds with different options -(variants). +(variants). The -src_dir +src_dir location must be in or underneath the SConstruct file's directory, and -variant_dir +variant_dir may not be underneath -src_dir. +src_dir. - &SetOption; is not currently supported for - options added with &AddOption;. @@ -634,15 +667,17 @@ foo.in -AddOption('--prefix', - dest='prefix', - type='string', - nargs=1, - action='store', - metavar='DIR', - help='installation prefix') +AddOption( + '--prefix', + dest='prefix', + type='string', + nargs=1, + action='store', + metavar='DIR', + help='installation prefix', +) -env = Environment(PREFIX = GetOption('prefix')) +env = Environment(PREFIX=GetOption('prefix')) installed_foo = env.Install('$PREFIX/usr/bin', 'foo.in') Default(installed_foo) @@ -655,14 +690,14 @@ foo.in The above code uses the &GetOption; function - to set the $PREFIX + to set the $PREFIX construction variable to any value that the user specifies with a command-line - option of --prefix. - Because $PREFIX + option of . + Because $PREFIX will expand to a null string if it's not initialized, running &SCons; without the - option of --prefix + option of will install the file in the /usr/bin/ directory: @@ -674,7 +709,7 @@ foo.in - But specifying --prefix=/tmp/install + But specifying on the command line causes the file to be installed in the /tmp/install/usr/bin/ directory: @@ -688,13 +723,13 @@ foo.in Option-arguments separated from long options by whitespace, rather than by an =, cannot be correctly - resolved by scons. - While --input=ARG - is clearly opt followed by arg, for --input ARG + resolved by &SCons;. + While + is clearly opt followed by arg, for it is not possible to tell without instructions whether ARG is an argument belonging to the input option or a positional argument. - scons treats positional arguments as either + &SCons; treats positional arguments as either command-line build options or command-line targets which are made available for use in an &SConscript; (see the immediately following sections for details). @@ -702,21 +737,21 @@ foo.in takes place. Since &AddOption; calls, which provide the processing instructions to resolve any ambiguity, happen in an &SConscript;, - scons does not know in time + &SCons; does not know in time for options added this way, and unexpected things will happen, such as option-arguments assigned as targets and/or exceptions due to missing option-arguments. As a result, this usage style should be avoided when invoking - scons. For single-argument - options, use the --input=ARG form on the + &scons;. For single-argument + options, use the form on the command line. For multiple-argument options (nargs greater than one), set nargs to one in &AddOption; calls and either: combine the option-arguments into one word with a separator, and parse the result in your own code - (see the built-in --debug option, which + (see the built-in option, which allows specifying multiple arguments as a single comma-separated word, for an example of such usage); or allow the option to be specified multiple times by setting @@ -730,13 +765,13 @@ foo.in
- Command-Line <varname>variable</varname>=<varname>value</varname> Build Variables + Command-Line <varname>variable</varname>=<replaceable>value</replaceable> Build Variables You may want to control various aspects of your build by allowing the user - to specify variable=value + to specify variable=value values on the command line. For example, suppose you want users to be able to @@ -753,7 +788,7 @@ foo.in &SCons; provides an &ARGUMENTS; dictionary that stores all of the - variable=value + variable=value assignments from the command line. This allows you to modify aspects of your build in response @@ -762,8 +797,7 @@ foo.in that users always specify a variable, you probably want to use - the Python - ARGUMENTS.get() function, + the Python dictionary get method, which allows you to specify a default value to be used if there is no specification on the command line.) @@ -845,7 +879,7 @@ prog.c To accomodate these requirements, &SCons; provides an &ARGLIST; variable that gives you direct access to - variable=value + variable=value settings on the command line, in the exact order they were specified, and without removing any duplicate settings. @@ -898,7 +932,7 @@ prog.c variables do not interfere with each other, but merely provide slightly different views into how the user specified - variable=value + variable=value settings on the command line. You can use both variables in the same &SCons; configuration. @@ -1056,7 +1090,7 @@ Help(vars.GenerateHelpText(env)) &SCons; will now display some useful text - when the -h option is used: + when the option is used: @@ -2292,7 +2326,7 @@ prog1.c &DEFAULT_TARGETS; list takes place during the first phase when &SCons; is reading up the &SConscript; files, which is obvious if - we leave off the -Q flag when we run &SCons;:) + we leave off the flag when we run &SCons;:) -- cgit v0.12 From c47ec6035ba472880ff3a9aead3a82baae3004c4 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 3 Jun 2020 06:23:35 -0600 Subject: [PR #3682] drop one more env var $ introducer [ci skip] Signed-off-by: Mats Wichmann --- doc/user/command-line.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 9114273..c230fea 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -342,7 +342,7 @@ foo.in The above snippet of code sets the value of the option to the value specified in the - $NUM_CPU environment variable. + NUM_CPU environment variable. (This is one of the exception cases where the string is spelled differently from the from command-line option. -- cgit v0.12 From 0e1ba5955b533677671ba483510109fc93472341 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 31 May 2020 10:36:19 -0600 Subject: Update debugging in MSVC Added the function name/lineno to the logging template, and removed function name from wherever it appeared in actual calls to debug() - this simplifies things a bit. The template is easily changeable; it's a pain to edit dozens of debug calls. Signed-off-by: Mats Wichmann --- SCons/Tool/MSCommon/common.py | 14 +++++-- SCons/Tool/MSCommon/sdk.py | 6 +-- SCons/Tool/MSCommon/vc.py | 94 +++++++++++++++++++++---------------------- SCons/Tool/MSCommon/vs.py | 30 +++++++------- 4 files changed, 75 insertions(+), 69 deletions(-) diff --git a/SCons/Tool/MSCommon/common.py b/SCons/Tool/MSCommon/common.py index b2b5de9..e1a82f2 100644 --- a/SCons/Tool/MSCommon/common.py +++ b/SCons/Tool/MSCommon/common.py @@ -43,7 +43,15 @@ if LOGFILE == '-': elif LOGFILE: import logging logging.basicConfig( - format='%(relativeCreated)05dms:pid%(process)05d:MSCommon/%(filename)s:%(message)s', + # This looks like: + # 00109ms:MSCommon/vc.py:find_vc_pdir#447: + format=( + '%(relativeCreated)05dms' + ':MSCommon/%(filename)s' + ':%(funcName)s' + '#%(lineno)s' + ':%(message)s: ' + ), filename=LOGFILE, level=logging.DEBUG) debug = logging.getLogger(name=__name__).debug @@ -243,8 +251,8 @@ def get_output(vcbat, args=None, env=None): stderr = popen.stderr.read() # Extra debug logic, uncomment if necessary -# debug('get_output():stdout:%s'%stdout) -# debug('get_output():stderr:%s'%stderr) + # debug('stdout:%s' % stdout) + # debug('stderr:%s' % stderr) # Ongoing problems getting non-corrupted text led to this # changing to "oem" from "mbcs" - the scripts run presumably diff --git a/SCons/Tool/MSCommon/sdk.py b/SCons/Tool/MSCommon/sdk.py index 03306ad..b76fbdd 100644 --- a/SCons/Tool/MSCommon/sdk.py +++ b/SCons/Tool/MSCommon/sdk.py @@ -33,9 +33,7 @@ import os import SCons.Errors import SCons.Util -from . import common - -debug = common.debug +from .common import debug, read_reg # SDK Checks. This is of course a mess as everything else on MS platforms. Here # is what we do to detect the SDK: @@ -79,7 +77,7 @@ class SDKDefinition: debug('find_sdk_dir(): checking registry:{}'.format(hkey)) try: - sdk_dir = common.read_reg(hkey) + sdk_dir = read_reg(hkey) except SCons.Util.WinError as e: debug('find_sdk_dir(): no SDK registry key {}'.format(repr(hkey))) return None diff --git a/SCons/Tool/MSCommon/vc.py b/SCons/Tool/MSCommon/vc.py index d3b2816..95afcca 100644 --- a/SCons/Tool/MSCommon/vc.py +++ b/SCons/Tool/MSCommon/vc.py @@ -190,7 +190,7 @@ def get_msvc_version_numeric(msvc_version): return ''.join([x for x in msvc_version if x in string_digits + '.']) def get_host_target(env): - debug('get_host_target()') + debug('called') host_platform = env.get('HOST_ARCH') if not host_platform: @@ -205,7 +205,7 @@ def get_host_target(env): # Retain user requested TARGET_ARCH req_target_platform = env.get('TARGET_ARCH') - debug('get_host_target() req_target_platform:%s'%req_target_platform) + debug('req_target_platform:%s' % req_target_platform) if req_target_platform: # If user requested a specific platform then only try that one. @@ -369,7 +369,7 @@ def find_vc_pdir_vswhere(msvc_version, env=None): if vswhere_path is None: return None - debug('find_vc_pdir_vswhere(): VSWHERE = %s'%vswhere_path) + debug('VSWHERE = %s'%vswhere_path) vswhere_cmd = [ vswhere_path, "-products", "*", @@ -377,7 +377,7 @@ def find_vc_pdir_vswhere(msvc_version, env=None): "-property", "installationPath", ] - debug("find_vc_pdir_vswhere(): running: %s" % vswhere_cmd) + debug("running: %s" % vswhere_cmd) #cp = subprocess.run(vswhere_cmd, capture_output=True) # 3.7+ only cp = subprocess.run(vswhere_cmd, stdout=PIPE, stderr=PIPE) @@ -428,9 +428,9 @@ def find_vc_pdir(env, msvc_version): if not key: comps = find_vc_pdir_vswhere(msvc_version, env) if not comps: - debug('find_vc_pdir_vswhere(): no VC found for version {}'.format(repr(msvc_version))) + debug('no VC found for version {}'.format(repr(msvc_version))) raise SCons.Util.WinError - debug('find_vc_pdir_vswhere(): VC found: {}'.format(repr(msvc_version))) + debug('VC found: {}'.format(repr(msvc_version))) return comps else: if common.is_win64(): @@ -444,13 +444,13 @@ def find_vc_pdir(env, msvc_version): # not Win64, or Microsoft Visual Studio for Python 2.7 comps = common.read_reg(root + key, hkroot) except SCons.Util.WinError as e: - debug('find_vc_dir(): no VC registry key {}'.format(repr(key))) + debug('no VC registry key {}'.format(repr(key))) else: - debug('find_vc_dir(): found VC in registry: {}'.format(comps)) + debug('found VC in registry: {}'.format(comps)) if os.path.exists(comps): return comps else: - debug('find_vc_dir(): reg says dir is {}, but it does not exist. (ignoring)'.format(comps)) + debug('reg says dir is {}, but it does not exist. (ignoring)'.format(comps)) raise MissingConfiguration("registry dir {} not found on the filesystem".format(comps)) return None @@ -495,11 +495,11 @@ def find_batch_file(env,msvc_version,host_arch,target_arch): for _sdk in installed_sdks: sdk_bat_file = _sdk.get_sdk_vc_script(host_arch,target_arch) if not sdk_bat_file: - debug("find_batch_file() not found:%s"%_sdk) + debug("batch file not found:%s" % _sdk) else: sdk_bat_file_path = os.path.join(pdir,sdk_bat_file) if os.path.exists(sdk_bat_file_path): - debug('find_batch_file() sdk_bat_file_path:%s'%sdk_bat_file_path) + debug('sdk_bat_file_path:%s' % sdk_bat_file_path) return (batfilename, use_arg, sdk_bat_file_path) return (batfilename, use_arg, None) @@ -543,7 +543,7 @@ def _check_cl_exists_in_vc_dir(env, vc_dir, msvc_version): host_platform = _ARCH_TO_CANONICAL[host_platform] target_platform = _ARCH_TO_CANONICAL[target_platform] - debug('_check_cl_exists_in_vc_dir(): host platform %s, target platform %s for version %s' % (host_platform, target_platform, msvc_version)) + debug('host platform %s, target platform %s for version %s' % (host_platform, target_platform, msvc_version)) ver_num = float(get_msvc_version_numeric(msvc_version)) @@ -558,21 +558,21 @@ def _check_cl_exists_in_vc_dir(env, vc_dir, msvc_version): with open(default_toolset_file) as f: vc_specific_version = f.readlines()[0].strip() except IOError: - debug('_check_cl_exists_in_vc_dir(): failed to read ' + default_toolset_file) + debug('failed to read ' + default_toolset_file) return False except IndexError: - debug('_check_cl_exists_in_vc_dir(): failed to find MSVC version in ' + default_toolset_file) + debug('failed to find MSVC version in ' + default_toolset_file) return False host_trgt_dir = _HOST_TARGET_TO_CL_DIR_GREATER_THAN_14.get((host_platform, target_platform), None) if host_trgt_dir is None: - debug('_check_cl_exists_in_vc_dir(): unsupported host/target platform combo: (%s,%s)'%(host_platform, target_platform)) + debug('unsupported host/target platform combo: (%s,%s)'%(host_platform, target_platform)) return False cl_path = os.path.join(vc_dir, 'Tools','MSVC', vc_specific_version, 'bin', host_trgt_dir[0], host_trgt_dir[1], _CL_EXE_NAME) - debug('_check_cl_exists_in_vc_dir(): checking for ' + _CL_EXE_NAME + ' at ' + cl_path) + debug('checking for ' + _CL_EXE_NAME + ' at ' + cl_path) if os.path.exists(cl_path): - debug('_check_cl_exists_in_vc_dir(): found ' + _CL_EXE_NAME + '!') + debug('found ' + _CL_EXE_NAME + '!') return True elif host_platform == "amd64" and host_trgt_dir[0] == "Hostx64": @@ -584,9 +584,9 @@ def _check_cl_exists_in_vc_dir(env, vc_dir, msvc_version): # targets, but we don't see those in this function. host_trgt_dir = ("Hostx86", host_trgt_dir[1]) cl_path = os.path.join(vc_dir, 'Tools','MSVC', vc_specific_version, 'bin', host_trgt_dir[0], host_trgt_dir[1], _CL_EXE_NAME) - debug('_check_cl_exists_in_vc_dir(): checking for ' + _CL_EXE_NAME + ' at ' + cl_path) + debug('checking for ' + _CL_EXE_NAME + ' at ' + cl_path) if os.path.exists(cl_path): - debug('_check_cl_exists_in_vc_dir(): found ' + _CL_EXE_NAME + '!') + debug('found ' + _CL_EXE_NAME + '!') return True elif 14 >= ver_num >= 8: @@ -595,11 +595,11 @@ def _check_cl_exists_in_vc_dir(env, vc_dir, msvc_version): # yields true when tested if not host_trgt_dir host_trgt_dir = _HOST_TARGET_TO_CL_DIR.get((host_platform, target_platform), None) if host_trgt_dir is None: - debug('_check_cl_exists_in_vc_dir(): unsupported host/target platform combo') + debug('unsupported host/target platform combo') return False cl_path = os.path.join(vc_dir, 'bin', host_trgt_dir, _CL_EXE_NAME) - debug('_check_cl_exists_in_vc_dir(): checking for ' + _CL_EXE_NAME + ' at ' + cl_path) + debug('checking for ' + _CL_EXE_NAME + ' at ' + cl_path) cl_path_exists = os.path.exists(cl_path) if not cl_path_exists and host_platform == 'amd64': @@ -614,23 +614,23 @@ def _check_cl_exists_in_vc_dir(env, vc_dir, msvc_version): return False cl_path = os.path.join(vc_dir, 'bin', host_trgt_dir, _CL_EXE_NAME) - debug('_check_cl_exists_in_vc_dir(): checking for ' + _CL_EXE_NAME + ' at ' + cl_path) + debug('checking for ' + _CL_EXE_NAME + ' at ' + cl_path) cl_path_exists = os.path.exists(cl_path) if cl_path_exists: - debug('_check_cl_exists_in_vc_dir(): found ' + _CL_EXE_NAME + '!') + debug('found ' + _CL_EXE_NAME + '!') return True elif 8 > ver_num >= 6: # not sure about these versions so if a walk the VC dir (could be slow) for root, _, files in os.walk(vc_dir): if _CL_EXE_NAME in files: - debug('get_installed_vcs ' + _CL_EXE_NAME + ' found %s' % os.path.join(root, _CL_EXE_NAME)) + debug(_CL_EXE_NAME + ' found %s' % os.path.join(root, _CL_EXE_NAME)) return True return False else: # version not support return false - debug('_check_cl_exists_in_vc_dir(): unsupported MSVC version: ' + str(ver_num)) + debug('unsupported MSVC version: ' + str(ver_num)) return False @@ -655,9 +655,9 @@ def get_installed_vcs(env=None): if _check_cl_exists_in_vc_dir(env, VC_DIR, ver): installed_versions.append(ver) else: - debug('find_vc_pdir no compiler found %s' % ver) + debug('no compiler found %s' % ver) else: - debug('find_vc_pdir return None for ver %s' % ver) + debug('return None for ver %s' % ver) except (MSVCUnsupportedTargetArch, MSVCUnsupportedHostArch): # Allow this exception to propagate further as it should cause # SCons to exit with an error code @@ -714,12 +714,12 @@ def script_env(script, args=None): return cache_data def get_default_version(env): - debug('get_default_version()') + debug('called') msvc_version = env.get('MSVC_VERSION') msvs_version = env.get('MSVS_VERSION') - debug('get_default_version(): msvc_version:%s msvs_version:%s'%(msvc_version,msvs_version)) + debug('msvc_version:%s msvs_version:%s' % (msvc_version,msvs_version)) if msvs_version and not msvc_version: SCons.Warnings.warn( @@ -742,10 +742,10 @@ def get_default_version(env): #msg = 'No installed VCs' #debug('msv %s' % repr(msg)) #SCons.Warnings.warn(SCons.Warnings.VisualCMissingWarning, msg) - debug('msvc_setup_env: No installed VCs') + debug('No installed VCs') return None msvc_version = installed_vcs[0] - debug('msvc_setup_env: using default installed MSVC version %s' % repr(msvc_version)) + debug('using default installed MSVC version %s' % repr(msvc_version)) return msvc_version @@ -774,7 +774,7 @@ def msvc_find_valid_batch_script(env, version): # Find the host, target, and if present the requested target: platforms = get_host_target(env) - debug(" msvs_find_valid_batch_script(): host_platform %s, target_platform %s req_target_platform:%s" % platforms) + debug("host_platform %s, target_platform %s req_target_platform %s" % platforms) host_platform, target_platform, req_target_platform = platforms # Most combinations of host + target are straightforward. @@ -804,14 +804,14 @@ def msvc_find_valid_batch_script(env, version): # if there are no viable 64 bit tools installed try_target_archs.append('x86') - debug("msvs_find_valid_batch_script(): host_platform: %s try_target_archs:%s"%(host_platform, try_target_archs)) + debug("host_platform: %s, try_target_archs: %s"%(host_platform, try_target_archs)) d = None for tp in try_target_archs: # Set to current arch. env['TARGET_ARCH'] = tp - debug("msvc_find_valid_batch_script() trying target_platform:%s"%tp) + debug("trying target_platform:%s" % tp) host_target = (host_platform, tp) if not is_host_target_supported(host_target, version): warn_msg = "host, target = %s not supported for MSVC version %s" % \ @@ -822,7 +822,7 @@ def msvc_find_valid_batch_script(env, version): # Try to locate a batch file for this host/target platform combo try: (vc_script, use_arg, sdk_script) = find_batch_file(env, version, host_platform, tp) - debug('msvc_find_valid_batch_script() vc_script:%s sdk_script:%s'%(vc_script,sdk_script)) + debug('vc_script:%s sdk_script:%s'%(vc_script,sdk_script)) except VisualCException as e: msg = str(e) debug('Caught exception while looking for batch file (%s)' % msg) @@ -834,7 +834,7 @@ def msvc_find_valid_batch_script(env, version): continue # Try to use the located batch file for this host/target platform combo - debug('msvc_find_valid_batch_script() use_script 2 %s, args:%s' % (repr(vc_script), arg)) + debug('use_script 2 %s, args:%s' % (repr(vc_script), arg)) found = None if vc_script: if not use_arg: @@ -851,22 +851,22 @@ def msvc_find_valid_batch_script(env, version): d = script_env(vc_script, args=arg) found = vc_script except BatchFileExecutionError as e: - debug('msvc_find_valid_batch_script() use_script 3: failed running VC script %s: %s: Error:%s'%(repr(vc_script),arg,e)) + debug('use_script 3: failed running VC script %s: %s: Error:%s'%(repr(vc_script),arg,e)) vc_script=None continue if not vc_script and sdk_script: - debug('msvc_find_valid_batch_script() use_script 4: trying sdk script: %s' % sdk_script) + debug('use_script 4: trying sdk script: %s' % sdk_script) try: d = script_env(sdk_script) found = sdk_script except BatchFileExecutionError as e: - debug('msvc_find_valid_batch_script() use_script 5: failed running SDK script %s: Error:%s'%(repr(sdk_script), e)) + debug('use_script 5: failed running SDK script %s: Error:%s'%(repr(sdk_script), e)) continue elif not vc_script and not sdk_script: - debug('msvc_find_valid_batch_script() use_script 6: Neither VC script nor SDK script found') + debug('use_script 6: Neither VC script nor SDK script found') continue - debug("msvc_find_valid_batch_script() Found a working script/target: %s/%s"%(repr(found),arg)) + debug("Found a working script/target: %s/%s"%(repr(found),arg)) break # We've found a working target_platform, so stop looking # If we cannot find a viable installed compiler, reset the TARGET_ARCH @@ -878,7 +878,7 @@ def msvc_find_valid_batch_script(env, version): def msvc_setup_env(env): - debug('msvc_setup_env()') + debug('called') version = get_default_version(env) if version is None: @@ -886,7 +886,7 @@ def msvc_setup_env(env): "compilers most likely not set correctly" SCons.Warnings.warn(SCons.Warnings.VisualCMissingWarning, warn_msg) return None - debug('msvc_setup_env: using specified MSVC version %s' % repr(version)) + debug('using specified MSVC version %s' % repr(version)) # XXX: we set-up both MSVS version for backward # compatibility with the msvs tool @@ -897,11 +897,11 @@ def msvc_setup_env(env): use_script = env.get('MSVC_USE_SCRIPT', True) if SCons.Util.is_String(use_script): - debug('msvc_setup_env() use_script 1 %s' % repr(use_script)) + debug('use_script 1 %s' % repr(use_script)) d = script_env(use_script) elif use_script: d = msvc_find_valid_batch_script(env,version) - debug('msvc_setup_env() use_script 2 %s' % d) + debug('use_script 2 %s' % d) if not d: return d else: @@ -913,11 +913,11 @@ def msvc_setup_env(env): for k, v in d.items(): env.PrependENVPath(k, v, delete_existing=True) - debug("msvc_setup_env() env['ENV']['%s'] = %s" % (k, env['ENV'][k])) + debug("env['ENV']['%s'] = %s" % (k, env['ENV'][k])) # final check to issue a warning if the compiler is not present if not find_program_path(env, 'cl'): - debug("msvc_setup_env() did not find 'cl'") + debug("did not find " + _CL_EXE_NAME) if CONFIG_CACHE: propose = "SCONS_CACHE_MSVC_CONFIG caching enabled, remove cache file {} if out of date.".format(CONFIG_CACHE) else: diff --git a/SCons/Tool/MSCommon/vs.py b/SCons/Tool/MSCommon/vs.py index 5a2523a..4eee9b3 100644 --- a/SCons/Tool/MSCommon/vs.py +++ b/SCons/Tool/MSCommon/vs.py @@ -55,12 +55,12 @@ class VisualStudio: def find_batch_file(self): vs_dir = self.get_vs_dir() if not vs_dir: - debug('find_executable(): no vs_dir') + debug('no vs_dir') return None batch_file = os.path.join(vs_dir, self.batch_file_path) batch_file = os.path.normpath(batch_file) if not os.path.isfile(batch_file): - debug('find_batch_file(): %s not on file system' % batch_file) + debug('%s not on file system' % batch_file) return None return batch_file @@ -68,7 +68,7 @@ class VisualStudio: SCons.Tool.MSCommon.vc.get_installed_vcs(env) dir = SCons.Tool.MSCommon.vc.find_vc_pdir(env, self.vc_version) if not dir: - debug('find_vs_dir_by_vc(): no installed VC %s' % self.vc_version) + debug('no installed VC %s' % self.vc_version) return None return os.path.abspath(os.path.join(dir, os.pardir)) @@ -84,9 +84,9 @@ class VisualStudio: try: comps = read_reg(key) except SCons.Util.WinError as e: - debug('find_vs_dir_by_reg(): no VS registry key {}'.format(repr(key))) + debug('no VS registry key {}'.format(repr(key))) else: - debug('find_vs_dir_by_reg(): found VS in registry: {}'.format(comps)) + debug('found VS in registry: {}'.format(comps)) return comps return None @@ -98,18 +98,18 @@ class VisualStudio: vs_dir=self.find_vs_dir_by_reg(env) if not vs_dir: vs_dir = self.find_vs_dir_by_vc(env) - debug('find_vs_dir(): found VS in ' + str(vs_dir )) + debug('found VS in ' + str(vs_dir )) return vs_dir def find_executable(self, env): vs_dir = self.get_vs_dir(env) if not vs_dir: - debug('find_executable(): no vs_dir ({})'.format(vs_dir)) + debug('no vs_dir ({})'.format(vs_dir)) return None executable = os.path.join(vs_dir, self.executable_path) executable = os.path.normpath(executable) if not os.path.isfile(executable): - debug('find_executable(): {} not on file system'.format(executable)) + debug('{} not on file system'.format(executable)) return None return executable @@ -123,12 +123,12 @@ class VisualStudio: def get_executable(self, env=None): try: - debug('get_executable using cache:%s'%self._cache['executable']) + debug('using cache:%s'%self._cache['executable']) return self._cache['executable'] except KeyError: executable = self.find_executable(env) self._cache['executable'] = executable - debug('get_executable not in cache:%s'%executable) + debug('not in cache:%s'%executable) return executable def get_vs_dir(self, env): @@ -479,14 +479,14 @@ def get_vs_by_version(msvs): global InstalledVSMap global SupportedVSMap - debug('get_vs_by_version()') + debug('called') if msvs not in SupportedVSMap: msg = "Visual Studio version %s is not supported" % repr(msvs) raise SCons.Errors.UserError(msg) get_installed_visual_studios() vs = InstalledVSMap.get(msvs) - debug('InstalledVSMap:%s'%InstalledVSMap) - debug('get_vs_by_version: found vs:%s'%vs) + debug('InstalledVSMap:%s' % InstalledVSMap) + debug('found vs:%s' % vs) # Some check like this would let us provide a useful error message # if they try to set a Visual Studio version that's not installed. # However, we also want to be able to run tests (like the unit @@ -521,8 +521,8 @@ def get_default_version(env): if versions: env['MSVS_VERSION'] = versions[0] #use highest version by default else: - debug('get_default_version: WARNING: no installed versions found, ' - 'using first in SupportedVSList (%s)'%SupportedVSList[0].version) + debug('WARNING: no installed versions found, ' + 'using first in SupportedVSList (%s)' % SupportedVSList[0].version) env['MSVS_VERSION'] = SupportedVSList[0].version env['MSVS']['VERSION'] = env['MSVS_VERSION'] -- cgit v0.12 From 1ec3ac13545e57c2396a6255bf8069aeaead866b Mon Sep 17 00:00:00 2001 From: William Deegan Date: Wed, 3 Jun 2020 21:37:07 -0700 Subject: [ci skip] fix typo in markup --- doc/user/command-line.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index c230fea..b6fb0a4 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -268,7 +268,7 @@ if not GetOption('help'): &f-Getoption; can be used to retrieve the values of options defined by calls to &f-link-AddOption;. A &f-GetOption; call must appear after the &f-AddOption; call for that option. - If the &f-AddOption; call supplied a dest + If the &f-AddOption; call supplied a dest keyword argument, a string with that name is what to pass as the argument to &f-GetOption;, otherwise it is a (possibly modified) version of the first long option name - -- cgit v0.12