http://scons.tigris.org/issues/show_bug.cgi?id=2365

Start the deprecation cycle for SourceCode() and its related factory functions.
Deprecation messages are added to the functions.  Regression tests are modified
to deal with the messages being generated.  Documentation is updated.

7 files changed, 134 insertions, 65 deletions

diff --git a/test/Deprecated/SourceCode/RCS/RCS_COCOM.py b/test/Deprecated/SourceCode/RCS/RCS_COCOM.py
index a1c18e5..20f0da6 100644
--- a/test/Deprecated/SourceCode/RCS/RCS_COCOM.py
+++ b/test/Deprecated/SourceCode/RCS/RCS_COCOM.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -28,13 +27,23 @@ __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
 Test setting the $RCS_COCOM variable.
 """
 
-import os.path
+import os
 
 import TestSCons
 
 _python_ = TestSCons._python_
 
-test = TestSCons.TestSCons()
+test = TestSCons.TestSCons(match = TestSCons.match_re_dotall)
+
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+warn_rcs = test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+msg_sc = """SourceCode() has been deprecated and there is no replacement.
+\tIf you need this function, please contact dev@scons.tigris.org."""
+warn_sc = test.deprecated_wrap(msg_sc)
 
 test.subdir('RCS', ['RCS', 'sub'], 'sub')
 
@@ -56,6 +65,7 @@ for f in sys.argv[1:]:
 """)
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 def cat(env, source, target):
     target = str(target[0])
     f = open(target, "wb")
@@ -89,11 +99,11 @@ test.write(['RCS', 'sub', 'ddd.in'], "RCS/sub/ddd.in\n")
 test.write(['sub', 'eee.in'], "checked-out sub/eee.in\n")
 test.write(['RCS', 'sub', 'fff.in'], "RCS/sub/fff.in\n")
 
-test.run(arguments = '.',
-         stdout = test.wrap_stdout(read_str = """\
+read_str = """\
 %(_python_)s my-rcs-co.py %(sub_SConscript)s
-""" % locals(),
-                                   build_str = """\
+""" % locals()
+
+build_str = """\
 %(_python_)s my-rcs-co.py aaa.in
 cat(["aaa.out"], ["aaa.in"])
 cat(["bbb.out"], ["bbb.in"])
@@ -106,7 +116,13 @@ cat(["%(sub_eee_out)s"], ["%(sub_eee_in)s"])
 %(_python_)s my-rcs-co.py %(sub_fff_in)s
 cat(["%(sub_fff_out)s"], ["%(sub_fff_in)s"])
 cat(["%(sub_all)s"], ["%(sub_ddd_out)s", "%(sub_eee_out)s", "%(sub_fff_out)s"])
-""" % locals()))
+""" % locals()
+
+stdout = test.wrap_stdout(read_str = read_str, build_str = build_str)
+
+test.run(arguments = '.',
+         stdout = TestSCons.re_escape(stdout),
+         stderr = warn_rcs + warn_sc)
 
 test.must_match('all',
                 "RCS/aaa.in\nchecked-out bbb.in\nRCS/ccc.in\n")
@@ -115,8 +131,6 @@ test.must_match(['sub', 'all'],
                 "RCS/sub/ddd.in\nchecked-out sub/eee.in\nRCS/sub/fff.in\n")
 
 
-
-#
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/RCS_COCOMSTR.py b/test/Deprecated/SourceCode/RCS/RCS_COCOMSTR.py
index ee3ba15..3626376 100644
--- a/test/Deprecated/SourceCode/RCS/RCS_COCOMSTR.py
+++ b/test/Deprecated/SourceCode/RCS/RCS_COCOMSTR.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -34,7 +33,17 @@ import TestSCons
 
 _python_ = TestSCons._python_
 
-test = TestSCons.TestSCons()
+test = TestSCons.TestSCons(match = TestSCons.match_re_dotall)
+
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+warn_rcs = test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+msg_sc = """SourceCode() has been deprecated and there is no replacement.
+\tIf you need this function, please contact dev@scons.tigris.org."""
+warn_sc = test.deprecated_wrap(msg_sc)
 
 test.subdir('RCS', ['RCS', 'sub'], 'sub')
 
@@ -56,6 +65,7 @@ for f in sys.argv[1:]:
 """)
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 def cat(env, source, target):
     target = str(target[0])
     f = open(target, "wb")
@@ -90,11 +100,11 @@ test.write(['RCS', 'sub', 'ddd.in'], "RCS/sub/ddd.in\n")
 test.write(['sub', 'eee.in'], "checked-out sub/eee.in\n")
 test.write(['RCS', 'sub', 'fff.in'], "RCS/sub/fff.in\n")
 
-test.run(arguments = '.',
-         stdout = test.wrap_stdout(read_str = """\
+read_str = """\
 Checking out %(sub_SConscript)s from our fake RCS
-""" % locals(),
-                                   build_str = """\
+""" % locals()
+
+build_str = """\
 Checking out aaa.in from our fake RCS
 cat(["aaa.out"], ["aaa.in"])
 cat(["bbb.out"], ["bbb.in"])
@@ -107,7 +117,13 @@ cat(["%(sub_eee_out)s"], ["%(sub_eee_in)s"])
 Checking out %(sub_fff_in)s from our fake RCS
 cat(["%(sub_fff_out)s"], ["%(sub_fff_in)s"])
 cat(["%(sub_all)s"], ["%(sub_ddd_out)s", "%(sub_eee_out)s", "%(sub_fff_out)s"])
-""" % locals()))
+""" % locals()
+
+stdout = test.wrap_stdout(read_str = read_str, build_str = build_str)
+
+test.run(arguments = '.',
+         stdout = TestSCons.re_escape(stdout),
+         stderr = warn_rcs + warn_sc)
 
 test.must_match('all',
                 "RCS/aaa.in\nchecked-out bbb.in\nRCS/ccc.in\n")
@@ -116,8 +132,6 @@ test.must_match(['sub', 'all'],
                 "RCS/sub/ddd.in\nchecked-out sub/eee.in\nRCS/sub/fff.in\n")
 
 
-
-#
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/changed.py b/test/Deprecated/SourceCode/RCS/changed.py
index d451be0..14c80bd 100644
--- a/test/Deprecated/SourceCode/RCS/changed.py
+++ b/test/Deprecated/SourceCode/RCS/changed.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -30,7 +29,17 @@ Test explicit checkouts from local RCS files.
 
 import TestSCons
 
-test = TestSCons.TestSCons()
+test = TestSCons.TestSCons(match = TestSCons.match_re_dotall)
+
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+warn_rcs = test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+msg_sc = """SourceCode() has been deprecated and there is no replacement.
+\tIf you need this function, please contact dev@scons.tigris.org."""
+warn_sc = test.deprecated_wrap(msg_sc)
 
 rcs = test.where_is('rcs')
 if not rcs:
@@ -45,7 +54,6 @@ if not co:
     test.skip_test("Could not find `co' command, skipping test(s).\n")
 
 
-
 main_cpp_contents = """\
 #include <stdio.h>
 #include <stdlib.h>
