docs: document new behavior with respect to mixed language link tests

2 files changed, 25 insertions, 1 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 8ef36de..9a0a89a 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -2513,7 +2513,10 @@ the following methods:
   positional argument compiles and links, you can specify external
   dependencies to use with `dependencies` keyword argument, `code` can
   be either a string containing source code or a `file` object
-  pointing to the source code.
+  pointing to the source code.  *Since 0.60.0*, if the `file` object's
+  suffix does not match the compiler object's language, the compiler
+  corresponding to the suffix is used to compile the source, while the
+  target of the `links` method is used to link the resulting object file.
 
 - `run(code)`: attempts to compile and execute the given code fragment,
   returns a run result object, you can specify external dependencies
diff --git a/docs/markdown/snippets/mixed_language_linker_tests.md b/docs/markdown/snippets/mixed_language_linker_tests.md
new file mode 100644
index 0000000..8b94edb
--- /dev/null
+++ b/docs/markdown/snippets/mixed_language_linker_tests.md
@@ -0,0 +1,21 @@
+== Link tests can use sources for a different compiler ==
+
+Usually, the `links` method of the compiler object uses a single program
+invocation to do both compilation and linking.  Starting with this version,
+whenever the argument to `links` is a file, Meson will check if the file
+suffix matches the compiler object's language.  If they do not match,
+as in the following case:
+
+```
+cxx = meson.get_compiler('cpp')
+cxx.links(files('test.c'))
+```
+
+then Meson will separate compilation and linking.  In the above example
+`test.c` will be compiled with a C compiler and the resulting object file
+will be linked with a C++ compiler.  This makes it possible to detect
+misconfigurations of the compilation environment, for example when the
+C++ runtime is not compatible with the one expected by the C compiler.
+
+For this reason, passing file arguments with an unrecognized suffix to
+`links` will cause a warning.