Clarify behavior of -C option plus speedups

Manpage now indicates that the additive behavior of multiple
-C options applies only to non-absolute paths.  A test for
a -C absolute-path is added.

Along the way this and several other option flag testcases were
sped up through the tools=[] trick.  On the Windows box under
test, these changes took 150 seconds off a (non-parallel) test run.

Signed-off-by: Mats Wichmann <mats@linux.com>

10 files changed, 137 insertions, 111 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index 899669e..19affcf 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -638,11 +638,12 @@ yet have any results in the cache.</para>
   </listitem>
   </varlistentry>
   <varlistentry>
-  <term>-C<emphasis> directory</emphasis>, --directory=<emphasis>directory</emphasis></term>
+  <term>-C <replaceable>directory</replaceable>, --directory=<replaceable>directory</replaceable></term>
   <listitem>
-<para>Change to the specified
-<emphasis>directory</emphasis>
-before searching for the
+<para>Run as if &scons; was started in
+<replaceable>directory</replaceable>
+instead of the current working directory.
+That is, change directory before searching for the
 <emphasis>SConstruct</emphasis>,
 <emphasis>Sconstruct</emphasis>,
 <emphasis>sconstruct</emphasis>,
@@ -651,23 +652,18 @@ before searching for the
 or
 <emphasis>sconstruct.py</emphasis>
 file, or doing anything
-else.  Multiple
-<option>-C</option>
-options are interpreted
-relative to the previous one, and the right-most
+else.  When multiple
 <option>-C</option>
-option wins. (This option is nearly
-equivalent to
-<option>-f directory/SConstruct</option>,
-except that it will search for
-<emphasis>SConstruct</emphasis>,
-<emphasis>Sconstruct</emphasis>,
-<emphasis>sconstruct</emphasis>,
-<emphasis>SConstruct.py</emphasis>
-<emphasis>Sconstruct.py</emphasis>
-or
-<emphasis>sconstruct.py</emphasis>
-in the specified directory.)</para>
+options are given, each subsequent non-absolute
+<option>-C</option> <replaceable>directory</replaceable>
+is interpreted relative to the preceding one.
+This option is similar to
+<option>-f <replaceable>directory</replaceable>/SConstruct</option>,
+but <option>-f</option> does not search for any of the
+predefined <emphasis>SConstruct</emphasis> names
+in the specified directory.</para>
+  </listitem>
+  </varlistentry>
 
 <!--  .TP -->
 <!--  \-d -->
@@ -675,8 +671,6 @@ in the specified directory.)</para>
 <!--  figuring out why a specific file is being rebuilt, as well as -->
 <!--  general debugging of the build process. -->
 
-  </listitem>
-  </varlistentry>
   <varlistentry>
   <term>-D</term>
   <listitem>
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST
index 62da288..3110c2a 100644
--- a/doc/user/MANIFEST
+++ b/doc/user/MANIFEST
@@ -43,7 +43,6 @@ scanners.xml
 sconf.xml
 separate.xml
 simple.xml
-sourcecode.xml
 tasks.xml
 tools.xml
 troubleshoot.xml
diff --git a/test/option--C.py b/test/option--C.py
index 3802bce..b5b5f98 100644
--- a/test/option--C.py
+++ b/test/option--C.py
@@ -22,6 +22,11 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
+"""
+Test that the -C option changes directory as expected - additively,
+except if a full path is given
+"""
+
 __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
 
 import os
@@ -50,44 +55,59 @@ wpath_sub_foo_bar = test.workpath('sub', 'foo', 'bar')
 test.subdir('sub', ['sub', 'dir'])
 
 test.write('SConstruct', """
+DefaultEnvironment(tools=[])
 import os
 print("SConstruct "+os.getcwd())
 """)
 
 test.write(['sub', 'SConstruct'], """
+DefaultEnvironment(tools=[])
 import os
 print(GetBuildPath('..'))
 """)
 
 test.write(['sub', 'dir', 'SConstruct'], """
+DefaultEnvironment(tools=[])
 import os
-env = Environment(FOO='foo', BAR='bar')
+env = Environment(FOO='foo', BAR='bar', tools=[])
 print(env.GetBuildPath('../$FOO/$BAR'))
 """)
 