@@ -62,8 +70,8 @@ test.write('main.c', main_cpp_contents % 1)
 test.run(program = ci, arguments = '-f -tmain.c main.c', stderr = None)
 
 
-
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 import os
 for key in ['LOGNAME', 'USERNAME', 'USER']:
     logname = os.environ.get(key)
@@ -76,22 +84,20 @@ env2 = env.Clone()
 env2.Program('main.exe', 'main.c')
 """)
 
-test.run()
+test.run(stderr = warn_rcs + warn_sc)
 
 test.run(program = test.workpath('main.exe'), stdout = "main.c 1\n")
 
-
-
 test.run(program = co, arguments = '-l main.c', stderr = None)
 
+
 test.write('main.c', main_cpp_contents % 2)
 
-test.not_up_to_date(arguments = 'main.exe')
+test.not_up_to_date(arguments = 'main.exe', stderr = warn_rcs + warn_sc)
 
 test.run(program = test.workpath('main.exe'), stdout = "main.c 2\n")
 
 
-
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/diskcheck.py b/test/Deprecated/SourceCode/RCS/diskcheck.py
index 4e7dd24..7183975 100644
--- a/test/Deprecated/SourceCode/RCS/diskcheck.py
+++ b/test/Deprecated/SourceCode/RCS/diskcheck.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -34,6 +33,13 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+
 rcs = test.where_is('rcs')
 if not rcs:
     test.skip_test("Could not find 'rcs'; skipping test(s).\n")
@@ -43,7 +49,6 @@ if not ci:
     test.skip_test("Could not find 'ci'; skipping test(s).\n")
 
 
-
 sub_RCS = os.path.join('sub', 'RCS')
 sub_SConscript = os.path.join('sub', 'SConscript')
 sub_all = os.path.join('sub', 'all')
@@ -87,6 +92,7 @@ test.no_result(os.path.exists(test.workpath('sub', 'bbb.in')))
 test.no_result(os.path.exists(test.workpath('sub', 'ccc.in')))
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 import os
 for key in ['LOGNAME', 'USERNAME', 'USER']:
     logname = os.environ.get(key)
@@ -115,7 +121,7 @@ test.write('bbb.in', "checked-out bbb.in\n")
 test.write(['sub', 'eee.in'], "checked-out sub/eee.in\n")
 
 sub_SConscript = os.path.join('sub', 'SConscript')
-SConstruct_file_line = test.python_file_line(test.workpath('SConstruct'), 22)[:-1]
+SConstruct_file_line = test.python_file_line(test.workpath('SConstruct'), 23)[:-1]
 
 expect = """\
 
