Clarify mutable objects usage

Only Environment and ConfigurationData are mutable. However, only
ConfigurationData becomes immutable after first use which is
inconsistent.

This deprecates modification after first use of Environment object and
clarify documentation.

2 files changed, 24 insertions, 1 deletions

diff --git a/mesonbuild/interpreterbase/_unholder.py b/mesonbuild/interpreterbase/_unholder.py
index c62aafe8e..e32b77fc7 100644
--- a/mesonbuild/interpreterbase/_unholder.py
+++ b/mesonbuild/interpreterbase/_unholder.py
@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import typing as T
 
-from .baseobjects import InterpreterObject, MesonInterpreterObject, ObjectHolder, HoldableTypes
+from .baseobjects import InterpreterObject, MesonInterpreterObject, ObjectHolder, HoldableTypes, MutableInterpreterObject
 from .exceptions import InvalidArguments
 from ..mesonlib import HoldableObject, MesonBugException
 
@@ -13,6 +13,8 @@ if T.TYPE_CHECKING:
     from .baseobjects import TYPE_var
 
 def _unholder(obj: InterpreterObject) -> TYPE_var:
+    if isinstance(obj, MutableInterpreterObject):
+        obj.mark_used()
     if isinstance(obj, ObjectHolder):
         assert isinstance(obj.held_object, HoldableTypes)
         return obj.held_object
diff --git a/mesonbuild/interpreterbase/baseobjects.py b/mesonbuild/interpreterbase/baseobjects.py
index 9a119a98a..c6864a478 100644
--- a/mesonbuild/interpreterbase/baseobjects.py
+++ b/mesonbuild/interpreterbase/baseobjects.py
@@ -120,6 +120,27 @@ class MesonInterpreterObject(InterpreterObject):
 
 class MutableInterpreterObject:
     ''' Dummy class to mark the object type as mutable '''
+    def __init__(self) -> None:
+        self.used = False
+        self.mutable_feature_new = False
+
+    def mark_used(self) -> None:
+        self.used = True
+
+    def is_used(self) -> bool:
+        return self.used
+
+    def check_used(self, interpreter: Interpreter, fatal: bool = True) -> None:
+        from .decorators import FeatureDeprecated, FeatureNew
+        if self.is_used():
+            if fatal:
+                raise InvalidArguments('Can not modify object after it has been used.')
+            FeatureDeprecated.single_use('Modify object after it has been used', '1.5.0',
+                                         interpreter.subproject, location=interpreter.current_node)
+        elif self.mutable_feature_new:
+            FeatureNew.single_use('Modify a copy of an immutable object', '1.5.0',
+                                  interpreter.subproject, location=interpreter.current_node)
+            self.mutable_feature_new = False
 
 HoldableTypes = (HoldableObject, int, bool, str, list, dict)
 TYPE_HoldableTypes = T.Union[TYPE_elementary, HoldableObject]