-test.run(arguments = '-C sub .',
-         stdout = "scons: Entering directory `%s'\n" % wpath_sub \
-             + test.wrap_stdout(read_str = '%s\n' % wpath,
-                                build_str = "scons: `.' is up to date.\n"))
-
-test.run(arguments = '-C sub -C dir .',
-         stdout = "scons: Entering directory `%s'\n" % wpath_sub_dir \
-             + test.wrap_stdout(read_str = '%s\n' % wpath_sub_foo_bar,
-                                build_str = "scons: `.' is up to date.\n"))
-
-test.run(arguments = ".",
-         stdout = test.wrap_stdout(read_str = 'SConstruct %s\n' % wpath,
-                                   build_str = "scons: `.' is up to date.\n"))
-
-test.run(arguments = '--directory=sub/dir .',
-         stdout = "scons: Entering directory `%s'\n" % wpath_sub_dir \
-             + test.wrap_stdout(read_str = '%s\n' % wpath_sub_foo_bar,
-                                build_str = "scons: `.' is up to date.\n"))
-
-test.run(arguments = '-C %s -C %s .' % (wpath_sub_dir, wpath_sub),
-         stdout = "scons: Entering directory `%s'\n" % wpath_sub \
-             + test.wrap_stdout(read_str = '%s\n' % wpath,
-                                build_str = "scons: `.' is up to date.\n"))
+test.run(arguments='-C sub .',
+         stdout="scons: Entering directory `%s'\n" % wpath_sub \
+             + test.wrap_stdout(read_str='%s\n' % wpath,
+                                build_str="scons: `.' is up to date.\n"))
+
+test.run(arguments='-C sub -C dir .',
+         stdout="scons: Entering directory `%s'\n" % wpath_sub_dir \
+             + test.wrap_stdout(read_str='%s\n' % wpath_sub_foo_bar,
+                                build_str="scons: `.' is up to date.\n"))
+
+test.run(arguments=".",
+         stdout=test.wrap_stdout(read_str='SConstruct %s\n' % wpath,
+                                   build_str="scons: `.' is up to date.\n"))
+
+test.run(arguments='--directory=sub/dir .',
+         stdout="scons: Entering directory `%s'\n" % wpath_sub_dir \
+             + test.wrap_stdout(read_str='%s\n' % wpath_sub_foo_bar,
+                                build_str="scons: `.' is up to date.\n"))
+
+test.run(arguments='-C %s -C %s .' % (wpath_sub_dir, wpath_sub),
+         stdout="scons: Entering directory `%s'\n" % wpath_sub \
+             + test.wrap_stdout(read_str='%s\n' % wpath,
+                                build_str="scons: `.' is up to date.\n"))
+
+import tempfile
+with tempfile.TemporaryDirectory() as full:
+    test.write([full, 'SConstruct'], """
+DefaultEnvironment(tools=[])
+import os
+print("SConstruct " + os.getcwd())
+""")
+    test.run(arguments='-C sub -C {} .'.format(full),
+             stdout="scons: Entering directory `{}'\n".format(full) \
+             + test.wrap_stdout(read_str='SConstruct {}\n'.format(full),
+                                build_str="scons: `.' is up to date.\n"))
 
 test.pass_test()
 
diff --git a/test/option--W.py b/test/option--W.py
index e29cd7c..3f68fbc 100644
--- a/test/option--W.py
+++ b/test/option--W.py
@@ -28,7 +28,9 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
-test.write('SConstruct', "")
+test.write('SConstruct', """\
+DefaultEnvironment(tools=[])
+""")
 
 test.option_not_yet_implemented('-W', 'foo .')
 
