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