interpreter/mesonmain: Add build_options method

This method allows meson.build to introspect on the changed options.
It works by merely exposing the same set of data that is logged by
MesonApp._generate.

Fixes mesonbuild#10898

docs/yaml/builtins/meson.yaml

@@ -164,6 +164,21 @@ methods:
       - `vs2022`
       - `xcode`
 
+  - name: build_options
+    returns: str
+    since: 1.1.0
+    description: |
+      Returns a string with the configuration line used to set the current project up.
+    notes:
+      - |
+        **Do not try to parse this string!**
+
+        You should use [[cfg_data.set_quoted]] to safely escape any embedded
+        quotes prior to storing it into e.g. a C header macro.
+
+        The contents returned by this function are the same as the
+        "Build Options:" line reported in `<builddir>/meson-logs/meson-log.txt`.
+
   - name: build_root
     returns: str
     deprecated: 0.56.0

mesonbuild/interpreter/mesonmain.py

@@ -9,7 +9,7 @@
 from .. import mesonlib
 from .. import dependencies
 from .. import build
-from .. import mlog
+from .. import mlog, coredata
 
 from ..mesonlib import MachineChoice, OptionKey
 from ..programs import OverrideProgram, ExternalProgram
@@ -84,6 +84,7 @@ def __init__(self, build: 'build.Build', interpreter: 'Interpreter'):
                              'has_external_property': self.has_external_property_method,
                              'backend': self.backend_method,
                              'add_devenv': self.add_devenv_method,
+                             'build_options': self.build_options_method,
                              })
 
     def _find_source_script(
@@ -465,3 +466,12 @@ def add_devenv_method(self, args: T.Tuple[T.Union[str, list, dict, build.Environ
         converted = env_convertor_with_method(env, kwargs['method'], kwargs['separator'])
         assert isinstance(converted, build.EnvironmentVariables)
         self.build.devenv.append(converted)
+
+    @noPosargs
+    @noKwargs
+    @FeatureNew('meson.build_options', '1.1.0')
+    def build_options_method(self, args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> str:
+        options = self.interpreter.user_defined_options
+        if options is None:
+            return ''
+        return coredata.format_cmd_line_options(options)

test cases/unit/110 list build options/meson.build

@@ -0,0 +1,6 @@
+project('feature user option', 'c')
+
+feature_opts = get_option('auto_features')
+optional_opt = get_option('optional')
+
+message('Build options:', meson.build_options())

test cases/unit/110 list build options/meson_options.txt

@@ -0,0 +1 @@
+option('optional', type : 'feature', value : 'auto', description : 'An optional feature')

unittests/allplatformstests.py

@@ -1948,6 +1948,33 @@ def test_options_with_choices_changing(self) -> None:
                 self.assertEqual(item['value'], ['b', 'c'])
                 self.assertEqual(item['choices'], ['b', 'c', 'd'])
 
+    def test_options_listed_in_build_options(self) -> None:
+        """Detect when changed options become listed in build options."""
+        testdir = os.path.join(self.unit_test_dir, '110 list build options')
+
+        out = self.init(testdir)
+        for line in out.splitlines():
+            if line.startswith('Message: Build options:'):
+                self.assertNotIn('-Dauto_features=auto', line)
+                self.assertNotIn('-Doptional=auto', line)
+
+        self.wipe()
+        self.mac_ci_delay()
+
+        out = self.init(testdir, extra_args=['-Dauto_features=disabled', '-Doptional=enabled'])
+        for line in out.splitlines():
+            if line.startswith('Message: Build options:'):
+                self.assertIn('-Dauto_features=disabled', line)
+                self.assertIn('-Doptional=enabled', line)
+
+        self.setconf('-Doptional=disabled')
+        out = self.build()
+        for line in out.splitlines():
+            if line.startswith('Message: Build options:'):
+                self.assertIn('-Dauto_features=disabled', line)
+                self.assertNotIn('-Doptional=enabled', line)
+                self.assertIn('-Doptional=disabled', line)
+
     def test_subproject_promotion(self):
         testdir = os.path.join(self.unit_test_dir, '12 promote')
         workdir = os.path.join(self.builddir, 'work')