Docs: Mention important macOS caveat about function detection [ci skip]
@@ -160,15 +160,30 @@ Does a function exist?
Just having a header doesn't say anything about its
contents. Sometimes you need to explicitly check if some function
-exists. This is how we would check whether the function `somefunc`
-exists in header `someheader.h`
+exists. This is how we would check whether the function `open_memstream`
+exists in header `stdio.h`
```meson
-if compiler.has_function('somefunc', prefix : '#include<someheader.h>')
+if compiler.has_function('open_memstream', prefix : '#include <stdio.h>')
# function exists, do whatever is required.
endif
```
+Note that, on macOS programs can be compiled targeting older macOS
+versions than the one that the program is compiled on. It can't be
+assumed that the OS version that is compiled on matches the OS
+version that the binary will run on.
+
+Therefore when detecting function availability with `has_function`, it
+is important to specify the correct header in the prefix argument.
+
+In the example above, the function `open_memstream` is detected, which
+was introduced in macOS 10.13. When the user builds on macOS 10.13, but
+targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will correctly
+report the function as missing. Without the header however, it would lack
+the necessary availability information and incorrectly report the function
+as available.
+
Does a structure contain a member?
==
