2 files changed, 57 insertions, 0 deletions
diff --git a/docs/markdown/Machine-files.md b/docs/markdown/Machine-files.md
index 9011f79..26af44a 100644
--- a/docs/markdown/Machine-files.md
+++ b/docs/markdown/Machine-files.md
@@ -12,6 +12,7 @@ The following sections are allowed:
 - binaries
 - paths
 - properties
+- project options
 
 ### constants
 
@@ -166,6 +167,25 @@ section may contain random key value pairs accessed using the
 The properties section can contain any variable you like, and is accessed via
 `meson.get_external_property`, or `meson.get_cross_property`.
 
+### Project specific options
+
+*New in 0.54.0*
+
+Being able to set project specific options in a native or cross files can be
+done using the `[project options]` section of the specific file (if doing a
+cross build the options from the native file will be ignored)
+
+For setting options in supbprojects use the `<subproject>:project options`
+section instead.
+
+```ini
+[project options]
+build-tests = true
+
+[zlib:project options]
+build-tests = false
+```
+
 ## Loading multiple machine files
 
 Native files allow layering (cross files can be layered since meson 0.52.0).
diff --git a/docs/markdown/snippets/project_options_in_machine_files.md b/docs/markdown/snippets/project_options_in_machine_files.md
new file mode 100644
index 0000000..78b129a
--- /dev/null
+++ b/docs/markdown/snippets/project_options_in_machine_files.md
@@ -0,0 +1,37 @@
+## Project options can be set in native or cross files
+
+A new set of sections has been added to the cross and native files, `[project
+options]` and `[<subproject_name>:project options]`, where `subproject_name`
+is the name of a subproject. Any options that are allowed in the project can
+be set from this section. They have the lowest precedent, and will be
+overwritten by command line arguments.
+
+
+```meson
+option('foo', type : 'string', value : 'foo')
+```
+
+```ini
+[project options]
+foo = 'other val'
+```
+
+```console
+meson build --native-file my.ini
+```
+
+Will result in the option foo having the value `other val`,
+
+```console
+meson build --native-file my.ini -Dfoo='different val'
+```
+
+Will result in the option foo having the value `different val`,
+
+
+Subproject options are assigned like this:
+
+```ini
+[zlib:project options]
+foo = 'some val'
+```