Document new `debug` and `runtime` option values

docs/guide/toolchains.rst

@@ -305,8 +305,37 @@ is ``false``.
 ``debug``
 ---------
 
-Boolean option (``true`` or ``false``) to enable/disable the generation of
-debugging information. Default is ``false``.
+Bool or string. Default is ``false``. If ``true`` or ``"embedded"``, generates
+debug information embedded in the compiled binaries. If ``"split"``, generates
+debug information in a separate file from the binaries.
+
+.. note::
+    ``"split"`` with GCC requires that the compiler support the
+    ``-gsplit-dwarf`` option.
+
+
+``runtime``
+-----------
+
+Select the language runtime/standard library options. Must be an object, and supports two keys:
+
+``static``
+    A boolean. If ``true``, the runtime and standard libraries will be static-linked into the generated binaries. If ``false``, they will be dynamically linked. Default is ``true`` with MSVC, and ``false`` with GCC and Clang.
+
+``debug``
+    A boolean. If ``true``, the debug versions of the runtime and standard library will be compiled and linked into the generated binaries. If ``false``, the default libraries will be used.
+
+    **On MSVC** the default value depends on the top-level ``/debug`` option: If ``/debug`` is not ``false``, then ``/runtime/debug`` defaults to ``true``.
+
+    **On GCC and Clang** the default value is ``false``.
+
+.. note::
+    On GNU-like compilers, ``static`` does not generate a static executable, it only statically links the runtime and standard library. To generate a static executable, the ``-static`` option should be added to ``link_flags``.
+
+.. note::
+    On GNU and Clang, setting ``/runtime/debug`` to ``true`` will compile all files with the ``_GLIBCXX_DEBUG`` and ``_LIBCPP_DEBUG=1`` preprocessor definitions set. **Translation units compiled with these macros are definitively ABI-incompatible with TUs that have been compiled without these options!!**
+
+    If you link to a static or dynamic library that has not been compiled with the same runtime settings, generated programs will likely crash.
 
 
 ``compiler_launcher``