Deprecate get_option('buildtype'), use optimization/debug insteadnirbheek/deprecate-get-option-buildtype

This was long overdue.

Closes https://github.com/mesonbuild/meson/issues/5814

3 files changed, 43 insertions, 2 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index ea5ad70e7..8bda7ca00 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -103,7 +103,10 @@ two-way mapping:
 | release        | false | 3            |
 | minsize        | true  | s            |
 
-All other combinations of `debug` and `optimization` set `buildtype` to `'custom'`.
+All other combinations of `debug` and `optimization` set `buildtype` to
+`'custom'`. Hence, inside your build files when using `get_option()`, you
+should always fetch `optimization` and/or `debug`. *Since 0.54*,
+`get_option('builtype')` is deprecated.
 
 ## Base options
 
diff --git a/docs/markdown/snippets/deprecate_get_option_buildtype.md b/docs/markdown/snippets/deprecate_get_option_buildtype.md
new file mode 100644
index 000000000..ed0474029
--- /dev/null
+++ b/docs/markdown/snippets/deprecate_get_option_buildtype.md
@@ -0,0 +1,35 @@
+## `get_option('buildtype')` is deprecated by `optimization` and `debug`
+
+Build files have been doing anti-patterns such as checking whether debugging is
+enabled with `get_option('buildtype').startswith('debug')`. This has been
+incorrect *[since 0.48]* where we added separate options for `-Doptimization`
+(choice) and `-Ddebug` (boolean) which also set `buildtype` for
+backward-compatibility.
+
+However, many [combinations of these two options](Builtin-options.html#build-type-options)
+such as `-Doptimization=g -Ddebug=true` actually set **`buildtype='custom'`**.
+
+The correct way to check for debugging is to simply do `get_option('debug')`.
+For checking whether a 'release' build is being done, you can do something like:
+
+```
+if not get_option('debug') and get_option('optimization') == '3'
+    message('Doing a release build')
+fi
+```
+
+Depending on why you're checking for that, you may want to do something like:
+
+```
+if not get_option('debug') and get_option('optimization') not in ['s', '2', '3']
+    message('Doing a release build')
+fi
+```
+
+**Note:** Passing `--buildtype` or `-Dbuildtype` using the command-line, in
+native/cross files, or in `project()` `default_options:` is still allowed as
+a convenient short-cut. Note that (*[since 0.48]*), Meson has been [automatically
+setting `-Doptimization` and `-Ddebug` using `-Dbuildtype` and
+vice-versa](Builtin-options.html#build-type-options).
+
+[since 0.48]: https://mesonbuild.com/Release-notes-for-0-48-0.html#toggles-for-build-type-optimization-and-vcrt-type
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index af6eda321..954a5db8d 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -2833,7 +2833,7 @@ external dependencies (including libraries) must go to "dependencies".''')
 
     @stringArgs
     @noKwargs
-    def func_get_option(self, nodes, args, kwargs):
+    def func_get_option(self, node, args, kwargs):
         if len(args) != 1:
             raise InterpreterException('Argument required for get_option.')
         optname = args[0]
@@ -2841,6 +2841,9 @@ external dependencies (including libraries) must go to "dependencies".''')
             raise InterpreterException('Having a colon in option name is forbidden, '
                                        'projects are not allowed to directly access '
                                        'options of other subprojects.')
+        if optname == 'buildtype':
+            mlog.deprecation("Use get_option('debug') and/or get_option('optimization') "
+                             "instead of get_option('buildtype')", location=node)
         opt = self.get_option_internal(optname)
         if isinstance(opt, coredata.UserFeatureOption):
             return FeatureOptionHolder(self.environment, optname, opt)