compilers: Add optimization=plain option

https://github.com/mesonbuild/meson/pull/9287 changed the `optimization=0`
to pass `-O0` to the compiler. This change is reasonable by itself
but unfortunately, it breaks `buildtype=plain`, which promises
that “no extra build flags are used”.

`buildtype=plain` is important for distros like NixOS,
which manage compiler flags for optimization and hardening
themselves.

Let’s introduce a new optimization level that does nothing
and set it as the default for `buildtype=plain`.

3 files changed, 29 insertions, 19 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index 9c3705b..d90631f 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -67,28 +67,28 @@ Options that are labeled "per machine" in the table are set per
 machine. See the [specifying options per
 machine](#specifying-options-per-machine) section for details.
 
-| Option                               | Default value | Description                                                    | Is per machine | Is per subproject |
-| ------                               | ------------- | -----------                                                    | -------------- | ----------------- |
+| Option                                 | Default value | Description                                                    | Is per machine | Is per subproject |
+| -------------------------------------- | ------------- | -----------                                                    | -------------- | ----------------- |
 | auto_features {enabled, disabled, auto} | auto       | Override value of all 'auto' features                          | no             | no                |
 | backend {ninja, vs,<br>vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, vs2022, xcode} | ninja | Backend to use        | no             | no                |
 | buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug |  Build type to use                    | no             | no                |
-| debug                                | true          | Enable debug symbols and other information                     | no             | no                |
+| debug                                  | true          | Enable debug symbols and other information                     | no             | no                |
 | default_library {shared, static, both} | shared      | Default library type                                           | no             | yes               |
-| errorlogs                            | true          | Whether to print the logs from failing tests.                  | no             | no                |
-| install_umask {preserve, 0000-0777}  | 022           | Default umask to apply on permissions of installed files       | no             | no                |
-| layout {mirror,flat}                 | mirror        | Build directory layout                                         | no             | no                |
-| optimization {0, g, 1, 2, 3, s}      | 0             | Optimization level                                             | no             | no                |
-| pkg_config_path {OS separated path}  | ''            | Additional paths for pkg-config to search before builtin paths | yes            | no                |
-| prefer_static                        | false         | Whether to try static linking before shared linking            | no             | no                |
-| cmake_prefix_path                    | []            | Additional prefixes for cmake to search before builtin paths   | yes            | no                |
-| stdsplit                             | true          | Split stdout and stderr in test logs                           | no             | no                |
-| strip                                | false         | Strip targets on install                                       | no             | no                |
-| unity {on, off, subprojects}         | off           | Unity build                                                    | no             | no                |
-| unity_size {>=2}                     | 4             | Unity file block size                                          | no             | no                |
-| warning_level {0, 1, 2, 3}           | 1             | Set the warning level. From 0 = none to 3 = highest            | no             | yes               |
-| werror                               | false         | Treat warnings as errors                                       | no             | yes               |
+| errorlogs                              | true          | Whether to print the logs from failing tests.                  | no             | no                |
+| install_umask {preserve, 0000-0777}    | 022           | Default umask to apply on permissions of installed files       | no             | no                |
+| layout {mirror,flat}                   | mirror        | Build directory layout                                         | no             | no                |
+| optimization {plain, 0, g, 1, 2, 3, s} | 0             | Optimization level                                             | no             | no                |
+| pkg_config_path {OS separated path}    | ''            | Additional paths for pkg-config to search before builtin paths | yes            | no                |
+| prefer_static                          | false         | Whether to try static linking before shared linking            | no             | no                |
+| cmake_prefix_path                      | []            | Additional prefixes for cmake to search before builtin paths   | yes            | no                |
+| stdsplit                               | true          | Split stdout and stderr in test logs                           | no             | no                |
+| strip                                  | false         | Strip targets on install                                       | no             | no                |
+| unity {on, off, subprojects}           | off           | Unity build                                                    | no             | no                |
+| unity_size {>=2}                       | 4             | Unity file block size                                          | no             | no                |
+| warning_level {0, 1, 2, 3}             | 1             | Set the warning level. From 0 = none to 3 = highest            | no             | yes               |
+| werror                                 | false         | Treat warnings as errors                                       | no             | yes               |
 | wrap_mode {default, nofallback,<br>nodownload, forcefallback, nopromote} | default | Wrap mode to use                 | no             | no                |
-| force_fallback_for                   | []            | Force fallback for those dependencies                          | no             | no                |
+| force_fallback_for                     | []            | Force fallback for those dependencies                          | no             | no                |
 
 <a name="build-type-options"></a> For setting optimization levels and
 toggling debug, you can either set the `buildtype` option, or you can
@@ -100,7 +100,7 @@ the two-way mapping:
 
 | buildtype      | debug | optimization |
 | ---------      | ----- | ------------ |
-| plain          | false | 0            |
+| plain          | false | plain        |
 | debug          | true  | 0            |
 | debugoptimized | true  | 2            |
 | release        | false | 3            |
diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md
index 37080ef..2012b37 100644
--- a/docs/markdown/Configuring-a-build-directory.md
+++ b/docs/markdown/Configuring-a-build-directory.md
@@ -30,7 +30,7 @@ a sample output for a simple project.
       default_library shared        [shared, static, both]                                     Default library type
       install_umask   0022          [preserve, 0000-0777]                                      Default umask to apply on permissions of installed files
       layout          mirror        [mirror, flat]                                             Build directory layout
-      optimization    3             [0, g, 1, 2, 3, s]                                         Optimization level
+      optimization    3             [plain, 0, g, 1, 2, 3, s]                                  Optimization level
       prefer_static   false         [true, false]                                              Whether to try static linking before shared linking
       strip           false         [true, false]                                              Strip targets on install
       unity           off           [on, off, subprojects]                                     Unity build
diff --git a/docs/markdown/snippets/add_optimization_plain_option.md b/docs/markdown/snippets/add_optimization_plain_option.md
new file mode 100644
index 0000000..67910df
--- /dev/null
+++ b/docs/markdown/snippets/add_optimization_plain_option.md
@@ -0,0 +1,10 @@
+## Add `optimization` `plain` option
+
+The `optimization` built-in option now accepts `plain` value,
+which will not set any optimization flags. This is now the default
+value of the flag for `buildtype=plain`, which is useful for distros,
+that set the optimization and hardening flags by other means.
+
+If you are using the value of `get_option('optimization')` in your
+Meson scripts, make sure you are not making assumptions about it,
+such as that the value can be passed to a compiler in `-O` flag.