diff --git a/documentation/source/development/building.rst b/documentation/source/development/building.rst index 8e6aa38d3..296d59f5e 100644 --- a/documentation/source/development/building.rst +++ b/documentation/source/development/building.rst @@ -97,9 +97,6 @@ If you have `Ninja build system `__ installed, you can # Build all targets \> cmake --build ./cmake-build-debug/ -.. note:: - If you use CMake GUI add `CMAKE_BUILD_TYPE` with value `Debug` or `Release`. `#228 `__. - - Choose any IDE that CMake can generate a project map for. If in doubt use `Visual Studio 2019 `__. - Clone the source code. Free and good tools are `GitHub Desktop `__ or `GitKraken Git GUI `__. - Open CMake and select the root folder which contains ``CMakeLists.txt`` (not just ``src`` folder!). diff --git a/documentation/source/development/reference/error-handling.rst b/documentation/source/development/reference/error-handling.rst new file mode 100644 index 000000000..f54fd1cd6 --- /dev/null +++ b/documentation/source/development/reference/error-handling.rst @@ -0,0 +1,29 @@ +Error handling +============== + +Inexor uses `exceptions `__ as for error handling, as it is proposed by the `C++ core guidelines `__. It should only be used for error handling and mainly in code areas which are not performance critical. It also should only be used for *exceptional errors*, which can't be ignored easily. Exceptions are not without criticism, but all alternatives (like return codes for examples) are not free either. In some areas, as in constructors for example, no return codes can be used at all. A detailed discussion why to use exceptions can be found `here `__. + +Spdlog +------ + +- Inexor uses `spdlog `__ for console output and log messages +- Use ``spdlog::trace``, ``spdlog::debug``, ``spdlog::info``, ``spdlog::warning``, ``spdlog::error``, and ``spdlog::critical`` + +Custom exception classes +------------------------ + +- Inexor has a custom base class for exceptions called ``InexorException`` which inherits from ``std::runtime_error`` +- For exceptions which are thrown because a Vulkan function call failed, ``VulkanException`` is used +- ``VulkanException`` constructor takes an error message as ``std::string`` and the ``VkResult`` value +- The constructor of ``VulkanException`` will turn the ``VkResult`` into a human readable error message (like ``VK_ERROR_INITIALIZATION_FAILED``) and a user friendly error description (in this case "Initialization of an object could not be completed for implementation-specific reasons.") +- In order to be able to pass the ``VkResult`` of a Vulkan function call to the exception, it should be stored in a `C++17 if statement with initializer `__ (see example) + +**Example** + +.. code-block:: cpp + + if (const auto result = vkEnumerateInstanceLayerProperties(&instance_layer_count, nullptr); result != VK_SUCCESS) { + throw VulkanException("Error: vkEnumerateInstanceLayerProperties failed!", result); + } + +Example result: ``Error: vkEnumerateInstanceLayerProperties failed! (VK_ERROR_OUT_OF_HOST_MEMORY: A host memory allocation has failed.)`` diff --git a/documentation/source/development/reference/main.rst b/documentation/source/development/reference/main.rst index 178ce2a43..325bf4f09 100644 --- a/documentation/source/development/reference/main.rst +++ b/documentation/source/development/reference/main.rst @@ -5,8 +5,9 @@ Reference .. toctree:: :maxdepth: 1 - gpu-selection binary-format-specification + error-handling + gpu-selection keyboard-mouse-input octree-file-format octree-collision