docs: add a couple words about system dependencies

1 files changed, 17 insertions, 0 deletions

diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index 2ac775bd3..c785e3c59 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -152,6 +152,7 @@ The dependency method order for `auto` is:
   1. `pkg-config`
   2. `cmake`
   3. `extraframework` (OSX only)
+  4. `system`
 
 ## CMake
 
@@ -266,6 +267,22 @@ dep = dependency('appleframeworks', modules : 'foundation')
 
 These dependencies can never be found for non-OSX hosts.
 
+## System
+
+Some dependencies provide no valid methods for discovery, or do so only in
+some cases. Some examples of this are Zlib, which provides both pkg-config
+and cmake, except when it is part of the base OS image (such as in FreeBSD
+and macOS); OpenGL which has pkg-config on Unices from glvnd or mesa, but has
+no pkg-config on macOS and Windows.
+
+In these cases meson provides convenience wrappers in the form of `system`
+dependencies. Internally these dependencies do exactly what a user would do
+in the build system DSL or with a script, likely calling
+`compiler.find_library()`, setting `link_with` and `include_directories`. By
+putting these in meson upstream the barrier of using them is lowered, as
+projects using meson don't have to re-implement the logic.
+
+
 ## Blocks
 
 Enable support for Clang's blocks extension.