mirror of
https://github.com/godotengine/godot-contributing-docs.git
synced 2025-12-31 05:48:13 +03:00
Remove debugging information as it doesn't pertain to contributing, it should be documented on the docs instead.
This commit is contained in:
Lukas Tenbrink
Binary file not shown.
|
Before Width: | Height: | Size: 184 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 69 KiB |
@@ -1,48 +0,0 @@
|
||||
:allow_comments: False
|
||||
|
||||
Debugging and profiling
|
||||
=======================
|
||||
|
||||
This section contains pages that provide guidance if you're looking at the
|
||||
engine code trying to find an underlying issue or an optimization possibility.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:name: toc-devel-cpp-debug-profiling
|
||||
|
||||
using_cpp_profilers
|
||||
using_sanitizers
|
||||
macos_debug
|
||||
vulkan/index
|
||||
|
||||
Debugging the editor
|
||||
--------------------
|
||||
|
||||
When working on the Godot editor keep in mind that by default the executable
|
||||
will start in the Project Manager mode. Opening a project from the Project
|
||||
Manager spawns a new process, which stops the debugging session. To avoid that
|
||||
you should launch directly into the project using ``-e`` and ``--path`` launch
|
||||
options.
|
||||
|
||||
For example, using ``gdb`` directly, you may do this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
gdb godot
|
||||
> run -e --path ~/myproject
|
||||
|
||||
You can also run the editor directly from your project's folder. In that case,
|
||||
only the ``-e`` option is required.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
cd ~/myproject
|
||||
gdb godot
|
||||
> run -e
|
||||
|
||||
You can learn more about these launch options and other command line arguments
|
||||
in the :ref:`command line tutorial <doc_command_line_tutorial>`.
|
||||
|
||||
If you're using a code editor or an IDE to debug Godot, check out our
|
||||
:ref:`configuration guides <doc_configuring_an_ide>`, which cover the setup
|
||||
process for building and debugging with your particular editor.
|
||||
@@ -1,46 +0,0 @@
|
||||
Debugging on macOS
|
||||
==================
|
||||
|
||||
Debugging Godot editor
|
||||
----------------------
|
||||
|
||||
Attaching a debugger to the signed macOS process requires the "com.apple.security.get-task-allow" entitlement, which is not enabled by default, since apps can't be notarized as long as it is enabled.
|
||||
If you want to debug an official build of the editor it should be re-signed with the proper entitlements.
|
||||
|
||||
Create an ``editor.entitlements`` text file with the following contents:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-jit</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.disable-executable-page-protection</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.disable-library-validation</key>
|
||||
<true/>
|
||||
<key>com.apple.security.device.audio-input</key>
|
||||
<true/>
|
||||
<key>com.apple.security.device.camera</key>
|
||||
<true/>
|
||||
<key>com.apple.security.get-task-allow</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
|
||||
Then use the following command to re-sign the editor:
|
||||
|
||||
::
|
||||
|
||||
codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app
|
||||
|
||||
Debugging exported project
|
||||
--------------------------
|
||||
|
||||
To allow debugging, select the ``codesign\debugging`` (``com.apple.security.get-task-allow``) entitlement during the export. When it is selected, notarization is not supported and should be disabled.
|
||||
@@ -1,161 +0,0 @@
|
||||
.. _doc_using_cpp_profilers:
|
||||
|
||||
Using C++ profilers
|
||||
===================
|
||||
|
||||
To optimize Godot's performance, you need to know what to optimize first.
|
||||
To this end, profilers are useful tools.
|
||||
|
||||
.. note::
|
||||
|
||||
There is a :ref:`built-in GDScript profiler <doc_the_profiler>` in the editor,
|
||||
but using C++ profiler may be useful in cases where the GDScript profiler
|
||||
is not accurate enough or is missing information due to bugs in the profiler.
|
||||
|
||||
Recommended profilers
|
||||
---------------------
|
||||
|
||||
- `VerySleepy <http://www.codersnotes.com/sleepy/>`__ (Windows only)
|
||||
- `HotSpot <https://github.com/KDAB/hotspot>`__ (Linux only)
|
||||
- `Xcode Instruments <https://developer.apple.com/xcode/>`__ (macOS only)
|
||||
|
||||
These profilers may not be the most powerful or flexible options, but their
|
||||
standalone operation and limited feature set tends to make them easier to use.
|
||||
|
||||
Setting up Godot
|
||||
----------------
|
||||
|
||||
To get useful profiling information, it is **absolutely required** to use a Godot
|
||||
build that includes debugging symbols. Official binaries do not include debugging
|
||||
symbols, since these would make the download size significantly larger.
|
||||
|
||||
To get profiling data that best matches the production environment (but with debugging symbols),
|
||||
you should compile binaries with the ``production=yes debug_symbols=yes`` SCons options.
|
||||
|
||||
It is possible to run a profiler on less optimized builds (e.g. ``target=template_debug`` without LTO),
|
||||
but results will naturally be less representative of real world conditions.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do *not* strip debugging symbols on the binaries using the ``strip`` command
|
||||
after compiling the binaries. Otherwise, you will no longer get useful
|
||||
profiling information when running a profiler.
|
||||
|
||||
Benchmarking startup/shutdown times
|
||||
-----------------------------------
|
||||
|
||||
If you're looking into optimizing Godot's startup/shutdown performance,
|
||||
you can tell the profiler to use the ``--quit`` command line option on the Godot binary.
|
||||
This will exit Godot just after it finished starting.
|
||||
The ``--quit`` option works with ``--editor``, ``--project-manager`` or
|
||||
``--path <path to project directory>`` (which runs a project directly).
|
||||
|
||||
.. seealso::
|
||||
|
||||
See :ref:`doc_command_line_tutorial` for more command line arguments
|
||||
supported by Godot.
|
||||
|
||||
Profiler-specific instructions
|
||||
------------------------------
|
||||
|
||||
VerySleepy
|
||||
~~~~~~~~~~
|
||||
|
||||
- Start the Godot editor or your project first.
|
||||
If you start the Project Manager, make sure to edit or run a project first.
|
||||
Otherwise, the profiler will not track the child process since the Project Manager
|
||||
will spawn a child process for every project edited or run.
|
||||
- Open VerySleepy and select the Godot executable in the list of processes on the left:
|
||||
|
||||
.. image:: img/cpp_profiler_verysleepy_select_process.png
|
||||
|
||||
- Click the **Profile All** button on the right to start profiling.
|
||||
- Perform the actions you wish to profile in the editor or project. When you're done, click **Stop** (*not* Abort).
|
||||
- Wait for the results window to appear.
|
||||
- Once the results window appears, filter the view to remove external modules (such as the graphics driver).
|
||||
You can filter by module by finding a line whose **Module** matches the Godot
|
||||
executable name, right-clicking that line then choosing
|
||||
**Filter Module to <Godot executable name>** in the dropdown that appears.
|
||||
- Your results window should now look something like this:
|
||||
|
||||
.. image:: img/cpp_profiler_verysleepy_results_filtered.png
|
||||
|
||||
HotSpot
|
||||
~~~~~~~
|
||||
|
||||
- Open HotSpot. Click **Record Data**:
|
||||
|
||||
.. image:: img/cpp_profiler_hotspot_welcome.png
|
||||
|
||||
- In the next window, specify the path to the Godot binary that includes debug symbols.
|
||||
- Specify command line arguments to run a specific project, with or without the editor.
|
||||
- The path to the working directory can be anything if an absolute path is used
|
||||
for the ``--path`` command line argument. Otherwise, it must be set to that
|
||||
the relative path to the project is valid.
|
||||
- Make sure **Elevate Privileges** is checked if you have administrative privileges.
|
||||
While not essential for profiling Godot, this will ensure all events can be captured.
|
||||
Otherwise, some events may be missing in the capture.
|
||||
Your settings should now look something like this:
|
||||
|
||||
.. image:: img/cpp_profiler_hotspot_record.png
|
||||
|
||||
- Click **Start Recording** and perform the actions you wish to profile in the editor/project.
|
||||
- Quit the editor/project normally or use the **Stop Profiling** button in HotSpot
|
||||
to stop profiling early. Stopping profiling early can result in cleaner profiles
|
||||
if you're not interested in the engine's quit procedure.
|
||||
- Click **View Results** and wait for the profiling visualization to be generated:
|
||||
|
||||
.. image:: img/cpp_profiler_hotspot_view_results.png
|
||||
|
||||
- Use the tabs at the top to navigate between the different views. These views
|
||||
show the same data, but in different ways. The **Flame Graph** tab is a good
|
||||
way to see which functions take up the most time at a glance. These functions
|
||||
are therefore the most important ones to optimize, since optimizing them will
|
||||
improve performance the most.
|
||||
- At the bottom of all tabs except **Summary**, you will also see a list of CPU threads
|
||||
started by the engine among with the CPU utilization for each thread.
|
||||
This lets you see threads that can be a bottleneck at a given point in time.
|
||||
|
||||
.. image:: img/cpp_profiler_hotspot_flame_graph.png
|
||||
|
||||
.. note::
|
||||
|
||||
If you don't want the startup procedure to be included in the profile, you
|
||||
can also attach HotSpot to a running process by clicking **Record Data**
|
||||
then setting the **Launch Application** dropdown option to **Attach To
|
||||
Process(es)**.
|
||||
|
||||
This process attachment-based workflow is similar to the one used by VerySleepy.
|
||||
|
||||
Xcode Instruments
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Open Xcode. Select **Open Developer Tool** - **Instruments** from the **Xcode** app menu:
|
||||
- Double-click on **Time Profiler** in the **Instruments** window:
|
||||
|
||||
.. image:: img/cpp_profiler_xcode_menu.png
|
||||
|
||||
- In the Time Profiler window, click on the **Target** menu, select **Choose target...**
|
||||
and specify the path to the Godot binary, command line arguments and environment variables
|
||||
in the next window.
|
||||
|
||||
.. image:: img/cpp_profiler_time_profiler.png
|
||||
|
||||
- You can also attach the Time Profiler to a running process by selecting it from the **Target**
|
||||
menu.
|
||||
|
||||
- Click the **Start an immediate mode recording** button to start profiling.
|
||||
|
||||
.. image:: img/cpp_profiler_time_profiler_record.png
|
||||
|
||||
- Perform the actions you wish to profile in the editor or project. When you're done,
|
||||
click the **Stop** button.
|
||||
|
||||
- Wait for the results to appear.
|
||||
- At the bottom of the window you will see a call tree for all CPU threads started, and
|
||||
the **Heaviest Stack Trace** overview.
|
||||
- Select **Hide system libraries** in the **Call Tree** menu (at the bottom of window) to
|
||||
remove external modules.
|
||||
- You can use the timeline at the top of the window to display details for the specific time period.
|
||||
|
||||
.. image:: img/cpp_profiler_time_profiler_result.png
|
||||
@@ -1,210 +0,0 @@
|
||||
.. _doc_using_sanitizers:
|
||||
|
||||
Using sanitizers
|
||||
================
|
||||
|
||||
What are sanitizers?
|
||||
--------------------
|
||||
|
||||
Sanitizers are static instrumentation tools that help find bugs that traditional
|
||||
debuggers usually cannot catch. This is particularly useful when combined with
|
||||
:ref:`doc_unit_testing` in continuous integration.
|
||||
|
||||
Sanitizers can be used on Windows, macOS and Linux by using the Clang (LLVM),
|
||||
GCC or Visual Studio compilers.
|
||||
:ref:`Certain platforms <doc_using_sanitizers_platform_specific_sanitizers>`
|
||||
may also have their own sanitizers available.
|
||||
In situations where a single sanitizer is provided by several different compilers,
|
||||
remember that their output and behavior will differ slightly.
|
||||
|
||||
Using sanitizers on Godot
|
||||
-------------------------
|
||||
|
||||
Sanitizers **require** recompiling the binary. This means you cannot use
|
||||
official Godot binaries to run sanitizers.
|
||||
|
||||
When :ref:`compiling <toc-devel-compiling>` with any of the sanitizers enabled,
|
||||
the resulting binary will have the ``.san`` suffix added to its name to
|
||||
distinguish it from a binary without sanitizers.
|
||||
|
||||
There is a performance impact as many additional runtime checks need to be
|
||||
performed. Memory utilization will also increase. It is possible to enable
|
||||
certain combinations of multiple sanitizers in a single build. Beware of the
|
||||
performance impact when using multiple sanitizers at once though, as the
|
||||
resulting binary may be excessively slow.
|
||||
|
||||
Certain options can be passed to sanitizers without having to recompile the
|
||||
binary using environment variables.
|
||||
|
||||
.. _doc_using_sanitizers_address_sanitizer:
|
||||
|
||||
Address sanitizer (ASAN)
|
||||
------------------------
|
||||
|
||||
- Available in Clang and GCC.
|
||||
- **Supported platforms:** Linux, macOS, Windows (Visual Studio), Web
|
||||
- `Clang ASAN documentation <https://clang.llvm.org/docs/AddressSanitizer.html>`__
|
||||
|
||||
The address sanitizer is generally the most frequently used sanitizer. It can
|
||||
diagnose issues such as buffer overruns and out-of-bounds access. If the engine
|
||||
crashes with a message such as ``free(): invalid pointer``, this is typically
|
||||
the result of a buffer overrun. (This message is printed by the C runtime, not
|
||||
Godot.)
|
||||
|
||||
In certain situations (such as detecting uninitialized memory reads),
|
||||
the address sanitizer doesn't suffice. The :ref:`doc_using_sanitizers_memory_sanitizer`
|
||||
should be used instead.
|
||||
|
||||
It is also possible to detect use-after-return situations by specifying the
|
||||
``ASAN_OPTIONS=detect_stack_use_after_return=1`` environment variable before
|
||||
*running* Godot (not when compiling it). This increases the address sanitizer's
|
||||
runtime overhead, so only enable this feature when you actually need it.
|
||||
|
||||
To enable the address sanitizer in a Godot build, pass the ``use_asan=yes``
|
||||
SCons option when compiling. Enabling ASAN generally makes the resulting binary
|
||||
about 2× slower.
|
||||
|
||||
.. warning::
|
||||
|
||||
Due to a `design decision
|
||||
<https://stackoverflow.com/questions/36971902/why-cant-clang-enable-all-sanitizers/>`__,
|
||||
the address, memory and thread sanitizers are mutually exclusive. This means
|
||||
you can only use one of those sanitizers in a given binary.
|
||||
|
||||
Leak sanitizer (LSAN)
|
||||
---------------------
|
||||
|
||||
- Available in Clang and GCC.
|
||||
- **Supported platforms:** Linux, Web
|
||||
- `Clang LSAN documentation <https://clang.llvm.org/docs/LeakSanitizer.html>`__
|
||||
|
||||
The leak sanitizer can detect memory leaks, which are situations where memory
|
||||
that is no longer in use is never freed by the running program. This can
|
||||
potentially lead to out-of-memory situations if the program runs for long
|
||||
enough. Since Godot may run on
|
||||
:ref:`dedicated servers <doc_exporting_for_dedicated_servers>` for months or
|
||||
even years without a restart, it's important to fix memory leaks when they occur.
|
||||
|
||||
To enable the leak sanitizer in a Godot build, pass the ``use_lsan=yes`` SCons
|
||||
option when compiling. Enabling LSAN only has a small performance overhead, but
|
||||
the program will be much slower to exit as leak detection occurs when the
|
||||
program exits.
|
||||
|
||||
.. _doc_using_sanitizers_memory_sanitizer:
|
||||
|
||||
Memory sanitizer (MSAN)
|
||||
-----------------------
|
||||
|
||||
- Available in Clang only, not GCC.
|
||||
- **Supported platforms:** Linux
|
||||
- `Clang MSAN documentation <https://clang.llvm.org/docs/MemorySanitizer.html>`__
|
||||
|
||||
The memory sanitizer complements the
|
||||
:ref:`doc_using_sanitizers_address_sanitizer`. Unlike the address sanitizer,
|
||||
the memory sanitizer can detect uninitialized memory reads.
|
||||
|
||||
To enable the memory sanitizer in a Godot build, pass the ``use_msan=yes``
|
||||
SCons option when compiling. Enabling MSAN generally makes the resulting binary
|
||||
about 3× slower.
|
||||
|
||||
.. warning::
|
||||
|
||||
Due to a `design decision
|
||||
<https://stackoverflow.com/questions/36971902/why-cant-clang-enable-all-sanitizers/>`__,
|
||||
the address, memory and thread sanitizers are mutually exclusive. This means
|
||||
you can only use one of those sanitizers in a given binary.
|
||||
|
||||
Thread sanitizer (TSAN)
|
||||
-----------------------
|
||||
|
||||
- Available in Clang and GCC.
|
||||
- **Supported platforms:** Linux, macOS
|
||||
- `Clang TSAN documentation <https://clang.llvm.org/docs/ThreadSanitizer.html>`__
|
||||
|
||||
The thread sanitizer is used to track down race conditions related to
|
||||
multithreading. A race condition is when multiple threads try to modify the same
|
||||
data at the same time. Since thread scheduling can be ordered in any fashion by
|
||||
the operating system, this leads to incorrect behavior that only occurs
|
||||
occasionally (and can be difficult to track as a result). To prevent a race
|
||||
condition, you need to add a lock to ensure only one thread can access the
|
||||
shared data at a given time.
|
||||
|
||||
To enable the thread sanitizer in a Godot build, pass the ``use_tsan=yes`` SCons
|
||||
option when compiling. Enabling TSAN generally makes the resulting binary 10×
|
||||
slower, while also multiplying memory usage by an approximately 8× factor.
|
||||
|
||||
.. warning::
|
||||
|
||||
Due to a `design decision
|
||||
<https://stackoverflow.com/questions/36971902/why-cant-clang-enable-all-sanitizers/>`__,
|
||||
the address, memory and thread sanitizers are mutually exclusive. This means
|
||||
you can only use one of those sanitizers in a given binary.
|
||||
|
||||
.. note::
|
||||
|
||||
On Linux, if you stumble upon the following error:
|
||||
|
||||
``FATAL: ThreadSanitizer: unexpected memory mapping``
|
||||
|
||||
You may need to temporarily lower the Address Space Layout Randomization (ASLR) entropy in your system with:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
sudo sysctl vm.mmap_rnd_bits=28
|
||||
|
||||
Or preferably disable it entirely with:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
sudo sysctl kernel.randomize_va_space=0
|
||||
|
||||
And as soon as you are done with the thread sanitizer, increase the ASLR entropy with:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
sudo sysctl vm.mmap_rnd_bits=32
|
||||
|
||||
Or re-enable ASLR with:
|
||||
|
||||
.. code:: sh
|
||||
|
||||
sudo sysctl kernel.randomize_va_space=2
|
||||
|
||||
Rebooting your machine will also revert the ASLR state to its default values.
|
||||
|
||||
It's important to revert the changes as soon as possible because lowering the ASLR entropy or disabling ASLR entirely can be a security risk.
|
||||
|
||||
Undefined behavior sanitizer (UBSAN)
|
||||
------------------------------------
|
||||
|
||||
- Available in Clang and GCC.
|
||||
- **Supported platforms:** Linux, macOS, Web
|
||||
- `Clang UBSAN documentation <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`__
|
||||
|
||||
The undefined behavior sanitizer is used to track down situations where the
|
||||
program exhibits random and unpredictable behavior. This is due to C/C++ code
|
||||
that is accepted by the compiler, but is not *correct*. Compiling with a
|
||||
different set of optimizations can also change the observed results of undefined
|
||||
behavior.
|
||||
|
||||
To enable the undefined behavior sanitizer in a Godot build, pass the
|
||||
``use_ubsan=yes`` SCons option when compiling. Enabling UBSAN only has a small
|
||||
performance overhead.
|
||||
|
||||
.. _doc_using_sanitizers_platform_specific_sanitizers:
|
||||
|
||||
Platform-specific sanitizers
|
||||
----------------------------
|
||||
|
||||
Web
|
||||
~~~
|
||||
|
||||
When :ref:`compiling for the Web <doc_compiling_for_web>`,
|
||||
there are 2 additional sanitizer SCons options available:
|
||||
|
||||
- ``use_assertions=yes`` enables runtime Emscripten assertions, which can catch
|
||||
various issues.
|
||||
- ``use_safe_heap=yes`` enables `Emscripten's SAFE_HEAP sanitizer <https://emscripten.org/docs/debugging/Sanitizers.html>`__.
|
||||
It provides similar functionality to ASAN, but it focuses on issues that
|
||||
are specific to WebAssembly. ``SAFE_HEAP`` is not guaranteed to be compatible
|
||||
with ASAN and UBSAN in the same binary, so you may have to build it separately.
|
||||
@@ -1,10 +0,0 @@
|
||||
:allow_comments: False
|
||||
|
||||
Vulkan
|
||||
======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:name: toc-devel-vulkan
|
||||
|
||||
vulkan_validation_layers
|
||||
@@ -1,190 +0,0 @@
|
||||
.. _doc_vulkan_validation_layers:
|
||||
|
||||
Validation layers
|
||||
=================
|
||||
|
||||
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.
|
||||
|
||||
.. 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
|
||||
-------
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Build validation layers from official sources
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To build Android libraries, follow the instructions on
|
||||
`Khronos' repository <https://github.com/KhronosGroup/Vulkan-ValidationLayers/blob/master/BUILD.md#building-on-android>`__.
|
||||
After a successful build, the libraries will be located in ``Vulkan-ValidationLayers/build-android/libs``.
|
||||
|
||||
Copy libraries
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Copy libraries from ``Vulkan-ValidationLayers/build-android/libs`` to
|
||||
``godot/platform/android/java/app/libs/debug/vulkan_validation_layers``.
|
||||
|
||||
Your Godot source directory tree should look like on the example below:
|
||||
|
||||
::
|
||||
|
||||
godot
|
||||
|-- platform
|
||||
|-- android
|
||||
|-- java
|
||||
|-- app
|
||||
|-- libs
|
||||
|-- debug
|
||||
|-- vulkan_validation_layers
|
||||
|-- arm64-v8a
|
||||
|-- armeabi-v7a
|
||||
|-- x86
|
||||
|-- x86_64
|
||||
|
||||
If the subdirectory ``libs/debug/vulkan_validation_layers`` doesn't exist, create it.
|
||||
|
||||
Compile and run the Android app
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Linked validation layers are automatically loaded and enabled in Android debug builds.
|
||||
You can use Godot's :ref:`doc_one-click_deploy` feature to quickly test your project with the validation layers enabled.
|
||||
Reference in New Issue
Block a user