Document setting up Vulkan validation layers on desktop platforms

contributing/development/debugging/vulkan/vulkan_validation_layers.rst

@@ -3,10 +3,133 @@
 Validation layers
 =================
 
-Validation layers enable developers to verify their application's correct use
-of the Vulkan API.
+Validation layers enable developers to verify their application's correct use of
+the Vulkan API. Validation layers can be enabled in both debug and release
+builds, including in exported projects.
 
-.. _doc_vulkan_validation_layers-android:
+.. note::
+
+    Enabling validation layers has a performance impact, so only enable them
+    when you actually need the output to debug the application.
+
+Windows
+-------
+
+Install the Vulkan SDK `<https://vulkan.lunarg.com/sdk/home>`__, which contains
+validation layers as part of its default installation. No need to enable any
+optional features in the installer; installing the core Vulkan SDK suffices. You
+don't need to reboot after installing the SDK, but you may need to close and
+reopen your current terminal.
+
+After installing the Vulkan SDK, run Godot with the ``--gpu-validation``
+:ref:`command line argument <doc_command_line_tutorial>`. You can also specify
+``--gpu-abort`` which will make Godot quit as soon as a validation error happens.
+This can prevent your system from freezing if a validation error occurs.
+
+macOS
+-----
+
+.. warning::
+
+    Official Godot macOS builds do **not** support validation layers, as these
+    are statically linked against the Vulkan SDK. Dynamic linking must be used
+    instead.
+
+    In practice, this means that using validation layers on macOS **requires**
+    you to use a Godot build compiled with the ``use_volk=yes`` SCons option.
+    :ref:`doc_compiling_for_macos`. If testing validation layers on an exported
+    project, you must recompile the export template and specify it as a custom
+    export template in your project's macOS export preset.
+
+Install the Vulkan SDK `<https://vulkan.lunarg.com/sdk/home>`__, which contains
+validation layers as part of its default installation. No need to enable any
+optional features in the installer; installing the core Vulkan SDK suffices. You
+don't need to reboot after installing the SDK, but you may need to close and
+reopen your current terminal.
+
+After installing the Vulkan SDK, run a Godot binary that was compiled with
+``use_volk=yes`` SCons option. Specify the ``--gpu-validation``
+:ref:`command line argument <doc_command_line_tutorial>`.
+You can also specify ``--gpu-abort`` which will make Godot quit as soon
+as a validation error happens. This can prevent your system from freezing
+if a validation error occurs.
+
+Linux, \*BSD
+------------
+
+Install Vulkan validation layers from your distribution's repositories:
+
+.. tabs::
+
+    .. tab:: Alpine Linux
+
+        ::
+
+            vulkan-validation-layers
+
+    .. tab:: Arch Linux
+
+        ::
+
+            pacman -S vulkan-validation-layers
+
+    .. tab:: Debian/Ubuntu
+
+        ::
+
+            apt install vulkan-validationlayers
+
+    .. tab:: Fedora
+
+        ::
+
+            dnf install vulkan-validation-layers
+
+    .. tab:: FreeBSD
+
+        ::
+
+            pkg install graphics/vulkan-validation-layers
+
+    .. tab:: Gentoo
+
+        ::
+
+            emerge -an media-libs/vulkan-layers
+
+    .. tab:: Mageia
+
+        ::
+
+            urpmi vulkan-validation-layers
+
+    .. tab:: OpenBSD
+
+        ::
+
+            pkg_add graphics/vulkan-validation-layers
+
+    .. tab:: openSUSE
+
+        ::
+
+            zypper install vulkan-validationlayers
+
+    .. tab:: Solus
+
+        ::
+
+            eopkg install -c vulkan-validation-layers
+
+You don't need to reboot after installing the validation layers, but you may
+need to close and reopen your current terminal.
+
+After installing the package, run Godot with the ``--gpu-validation``
+:ref:`command line argument <doc_command_line_tutorial>`. You can also specify
+``--gpu-abort`` which will make Godot quit as soon as a validation error happens.
+This can prevent your system from freezing if a validation error occurs.
+
+.. _doc_vulkan_validation_layers_android:
 
 Android
 -------
@@ -14,6 +137,17 @@ Android
 After enabling validation layers on Android, a developer can see errors and
 warning messages in the ``adb logcat`` output.
 
+iOS
+---
+
+Validation layers are currently **not** supported on iOS.
+
+Web
+---
+
+Validation layers are **not** supported on the web platform, as there is no support
+for Vulkan there.
+
 Enabling validation layers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~