Allow deprecating an option for a new one

6 files changed, 62 insertions, 4 deletions

diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md
index 4b66cbf..b8f1407 100644
--- a/docs/markdown/Build-options.md
+++ b/docs/markdown/Build-options.md
@@ -149,6 +149,21 @@ option('o4', type: 'feature', deprecated: {'true': 'enabled', 'false': 'disabled
 option('o5', type: 'boolean', deprecated: {'enabled': 'true', 'disabled': 'false', 'auto': 'false'})
 ```
 
+Since *0.63.0* the `deprecated` keyword argument can take the name of a new option
+that replace this option. In that case, setting a value on the deprecated option
+will set the value on both the old and new names, assuming they accept the same
+values.
+
+```meson
+# A boolean option has been replaced by a feature with another name, old true/false values
+# are accepted by the new option for backward compatibility.
+option('o6', type: 'boolean', value: 'true', deprecated: 'o7')
+option('o7', type: 'feature', value: 'enabled', deprecated: {'true': 'enabled', 'false': 'disabled'})
+
+# A project option is replaced by a module option
+option('o8', type: 'string', value: '', deprecated: 'python.platlibdir')
+```
+
 ## Using build options
 
 ```meson
diff --git a/docs/markdown/snippets/deprecated_for_option.md b/docs/markdown/snippets/deprecated_for_option.md
new file mode 100644
index 0000000..c0a012c
--- /dev/null
+++ b/docs/markdown/snippets/deprecated_for_option.md
@@ -0,0 +1,16 @@
+## Deprecate an option and replace it with a new one
+
+The `deprecated` keyword argument can now take the name of a new option
+that replace this option. In that case, setting a value on the deprecated option
+will set the value on both the old and new names, assuming they accept the same
+values.
+
+```meson
+# A boolean option has been replaced by a feature with another name, old true/false values
+# are accepted by the new option for backward compatibility.
+option('o1', type: 'boolean', value: 'true', deprecated: 'o2')
+option('o2', type: 'feature', value: 'enabled', deprecated: {'true': 'enabled', 'false': 'disabled'})
+
+# A project option is replaced by a module option
+option('o3', type: 'string', value: '', deprecated: 'python.platlibdir')
+```
diff --git a/mesonbuild/coredata.py b/mesonbuild/coredata.py
index cf06ac6..b9a4828 100644
--- a/mesonbuild/coredata.py
+++ b/mesonbuild/coredata.py
@@ -81,7 +81,7 @@ class UserOption(T.Generic[_T], HoldableObject):
         if not isinstance(yielding, bool):
             raise MesonException('Value of "yielding" must be a boolean.')
         self.yielding = yielding
-        self.deprecated: T.Union[bool, T.Dict[str, str], T.List[str]] = False
+        self.deprecated: T.Union[bool, str, T.Dict[str, str], T.List[str]] = False
 
     def listify(self, value: T.Any) -> T.List[T.Any]:
         return [value]
@@ -660,6 +660,19 @@ class CoreData:
                 return v
             newvalue = [replace(v) for v in opt.listify(value)]
             value = ','.join(newvalue)
+        elif isinstance(opt.deprecated, str):
+            # Option is deprecated and replaced by another. Note that a project
+            # option could be replaced by a built-in or module option, which is
+            # why we use OptionKey.from_string(newname) instead of
+            # key.evolve(newname). We set the value on both the old and new names,
+            # assuming they accept the same value. That could for example be
+            # achieved by adding the values from old option as deprecated on the
+            # new option, for example in the case of boolean option is replaced
+            # by a feature option with a different name.
+            newname = opt.deprecated
+            newkey = OptionKey.from_string(newname).evolve(subproject=key.subproject)
+            mlog.deprecation(f'Option {key.name!r} is replaced by {newname!r}')
+            self.set_option(newkey, value)
 
         opt.set_value(value)
 
diff --git a/mesonbuild/optinterpreter.py b/mesonbuild/optinterpreter.py
index eeb7cf8..549d564 100644
--- a/mesonbuild/optinterpreter.py
+++ b/mesonbuild/optinterpreter.py
@@ -32,7 +32,7 @@ if T.TYPE_CHECKING:
         'value': object,
         'min': T.Optional[int],
         'max': T.Optional[int],
-        'deprecated': T.Union[bool, T.Dict[str, str], T.List[str]],
+        'deprecated': T.Union[bool, str, T.Dict[str, str], T.List[str]],
         })
     ParserArgs = TypedDict('ParserArgs', {
         'yield': bool,
@@ -153,7 +153,7 @@ class OptionInterpreter:
                   KwargInfo('value', object),
                   KwargInfo('min', (int, type(None))),
                   KwargInfo('max', (int, type(None))),
-                  KwargInfo('deprecated', (bool, ContainerTypeInfo(dict, str), ContainerTypeInfo(list, str)),
+                  KwargInfo('deprecated', (bool, str, ContainerTypeInfo(dict, str), ContainerTypeInfo(list, str)),
                             default=False, since='0.60.0')
                   )
     @typed_pos_args('option', str)
@@ -177,7 +177,8 @@ class OptionInterpreter:
         parser_kwargs = {k: v for k, v in kwargs.items() if k in known_parser_kwargs and v is not None}
         opt = parser(description, T.cast('ParserArgs', parser_kwargs))
         opt.deprecated = kwargs['deprecated']
-
+        if isinstance(opt.deprecated, str):
+            FeatureNew.single_use('String value to "deprecated" keyword argument', '0.63.0', self.subproject)
         if key in self.options:
             mlog.deprecation(f'Option {opt_name} already exists.')
         self.options[key] = opt
diff --git a/test cases/common/247 deprecated option/meson.build b/test cases/common/247 deprecated option/meson.build
index 5102fd0..4c734ee 100644
--- a/test cases/common/247 deprecated option/meson.build
+++ b/test cases/common/247 deprecated option/meson.build
@@ -5,6 +5,8 @@ project('deprecated options',
     'o3=a,b',
     'o4=true',
     'o5=auto',
+    'o6=false',
+    'o8=/foo',
   ]
 )
 
@@ -13,3 +15,6 @@ assert(get_option('o2') == ['a', 'b'])
 assert(get_option('o3') == ['c', 'b'])
 assert(get_option('o4').enabled())
 assert(get_option('o5') == false)
+assert(get_option('o6') == false)
+assert(get_option('o7').disabled())
+assert(get_option('python.platlibdir') == '/foo')
diff --git a/test cases/common/247 deprecated option/meson_options.txt b/test cases/common/247 deprecated option/meson_options.txt
index 5814531..9665501 100644
--- a/test cases/common/247 deprecated option/meson_options.txt
+++ b/test cases/common/247 deprecated option/meson_options.txt
@@ -13,3 +13,11 @@ option('o4', type: 'feature', deprecated: {'true': 'enabled', 'false': 'disabled
 
 # A feature option has been replaced by a boolean, enabled/disabled/auto values are remapped.
 option('o5', type: 'boolean', deprecated: {'enabled': 'true', 'disabled': 'false', 'auto': 'false'})
+
+# A boolean option has been replaced by a feature with another name, old true/false values
+# are accepted by the new option for backward compatibility.
+option('o6', type: 'boolean', value: 'true', deprecated: 'o7')
+option('o7', type: 'feature', value: 'enabled', deprecated: {'true': 'enabled', 'false': 'disabled'})
+
+# A project option is replaced by a module option
+option('o8', type: 'string', value: '', deprecated: 'python.platlibdir')