diff --git a/CHANGES.txt b/CHANGES.txt index bfd3eb18a9..b991c5dd54 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -131,6 +131,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - zip tool now uses zipfile module's "from_file" method to populate ZipInfo records, rather than doing manually. - Some cleanups in Subst.py. Functionality does not change. + - Deprecate the legacy job scheduler and feature flag. The feature flag + is renamed to "legacy_sched_deprecated". - Reference manual improvements: * More clarifications in Builder Methods section. * Clarify VariantDir behavior when switching from duplicate=True (the diff --git a/RELEASE.txt b/RELEASE.txt index 50438076cb..02565fa456 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -28,6 +28,13 @@ DEPRECATED FUNCTIONALITY - Deprecated using signature-file-per-directory (aka old-style SConsign) via the SConsignFile(name=None) call. +- The legacy job scheduler, which was superseded by a new scheduler in + SCons 4.7 but remained available as a fallback, is deprecated and + will be removed in the next release. The --experimental feature flag + to select the legacy scheduler is renamed to "legacy_sched_deprecated" + to give a clear indication of the status change; the flag will also + be removed in the next release. + REMOVED FUNCTIONALITY --------------------- diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py index 74949c0599..b6b23782d1 100644 --- a/SCons/Script/SConsOptions.py +++ b/SCons/Script/SConsOptions.py @@ -42,7 +42,8 @@ diskcheck_all = SCons.Node.FS.diskcheck_types() -experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched'} +# legacy_sched renamed legacy_sched_deprecated in 4.11, scheduled for removal +experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched_deprecated'} def diskcheck_convert(value): diff --git a/SCons/Taskmaster/Job.py b/SCons/Taskmaster/Job.py index a24742ed65..b538b27490 100644 --- a/SCons/Taskmaster/Job.py +++ b/SCons/Taskmaster/Job.py @@ -72,12 +72,15 @@ class Jobs: """ def __init__(self, num, taskmaster) -> None: - """ - Create 'num' jobs using the given taskmaster. The exact implementation - used varies with the number of jobs requested and the state of the `legacy_sched` flag - to `--experimental`. - """ + """Create *num* jobs using the given taskmaster. + The exact implementation used varies with the number of jobs + requested and the scheduler selected - the old scheduler is + available through CLI ``--experimental=legacy_sched_deprecated``. + + .. versionchanged: NEXT_RELEASE + Legacy scheduler deprecated, flag renamed to ``legacy_sched_deprecated`` + """ # Importing GetOption here instead of at top of file to avoid # circular imports # pylint: disable=import-outside-toplevel @@ -88,7 +91,7 @@ def __init__(self, num, taskmaster) -> None: stack_size = default_stack_size experimental_option = GetOption('experimental') or [] - if 'legacy_sched' in experimental_option: + if 'legacy_sched_deprecated' in experimental_option: if num > 1: self.job = LegacyParallel(taskmaster, num, stack_size) else: diff --git a/SCons/Taskmaster/JobTests.py b/SCons/Taskmaster/JobTests.py index 59cfe78adc..93d1ce0254 100644 --- a/SCons/Taskmaster/JobTests.py +++ b/SCons/Taskmaster/JobTests.py @@ -313,7 +313,7 @@ def get(self): try: taskmaster = Taskmaster(3, self, SleepTask) - OptionsParser.values.experimental.append('legacy_sched') + OptionsParser.values.experimental.append('legacy_sched_deprecated') jobs = SCons.Taskmaster.Job.Jobs(2, taskmaster) OptionsParser.values.experimental.pop() jobs.run() @@ -529,7 +529,7 @@ def runTest(self) -> None: self._test_seq(1) # Now run test with LegacyParallel - OptionsParser.values.experimental=['legacy_sched'] + OptionsParser.values.experimental=['legacy_sched_deprecated'] self._test_seq(1) class ParallelTaskTest(_SConsTaskTest): @@ -538,7 +538,7 @@ def runTest(self) -> None: self._test_seq(num_jobs) # Now run test with LegacyParallel - OptionsParser.values.experimental=['legacy_sched'] + OptionsParser.values.experimental=['legacy_sched_deprecated'] self._test_seq(num_jobs) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index a689960bac..1d2d3b2324 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1258,14 +1258,33 @@ the mechanisms in the specified order. the special tokens all or none. A comma-separated string can be used to select multiple features. The default setting is none. - Current available features are: - ninja (New in version 4.2), - legacy_sched (New in version 4.6.0). + + Current available features are + ninja (new in version 4.2) + and + legacy_sched_deprecated + (new in, and deprecated since, version NEXT_RELEASE). + + + The legacy scheduler is not strictly an experimental feature. + The feature flag selects the job scheduler which was + the &SCons; default prior to version 4.7. + The feature flag was introduced as legacy_sched + in version 4.7. + The legacy scheduler is due to be removed in a future release, + so the feature flag is now deprecated. In version NEXT_RELEASE, + it was renamed to legacy_sched_deprecated, + so that existing users will receive a signal - due to the nature + of experimental feature flags it is not possible to use the + standard &SCons; deprecation warning mechanism here. + - No Support offered for any features or tools enabled by this flag. + Experimental features come with no compatibility promises - + a given feature could change significantly in a future release, + or disappear completely. - New in version 4.2 (experimental). + Option added in version 4.2. diff --git a/test/Interactive/taskmastertrace.py b/test/Interactive/taskmastertrace.py index c7196f6e84..6066fe10a2 100644 --- a/test/Interactive/taskmastertrace.py +++ b/test/Interactive/taskmastertrace.py @@ -46,7 +46,7 @@ test.write('foo.in', "foo.in 1\n") -scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched') +scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched_deprecated') scons.send("build foo.out 1\n") diff --git a/test/option/option--experimental.py b/test/option/option--experimental.py index 2b1bda53c2..d17d1aaf38 100755 --- a/test/option/option--experimental.py +++ b/test/option/option--experimental.py @@ -36,13 +36,13 @@ tests = [ ('.', []), ('--experimental=ninja', ['ninja']), - ('--experimental=legacy_sched', ['legacy_sched']), - ('--experimental=all', ['legacy_sched', 'ninja', 'transporter', 'warp_speed']), + ('--experimental=legacy_sched_deprecated', ['legacy_sched_deprecated']), + ('--experimental=all', ['legacy_sched_deprecated', 'ninja', 'transporter', 'warp_speed']), ('--experimental=none', []), ] for args, exper in tests: - read_string = """All Features=legacy_sched,ninja,transporter,warp_speed + read_string = """All Features=legacy_sched_deprecated,ninja,transporter,warp_speed Experimental=%s """ % (exper) test.run(arguments=args, @@ -51,7 +51,7 @@ test.run(arguments='--experimental=warp_drive', stderr="""usage: scons [OPTIONS] [VARIABLES] [TARGETS] -SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched','ninja','transporter','warp_speed') +SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched_deprecated','ninja','transporter','warp_speed') """, status=2) diff --git a/test/option/taskmastertrace.py b/test/option/taskmastertrace.py index 5b1047bbec..223ca011cc 100755 --- a/test/option/taskmastertrace.py +++ b/test/option/taskmastertrace.py @@ -42,7 +42,7 @@ expect_stdout = test.wrap_stdout(test.read('taskmaster_expected_stdout_1.txt', mode='r')) -test.run(arguments='--experimental=legacy_sched --taskmastertrace=- .', stdout=expect_stdout) +test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=- .', stdout=expect_stdout) test.run(arguments='-c .') @@ -52,7 +52,7 @@ """) # Test LegacyParallel Job implementation -test.run(arguments='--experimental=legacy_sched --taskmastertrace=trace.out .', stdout=expect_stdout) +test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=trace.out .', stdout=expect_stdout) test.must_match_file('trace.out', 'taskmaster_expected_file_1.txt', mode='r') # Test NewParallel Job implementation