Add a page documenting platform support

Author: vector-of-bool

docs/ref/building.rst

@@ -8,15 +8,12 @@ Configuring, Building, & Using
 Building |amongoc| requires a C++20 compiler. The following tools are known to
 work:
 
+- :doc:`A supported operating system and toolchain <platform-support>`
 - CMake_ 3.25 or newer
-- GCC ≥12.0\ [#fn-redhat-issue]_ **or** Clang ≥17.0
 - Earthly_ 0.8 or newer (for :ref:`building with Earthly <building.earthly>`)
 
-Building on Windows or with MSVC is not currently supported.
-
-Builds are only currently tested with Debian 12 and Alpine 3.20. Support for
-other platforms may be considered in the future, but are not currently planned
-for this prototype.
+Support for other platforms and toolchains may be considered in the future, but
+are not currently planned for this prototype.
 
 .. _CMake: https://cmake.org/
 .. _Earthly: https://earthly.dev/
@@ -88,7 +85,6 @@ them:
     - CMake built-in
 
 
-
 Build Configuration
 ###################
 

docs/ref/index.rst

@@ -9,6 +9,7 @@ Reference
 
   meta-attrs
   api-patterns
+  platform-support
   building
 
   box

docs/ref/platform-support.rst

@@ -0,0 +1,83 @@
+################
+Platform Support
+################
+
+This page details information on the compiler/platform support of |amongoc|.
+
+.. NOTE
+  This page should be kept in sync with our CI tasks to ensure that it remains
+  correct. The main CI tasks defined in `ci.yml` define our platform support.
+
+
+Operating Systems
+#################
+
+Linux
+*****
+
+Full Support with Default Toolchain
+===================================
+
+|amongoc| is tested and supported on the following Linux distributions using the
+toolchains and libraries that are available in their default package
+repositories:
+
+1. **Debian 12** and newer
+2. **Ubuntu 24.04** and newer
+3. **Fedora 40** and newer
+4. **Alpine 3.18** and newer
+
+
+Partially Supported
+===================
+
+|amongoc| is tested and supported on the following Linux platorms with some
+caveats:
+
+1. **Alpine 3.17** and **RHEL 10** (and derived) can build and run |amongoc|
+   using the default platform toolchain, but it requires library dependencies
+   that are not available in the default respositories. Building using ``vcpkg``
+   is fully supported.
+2. **RHEL 8** (and derived) can build and run |amongoc|, but it requires
+   dependencies that are not available in the default repositories, and requires
+   using a newer ``gcc-toolset`` (≥12.0) package to build.
+
+
+Windows
+*******
+
+|amongoc| is supported on Windows using the **Visual Studio 2022** toolchain and
+``vcpkg`` to obtain dependencies.
+
+.. note::
+
+  Building using other toolchains on Windows is not tested.
+
+
+Compilers and Toolchains
+########################
+
+Fully Supported
+***************
+
+The following toolchains are fully supported:
+
+- **GCC 12** and newer. See also: :ref:`gcc-linker-issue`
+- **LLVM/Clang 17** and newer
+- **Microsoft Visual Studio 2022** and newer
+
+.. note::
+
+  Apple/Clang is not tested.
+
+
+.. _gcc-linker-issue:
+
+GCC Linker Issues
+*****************
+
+While **GCC 13** and **GCC 12** can build |amongoc|, a bug in GCC causes a
+linker error when all optimizations are enabled. The |amongoc| CMake build
+detects these GCC versions and disables the specific optimizations that cause
+the linker issue. If you see a linker issue that only appears when optimizations
+are enabled, please file a bug report.