diff --git a/test/option--duplicate.py b/test/option--duplicate.py
index 2d21d74..91dc61c 100644
--- a/test/option--duplicate.py
+++ b/test/option--duplicate.py
@@ -39,6 +39,7 @@ python = TestSCons.python
 test = TestSCons.TestSCons()
 
 test.write('SConstruct', """
+DefaultEnvironment(tools=[])
 try:
     duplicate = ARGUMENTS['duplicate']
     SetOption('duplicate', duplicate)
diff --git a/test/option-f.py b/test/option-f.py
index 46e2686..94e7e46 100644
--- a/test/option-f.py
+++ b/test/option-f.py
@@ -35,16 +35,19 @@ test.subdir('subdir')
 subdir_BuildThis = os.path.join('subdir', 'Buildthis')
 
 test.write('SConscript', """
+DefaultEnvironment(tools=[])
 import os
 print("SConscript " + os.getcwd())
 """)
 
 test.write(subdir_BuildThis, """
+DefaultEnvironment(tools=[])
 import os
 print("subdir/BuildThis "+ os.getcwd())
 """)
 
 test.write('Build2', """
+DefaultEnvironment(tools=[])
 import os
 print("Build2 "+ os.getcwd())
 """)
@@ -84,6 +87,7 @@ test.run(arguments = '--sconstruct=%s .' % subdir_BuildThis,
                                    build_str = "scons: `.' is up to date.\n"))
 
 test.run(arguments = '-f - .', stdin = """
+DefaultEnvironment(tools=[])
 import os
 print("STDIN " + os.getcwd())
 """,
diff --git a/test/option-j.py b/test/option-j.py
index 278fd30..0b0078f 100644
--- a/test/option-j.py
+++ b/test/option-j.py
@@ -51,11 +51,10 @@ test = TestSCons.TestSCons()
 test.write('build.py', r"""
 import time
 import sys
-file = open(sys.argv[1], 'w')
-file.write(str(time.time()) + '\n')
-time.sleep(1)
-file.write(str(time.time()))
-file.close()
+with open(sys.argv[1], 'w') as f:
+    f.write(str(time.time()) + '\n')
+    time.sleep(1)
+    f.write(str(time.time()))
 """)
 
 test.subdir('foo')
@@ -65,11 +64,12 @@ foo you
 """)
 
 test.write('SConstruct', """
+DefaultEnvironment(tools=[])
 MyBuild = Builder(action = r'%(_python_)s build.py $TARGETS')
-env = Environment(BUILDERS = { 'MyBuild' : MyBuild })
+env = Environment(BUILDERS={'MyBuild': MyBuild}, tools=[])
 env.Tool('install')
-env.MyBuild(target = 'f1', source = 'f1.in')
-env.MyBuild(target = 'f2', source = 'f2.in')
+env.MyBuild(target='f1', source='f1.in')
+env.MyBuild(target='f2', source='f2.in')
 
 def copyn(env, target, source):
     import shutil
@@ -161,8 +161,9 @@ if sys.platform != 'win32' and sys.version_info[0] == 2:
 
 # Test SetJobs() with no -j:
 test.write('SConstruct', """
-MyBuild = Builder(action = r'%(_python_)s build.py $TARGETS')
-env = Environment(BUILDERS = { 'MyBuild' : MyBuild })
+DefaultEnvironment(tools=[])
+MyBuild = Builder(action=r'%(_python_)s build.py $TARGETS')
+env = Environment(BUILDERS={'MyBuild': MyBuild}, tools=[])
 env.Tool('install')
 env.MyBuild(target = 'f1', source = 'f1.in')
 env.MyBuild(target = 'f2', source = 'f2.in')
@@ -190,11 +191,12 @@ test.fail_test(not (start2 < finish1))
 
 # Test SetJobs() with -j:
 test.write('SConstruct', """
+DefaultEnvironment(tools=[])
 MyBuild = Builder(action = r'%(_python_)s build.py $TARGETS')
-env = Environment(BUILDERS = { 'MyBuild' : MyBuild })
+env = Environment(BUILDERS = {'MyBuild': MyBuild}, tools=[])
 env.Tool('install')
-env.MyBuild(target = 'f1', source = 'f1.in')
-env.MyBuild(target = 'f2', source = 'f2.in')
+env.MyBuild(target='f1', source='f1.in')
+env.MyBuild(target='f2', source='f2.in')
 
 def copyn(env, target, source):
     import shutil
diff --git a/test/option-k.py b/test/option-k.py
index 7a01ed3..4f4c86b 100644
--- a/test/option-k.py
+++ b/test/option-k.py
@@ -56,30 +56,30 @@ sys.exit(1)
 
 test.write(['work1', 'SConstruct'], """\
 DefaultEnvironment(tools=[])
-Succeed = Builder(action = r'%(_python_)s ../succeed.py $TARGETS')
-Fail = Builder(action = r'%(_python_)s ../fail.py $TARGETS')
-env = Environment(BUILDERS = { 'Succeed' : Succeed, 'Fail' : Fail })
-env.Fail(target = 'aaa.1', source = 'aaa.in')
-env.Succeed(target = 'aaa.out', source = 'aaa.1')
-env.Succeed(target = 'bbb.out', source = 'bbb.in')
+Succeed = Builder(action=r'%(_python_)s ../succeed.py $TARGETS')
+Fail = Builder(action=r'%(_python_)s ../fail.py $TARGETS')
+env = Environment(BUILDERS={'Succeed': Succeed, 'Fail': Fail}, tools=[])
+env.Fail(target='aaa.1', source='aaa.in')
+env.Succeed(target='aaa.out', source='aaa.1')
+env.Succeed(target='bbb.out', source='bbb.in')
 """ % locals())
 
 test.write(['work1', 'aaa.in'], "aaa.in\n")
 test.write(['work1', 'bbb.in'], "bbb.in\n")
 
-test.run(chdir = 'work1',
-         arguments = 'aaa.out bbb.out',
-         stderr = 'scons: *** [aaa.1] Error 1\n',
-         status = 2)
+test.run(chdir='work1',
+         arguments='aaa.out bbb.out',
+         stderr='scons: *** [aaa.1] Error 1\n',
+         status=2)
 
 test.must_not_exist(test.workpath('work1', 'aaa.1'))
 test.must_not_exist(test.workpath('work1', 'aaa.out'))
 test.must_not_exist(test.workpath('work1', 'bbb.out'))
 
-test.run(chdir = 'work1',
-         arguments = '-k aaa.out bbb.out',
-         stderr = 'scons: *** [aaa.1] Error 1\n',
-         status = 2)
+test.run(chdir='work1',
+         arguments='-k aaa.out bbb.out',
+         stderr='scons: *** [aaa.1] Error 1\n',
+         status=2)
 
 test.must_not_exist(test.workpath('work1', 'aaa.1'))
 test.must_not_exist(test.workpath('work1', 'aaa.out'))
@@ -88,9 +88,9 @@ test.must_match(['work1', 'bbb.out'], "succeed.py: bbb.out\n", mode='r')
 test.unlink(['work1', 'bbb.out'])
 
 test.run(chdir = 'work1',
-         arguments = '--keep-going aaa.out bbb.out',
-         stderr = 'scons: *** [aaa.1] Error 1\n',
-         status = 2)
+         arguments='--keep-going aaa.out bbb.out',
+         stderr='scons: *** [aaa.1] Error 1\n',
+         status=2)
 
 test.must_not_exist(test.workpath('work1', 'aaa.1'))
 test.must_not_exist(test.workpath('work1', 'aaa.out'))
@@ -104,9 +104,9 @@ Removed bbb.out
 scons: done cleaning targets.
 """
 
-test.run(chdir = 'work1',
-         arguments = '--clean --keep-going aaa.out bbb.out',
-         stdout = expect)
+test.run(chdir='work1',
+         arguments='--clean --keep-going aaa.out bbb.out',
+         stdout=expect)
 
 test.must_not_exist(test.workpath('work1', 'aaa.1'))
 test.must_not_exist(test.workpath('work1', 'aaa.out'))
@@ -120,9 +120,9 @@ test.must_not_exist(test.workpath('work1', 'bbb.out'))
 
 test.write(['work2', 'SConstruct'], """\
 DefaultEnvironment(tools=[])
-Succeed = Builder(action = r'%(_python_)s ../succeed.py $TARGETS')
-Fail = Builder(action = r'%(_python_)s ../fail.py $TARGETS')
-env = Environment(BUILDERS = { 'Succeed' : Succeed, 'Fail' : Fail })
+Succeed = Builder(action=r'%(_python_)s ../succeed.py $TARGETS')
+Fail = Builder(action=r'%(_python_)s ../fail.py $TARGETS')
+env = Environment(BUILDERS={'Succeed': Succeed, 'Fail': Fail}, tools=[])
 env.Fail('aaa.out', 'aaa.in')
 env.Succeed('bbb.out', 'aaa.out')
 env.Succeed('ccc.out', 'ccc.in')
@@ -132,11 +132,11 @@ env.Succeed('ddd.out', 'ccc.in')
 test.write(['work2', 'aaa.in'], "aaa.in\n")
 test.write(['work2', 'ccc.in'], "ccc.in\n")
 
-test.run(chdir = 'work2',
-         arguments = '-k .',
-         status = 2,
-         stderr = None,
-         stdout = """\
+test.run(chdir='work2',
+         arguments='-k .',
+         status=2,
+         stderr=None,
+         stdout="""\
 scons: Reading SConscript files ...
 scons: done reading SConscript files.
 scons: Building targets ...
@@ -178,7 +178,7 @@ test.write(['work3', 'SConstruct'], """\
 DefaultEnvironment(tools=[])
 Succeed = Builder(action = r'%(_python_)s ../succeed.py $TARGETS')
 Fail = Builder(action = r'%(_python_)s ../fail.py $TARGETS')
-env = Environment(BUILDERS = { 'Succeed' : Succeed, 'Fail' : Fail })
+env = Environment(BUILDERS = {'Succeed': Succeed, 'Fail': Fail}, tools=[])
 a = env.Fail('aaa.out', 'aaa.in')
 b = env.Succeed('bbb.out', 'bbb.in')
 c = env.Succeed('ccc.out', 'ccc.in')
diff --git a/test/option-n.py b/test/option-n.py
index f952428..2ec3fdc 100644
--- a/test/option-n.py
+++ b/test/option-n.py
@@ -57,11 +57,12 @@ with open(sys.argv[1], 'w') as ofp:
 """)
 
 test.write('SConstruct', """
-MyBuild = Builder(action = r'%(_python_)s build.py $TARGETS')
-env = Environment(BUILDERS = { 'MyBuild' : MyBuild })
+DefaultEnvironment(tools=[])
+MyBuild = Builder(action=r'%(_python_)s build.py $TARGETS')
+env = Environment(BUILDERS={'MyBuild': MyBuild}, tools=[])
 env.Tool('install')
-env.MyBuild(target = 'f1.out', source = 'f1.in')
-env.MyBuild(target = 'f2.out', source = 'f2.in')
+env.MyBuild(target='f1.out', source='f1.in')
+env.MyBuild(target='f2.out', source='f2.in')
 env.Install('install', 'f3.in')
 VariantDir('build', 'src', duplicate=1)
 SConscript('build/SConscript', "env")
@@ -69,7 +70,7 @@ SConscript('build/SConscript', "env")
 
 test.write(['src', 'SConscript'], """
 Import("env")
-env.MyBuild(target = 'f4.out', source = 'f4.in')
+env.MyBuild(target='f4.out', source='f4.in')
 """)
 
 test.write('f1.in', "f1.in\n")
@@ -83,7 +84,7 @@ expect = test.wrap_stdout("""\
 %(_python_)s build.py f2.out
 """ % locals())
 
-test.run(arguments = args, stdout = expect)
+test.run(arguments=args, stdout=expect)
 test.fail_test(not os.path.exists(test.workpath('f1.out')))
 test.fail_test(not os.path.exists(test.workpath('f2.out')))
 
@@ -169,8 +170,9 @@ test.fail_test(os.path.exists(test.workpath('build', 'f4.in')))
 test.subdir('configure')
 test.set_match_function(TestSCons.match_re_dotall)
 test.set_diff_function(TestSCons.diff_re)
-test.write('configure/SConstruct',
-"""def CustomTest(context):
+test.write('configure/SConstruct', """\
+DefaultEnvironment(tools=[])
+def CustomTest(context):
     def userAction(target,source,env):
         import shutil
         shutil.copyfile( str(source[0]), str(target[0]))
@@ -182,11 +184,11 @@ test.write('configure/SConstruct',
     context.Result(ok)
     return ok
 
-env = Environment()
-conf = Configure( env,
-                  custom_tests={'CustomTest':CustomTest},
-                  conf_dir="config.test",
-                  log_file="config.log" )
+env = Environment(tools=[])
+conf = Configure(env,
+                 custom_tests={'CustomTest':CustomTest},
+                 conf_dir="config.test",
+                 log_file="config.log")
 if not conf.CustomTest():
     Exit(1)
 else:
diff --git a/test/option-s.py b/test/option-s.py
index df7cd50..89a0c62 100644
--- a/test/option-s.py
+++ b/test/option-s.py
@@ -40,47 +40,49 @@ file.close()
 """)
 
 test.write('SConstruct', """
+DefaultEnvironment(tools=[])
 MyBuild = Builder(action = r'%(_python_)s build.py $TARGET')
 
 silent = ARGUMENTS.get('QUIET',0)
 if silent:
     SetOption('silent',True)
 
-env = Environment(BUILDERS = { 'MyBuild' : MyBuild })
-env.MyBuild(target = 'f1.out', source = 'f1.in')
-env.MyBuild(target = 'f2.out', source = 'f2.in')
+env = Environment(BUILDERS={'MyBuild': MyBuild}, tools=[])
+env.MyBuild(target='f1.out', source='f1.in')
+env.MyBuild(target='f2.out', source='f2.in')
 """ % locals())
 
 test.write('f1.in', "f1.in\n")
 test.write('f2.in', "f2.in\n")
 
-test.run(arguments = '-s f1.out f2.out', stdout = "")
+test.run(arguments='-s f1.out f2.out', stdout="")
 test.fail_test(not os.path.exists(test.workpath('f1.out')))
 test.fail_test(not os.path.exists(test.workpath('f2.out')))
 
 test.unlink('f1.out')
 test.unlink('f2.out')
 
-test.run(arguments = '--silent f1.out f2.out', stdout = "")
+test.run(arguments='--silent f1.out f2.out', stdout="")
 test.fail_test(not os.path.exists(test.workpath('f1.out')))
 test.fail_test(not os.path.exists(test.workpath('f2.out')))
 
 test.unlink('f1.out')
 test.unlink('f2.out')
 
-test.run(arguments = '--quiet f1.out f2.out', stdout = "")
+test.run(arguments='--quiet f1.out f2.out', stdout="")
 test.fail_test(not os.path.exists(test.workpath('f1.out')))
 test.fail_test(not os.path.exists(test.workpath('f2.out')))
 
 # -C should also be quiet Issue#2796
 test.subdir( 'sub' )
 test.write(['sub','SConstruct'],"")
-test.run(arguments = '-s -C sub', stdout = "" )
+test.run(arguments='-s -C sub', stdout="" )
 
 test.unlink('f1.out')
 test.unlink('f2.out')
 
-test.run(arguments = 'QUIET=1 f1.out f2.out', stdout = "scons: Reading SConscript files ...\nscons: done reading SConscript files.\n")
+test.run(arguments='QUIET=1 f1.out f2.out',
+         stdout="scons: Reading SConscript files ...\nscons: done reading SConscript files.\n")
 test.fail_test(not os.path.exists(test.workpath('f1.out')))
 test.fail_test(not os.path.exists(test.workpath('f2.out')))