Document the project policy on mixing build systems. [skip ci]

4 files changed, 62 insertions, 0 deletions

diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md
index a15e3c2..2e2da71 100644
--- a/docs/markdown/CMake-module.md
+++ b/docs/markdown/CMake-module.md
@@ -1,5 +1,8 @@
 # CMake module
 
+**Note**: the functionality of this module is governed by [Meson's
+  rules on mixing build systems](Mixing-build-systems.md].
+
 This module provides helper tools for generating cmake package files.
 It also supports the usage of CMake based subprojects, similar to
 the normal [meson subprojects](Subprojects.md).
diff --git a/docs/markdown/Mixing-build-systems.md b/docs/markdown/Mixing-build-systems.md
new file mode 100644
index 0000000..98ca0ed
--- /dev/null
+++ b/docs/markdown/Mixing-build-systems.md
@@ -0,0 +1,55 @@
+# Meson's policy on mixing multiple build systems in one build directory
+
+Meson has been designed with the principle that all dependencies are
+either provided by "the platform" via a mechanism such as Pkg-Config
+or that they are built as Meson subprojects under the main
+project. There are several projects that would like to mix build
+systems, that is, build dependencies in the same build directory as
+the other build system by having one build system call the other. The
+build directories do not necessarily need to be inside each other, but
+that is the common case.
+
+This page lists the Meson project's stance on mixing build
+systems. The tl/dr version is that while we do provide some
+functionality for this use case, it only works for simple
+cases. Anything more complex can not be made reliable and trying to do
+that would burden Meson developers with an effectively infinite
+maintenance burden. Thus these use cases are not guaranteed to work,
+and even if a project using them works today there are no guarantees
+that it will work in any future version.
+
+## The definition of "build system mixing"
+
+For the purposes of this page, mixing build systems means any and all
+mechanisms where one build system uses build artifacts from a
+different build system's build directory in any way.
+
+Note that this definition does not specify what the dependencies are
+and how they are built, only how they are consumed. For example
+suppose you have a standalone dependency library that builds with
+build system X. In this case having Meson call the build system to
+build the dependency at build time would be interpreted as mixing
+build systems. On the other hand a "Flatpak-like" approach of building
+and installing the library with an external mechanism and consuming it
+via a standard build-system agnostic method such as Pkg-Config would
+not be considered build system mixing. Use of uninstalled-pkgconfig
+files is considered mixing, though.
+
+## What does this mean for support and compatibility?
+
+The Meson project will not take on any maintenance burden to ensure
+anything other than the simple builds setups as discussed above will
+work. Nor will we make changes to support these use cases that would
+worsen the user experience of users of plain Meson. This includes, but
+is not limited to, the following:
+
+- Any changes in other build systems that cause mixed project breakage
+  will not be considered a bug in Meson.
+
+- Breakages in mixed build projects will not be considered regressions
+  and such problems will never be considered release blockers,
+  regardless of what the underlying issue is.
+
+- Any use case that would require major changes in Meson to work
+  around missing or broken functionality in the other build system is
+  not supported. These issues must be fixed upstream.
diff --git a/docs/markdown/snippets/uninstalled-pkgconfig.md b/docs/markdown/snippets/uninstalled-pkgconfig.md
index 2e265ab..27a3c66 100644
--- a/docs/markdown/snippets/uninstalled-pkgconfig.md
+++ b/docs/markdown/snippets/uninstalled-pkgconfig.md
@@ -1,5 +1,8 @@
 ## Uninstalled pkg-config files
 
+**Note**: the functionality of this module is governed by [Meson's
+  rules on mixing build systems](Mixing-build-systems.md].
+
 The `pkgconfig` module now generates uninstalled pc files as well. For any generated
 `foo.pc` file, an extra `foo-uninstalled.pc` file is placed into
 `<builddir>/meson-uninstalled`. They can be used to build applications against
diff --git a/docs/sitemap.txt b/docs/sitemap.txt
index 157574d..ef72f70 100644
--- a/docs/sitemap.txt
+++ b/docs/sitemap.txt
@@ -105,6 +105,7 @@ index.md
 		Design-rationale.md
 		IndepthTutorial.md
 		In-the-press.md
+		Mixing-build-systems.md
 		Pkg-config-files.md
 		Playground.md
 		Porting-from-autotools.md