diff options
| author | Xavier Claessens <xavier.claessens@collabora.com> | 2024-04-05 08:55:20 -0700 |
|---|---|---|
| committer | Jussi Pakkanen <jpakkane@gmail.com> | 2024-04-14 19:40:02 +0300 |
| commit | 9f02d0a3e5a5ffc82256391c244b1af38e41ef78 (patch) | |
| tree | abd84b53919405a6ea3de5494720e88df7ae23c1 /docs | |
| parent | 1dcffb635f3ba3dae63e6aa1b61d3cf56c9cc49b (diff) | |
| download | meson-9f02d0a3e5a5ffc82256391c244b1af38e41ef78.tar.gz | |
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.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Configuration.md | 2 | ||||
| -rw-r--r-- | docs/yaml/objects/cfg_data.yaml | 12 | ||||
| -rw-r--r-- | docs/yaml/objects/env.yaml | 13 |
3 files changed, 22 insertions, 5 deletions
diff --git a/docs/markdown/Configuration.md b/docs/markdown/Configuration.md index 48f071e6c..b5875e55e 100644 --- a/docs/markdown/Configuration.md +++ b/docs/markdown/Configuration.md @@ -39,7 +39,7 @@ use a single `configuration_data` object as many times as you like, but it becomes immutable after being passed to the `configure_file` function. That is, after it has been used once to generate output the `set` function becomes unusable and trying to call it causes an error. -Copy of immutable `configuration_data` is still immutable. +*Since 1.5.0* Copy of immutable `configuration_data` is however mutable. For more complex configuration file generation Meson provides a second form. To use it, put a line like this in your configuration file. diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml index 03abb1709..069cadbf6 100644 --- a/docs/yaml/objects/cfg_data.yaml +++ b/docs/yaml/objects/cfg_data.yaml @@ -1,10 +1,14 @@ name: cfg_data long_name: Configuration data object description: | - This object encapsulates - configuration values to be used for generating configuration files. A - more in-depth description can be found in the [the configuration wiki - page](Configuration.md). + This object encapsulates configuration values to be used for generating + configuration files. A more in-depth description can be found in the + [the configuration page](Configuration.md). + + This object becomes immutable after first use. This means that + calling set() or merge_from() will cause an error if this object has + already been used in any function arguments. However, assignment creates a + mutable copy. methods: - name: set diff --git a/docs/yaml/objects/env.yaml b/docs/yaml/objects/env.yaml index 714da4fe4..3b2e2a851 100644 --- a/docs/yaml/objects/env.yaml +++ b/docs/yaml/objects/env.yaml @@ -9,6 +9,11 @@ description: | on the same `varname`. Earlier Meson versions would warn and only the last operation took effect. + *Since 1.5.0* This object becomes immutable after first use. This means that + calling append(), prepend() or set() will cause a deprecation warning if this + object has already been used in any function arguments. However, assignment + creates a mutable copy. + example: | ```meson env = environment() @@ -18,6 +23,14 @@ example: | env.append('MY_PATH', '2') env.append('MY_PATH', '3') env.prepend('MY_PATH', '0') + + # Deprecated since 1.5.0 + run_command('script.py', env: env) + env.append('MY_PATH', '4') + + # Allowed and only env2 is modified + env2 = env + env2.append('MY_PATH', '4') ``` methods: |