@@ -128,11 +134,11 @@ test.run(status=2, stderr=expect)
 
 test.run(arguments = '--diskcheck=match,sccs', status=2, stderr=expect)
 
-test.run(arguments = '--diskcheck=rcs',
-         stdout = test.wrap_stdout(read_str = """\
+read_str = """\
 co -l %(sub_SConscript)s
-""" % locals(),
-                                   build_str = """\
+""" % locals()
+
+build_str = """\
 co -l aaa.in
 cat(["aaa.out"], ["aaa.in"])
 cat(["bbb.out"], ["bbb.in"])
@@ -145,8 +151,11 @@ cat(["%(sub_eee_out)s"], ["%(sub_eee_in)s"])
 co -l %(sub_fff_in)s
 cat(["%(sub_fff_out)s"], ["%(sub_fff_in)s"])
 cat(["%(sub_all)s"], ["%(sub_ddd_out)s", "%(sub_eee_out)s", "%(sub_fff_out)s"])
-""" % locals()),
-         stderr = """\
+""" % locals()
+
+stdout = test.wrap_stdout(read_str = read_str, build_str = build_str)
+
+stderr = """\
 %(sub_RCS)s/SConscript,v  -->  %(sub_SConscript)s
 revision 1.1 (locked)
 done
@@ -162,7 +171,9 @@ done
 %(sub_RCS)s/fff.in,v  -->  %(sub_fff_in)s
 revision 1.1 (locked)
 done
-""" % locals())
+""" % locals()
+
+test.run(arguments = '--diskcheck=rcs', stdout = stdout, stderr = stderr)
 
 # Checking things back out of RCS apparently messes with the line
 # endings, so read the result files in non-binary mode.
@@ -182,8 +193,6 @@ test.must_be_writable(test.workpath('sub', 'ddd.in'))
 test.must_be_writable(test.workpath('sub', 'fff.in'))
 
 
-
-#
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/explicit.py b/test/Deprecated/SourceCode/RCS/explicit.py
index 75eb189..53c336a 100644
--- a/test/Deprecated/SourceCode/RCS/explicit.py
+++ b/test/Deprecated/SourceCode/RCS/explicit.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -32,7 +31,17 @@ import os
 
 import TestSCons
 
-test = TestSCons.TestSCons()
+test = TestSCons.TestSCons(match = TestSCons.match_re_dotall)
+
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+warn_rcs = test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+msg_sc = """SourceCode() has been deprecated and there is no replacement.
+\tIf you need this function, please contact dev@scons.tigris.org."""
+warn_sc = test.deprecated_wrap(msg_sc)
 
 rcs = test.where_is('rcs')
 if not rcs:
@@ -43,7 +52,6 @@ if not ci:
     test.skip_test("Could not find `ci' command, skipping test(s).\n")
 
 
-
 test.subdir('sub')
 
 sub_RCS = os.path.join('sub', 'RCS')
@@ -87,6 +95,7 @@ test.no_result(os.path.exists(test.workpath('sub', 'eee.in')))
 test.no_result(os.path.exists(test.workpath('sub', 'fff.in')))
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 import os
 for key in ['LOGNAME', 'USERNAME', 'USER']:
     logname = os.environ.get(key)
@@ -115,11 +124,11 @@ test.write('bbb.in', "checked-out bbb.in\n")
 
 test.write(['sub', 'eee.in'], "checked-out sub/eee.in\n")
 
-test.run(arguments = '.',
-         stdout = test.wrap_stdout(read_str = """\
+read_str = """\
 co -q %(sub_SConscript)s
-""" % locals(),
-                                   build_str = """\
+""" % locals()
+
+build_str = """\
 co -q aaa.in
 cat(["aaa.out"], ["aaa.in"])
 cat(["bbb.out"], ["bbb.in"])
@@ -132,7 +141,13 @@ cat(["%(sub_eee_out)s"], ["%(sub_eee_in)s"])
 co -q %(sub_fff_in)s
 cat(["%(sub_fff_out)s"], ["%(sub_fff_in)s"])
 cat(["%(sub_all)s"], ["%(sub_ddd_out)s", "%(sub_eee_out)s", "%(sub_fff_out)s"])
-""" % locals()))
+""" % locals()
+
+stdout = test.wrap_stdout(read_str = read_str, build_str = build_str)
+
+test.run(arguments = '.',
+         stdout = TestSCons.re_escape(stdout),
+         stderr = warn_rcs + warn_sc)
 
 # Checking things back out of RCS apparently messes with the line
 # endings, so read the result files in non-binary mode.
@@ -152,8 +167,6 @@ test.must_not_be_writable(test.workpath('sub', 'ddd.in'))
 test.must_not_be_writable(test.workpath('sub', 'fff.in'))
 
 
-
-#
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/implicit.py b/test/Deprecated/SourceCode/RCS/implicit.py
index 6677c55..ed1f1a2 100644
--- a/test/Deprecated/SourceCode/RCS/implicit.py
+++ b/test/Deprecated/SourceCode/RCS/implicit.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -32,6 +31,13 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+
 rcs = test.where_is('rcs')
 if not rcs:
     test.skip_test("Could not find 'rcs'; skipping test(s).\n")
@@ -45,7 +51,6 @@ if not co:
     test.skip_test("Could not find 'co'; skipping test(s).\n")
 
 
-
 test.subdir('RCS')
 
 test.write('foo.c', """\
@@ -70,6 +75,7 @@ test.run(program = ci,
          stderr = None)
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 DefaultEnvironment(RCS_CO = r'%s')
 env = Environment()
 env.Program('foo.c')
@@ -85,8 +91,6 @@ done
 """)
 
 
-
-#
 test.pass_test()
 
 # Local Variables:
diff --git a/test/Deprecated/SourceCode/RCS/transparent.py b/test/Deprecated/SourceCode/RCS/transparent.py
index 2ebde9a..67d0512 100644
--- a/test/Deprecated/SourceCode/RCS/transparent.py
+++ b/test/Deprecated/SourceCode/RCS/transparent.py
@@ -20,7 +20,6 @@
 # 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__"
 
@@ -34,6 +33,13 @@ import TestSCons
 
 test = TestSCons.TestSCons()
 
+test.write('SConscript', """
+Environment(tools = ['RCS']).RCS()
+""")
+
+msg_rcs = """The RCS() factory is deprecated and there is no replacement."""
+test.deprecated_fatal('deprecated-build-dir', msg_rcs)
+
 rcs = test.where_is('rcs')
 if not rcs:
     test.skip_test("Could not find 'rcs'; skipping test(s).\n")
@@ -43,7 +49,6 @@ if not ci:
     test.skip_test("Could not find 'ci'; skipping test(s).\n")
 
 
-
 sub_RCS = os.path.join('sub', 'RCS')
 sub_SConscript = os.path.join('sub', 'SConscript')
 sub_all = os.path.join('sub', 'all')
@@ -87,6 +92,7 @@ test.no_result(os.path.exists(test.workpath('sub', 'bbb.in')))
 test.no_result(os.path.exists(test.workpath('sub', 'ccc.in')))
 
 test.write('SConstruct', """
+SetOption('warn', 'deprecated-source-code')
 import os
 for key in ['LOGNAME', 'USERNAME', 'USER']:
     logname = os.environ.get(key)
@@ -113,11 +119,11 @@ test.write('bbb.in', "checked-out bbb.in\n")
 
 test.write(['sub', 'eee.in'], "checked-out sub/eee.in\n")
 
-test.run(arguments = '.',
-         stdout = test.wrap_stdout(read_str = """\
+read_str = """\
 co -l %(sub_SConscript)s
-""" % locals(),
-                                   build_str = """\
+""" % locals()
+
+build_str = """\
 co -l aaa.in
 cat(["aaa.out"], ["aaa.in"])
 cat(["bbb.out"], ["bbb.in"])
@@ -130,8 +136,11 @@ cat(["%(sub_eee_out)s"], ["%(sub_eee_in)s"])
 co -l %(sub_fff_in)s
 cat(["%(sub_fff_out)s"], ["%(sub_fff_in)s"])
 cat(["%(sub_all)s"], ["%(sub_ddd_out)s", "%(sub_eee_out)s", "%(sub_fff_out)s"])
-""" % locals()),
-         stderr = """\
+""" % locals()
+
+stdout = test.wrap_stdout(read_str = read_str, build_str = build_str)
+
+stderr = """\
 %(sub_RCS)s/SConscript,v  -->  %(sub_SConscript)s
 revision 1.1 (locked)
 done
@@ -147,7 +156,9 @@ done
 %(sub_RCS)s/fff.in,v  -->  %(sub_fff_in)s
 revision 1.1 (locked)
 done
-""" % locals())
+""" % locals()
+
+test.run(arguments = '.', stdout = stdout, stderr = stderr)
 
 # Checking things back out of RCS apparently messes with the line
 # endings, so read the result files in non-binary mode.
@@ -167,8 +178,6 @@ test.must_be_writable(test.workpath('sub', 'ddd.in'))
 test.must_be_writable(test.workpath('sub', 'fff.in'))
 
 
-
-#
 test.pass_test()
 
 # Local Variables: