TMP / Updated guides

docs/DevelopmentSetupGuide.md

@@ -1,63 +1,93 @@
 # Development setup guide
 
-To make development  easier, contributors should be using a few  tools. Included
-with the project are configurations and scripts for these tools:
-  - [cppcheck](http://cppcheck.net/) – performs static code analysis for C++
-  - [clang-format](https://clang.llvm.org/docs/ClangFormat.html) – automatically
-      formats C++ source code
-  - [memcheck](https://valgrind.org/docs/manual/mc-manual.html)
-      (part of  [valgrind](https://valgrind.org/))  –  performs  runtime  memory
-      error detection
+This document  provides instructions for  setting up a development  environment
+for Progressia.
+See also
+    [Building Guide](BuildingGuide.md)
+and
+    [IDE setup guides](ide_setup).
 
-Additionally, git  hooks prevent committing code that  is formatted incorrectly,
-does  not  compile  or  produces  warnings. You  can  bypass  this  check  using
+To make development easier, contributors  should be using a few tools. Included
+with the project are configurations and scripts for these tools:
+  - [clang-tidy](https://clang.llvm.org/extra/clang-tidy/)  –  performs  static
+      code analysis for C++
+  - [clang-format](https://clang.llvm.org/docs/ClangFormat.html) – formats  C++
+      source code
+  - Vulkan validation layers – checks for errors in Vulkan API usage at runtime
+      (see below for details)
+  - [memcheck](https://valgrind.org/docs/manual/mc-manual.html)
+      (part of  [valgrind](https://valgrind.org/))  –  performs runtime  memory
+      error detection on Linux
+
+Additionally, a git pre-commit hook prevents  committing code that is formatted
+incorrectly, does not compile or produces warnings.
+
+## Basic setup
+Follow [Building Guide](BuildingGuide.md) instructions before proceeding.
+
+Debian/Ubuntu:
+```bash
+# Install clang-tidy and clang-format-diff
+sudo apt update && sudo apt install -y \
+    clang-tidy clang-format
+
+# Enable DEV_MODE (sets up git pre-commit hook)
+cmake -S . -B build -DDEV_MODE=ON
+```
+
+Fedora:
+```bash
+# Install clang-tidy and clang-format-diff
+sudo dnf install -y \
+    clang-tools-extra clang
+
+# Enable DEV_MODE (sets up git pre-commit hook)
+cmake -S . -B build -DDEV_MODE=ON
+```
+
+Windows: _see [IDE setup guides](ide_setup)._
+
+## Pre-commit git hook
+
+A
+[git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
+is installed to  correct formatting  and check for  compilation/linting issues.
+This check can be bypassed with
   `git commit --no-verify`
 in case of dire need.
 
-## Prerequisites
+The hook runs `tools/pre-commit.py`, which formats  modified files  and ensures
+that `cmake --build build` executes without  errors. Several git operations are
+performed by `pre-commit.py`; run
+  `tools/pre-commit.py restore`
+to restore the state of the repository in case the hook crashes.
 
-Perform the setup described in the [Building Guide](BuildingGuide.md) first.
+The list of directories with source code  to format and the list of source code
+filename extensions are hard-coded into the Python script.
 
-Install the following software:
-  - cppcheck,
-  - clang-format (version 13 is recommended)
-  - valgrind
+## Vulkan validation layers
 
-### Debian
-
-On Debian, you can run the following commands as root to install all required
-software:
-```bash
-apt-get install \
-    cppcheck \
-    clang-format-13 \
-    valgrind
-```
-
-## Setup
-
-```bash
-tools/setup.sh --for-development
-```
-
-With `--for-development` flag, `tools/setup.sh` will check the development tools
-and install git pre-commit hook in addition to its normal duties.
-
-## Notes
-
-Developers will find it useful to read through the following help pages:
-```bash
-tools/build.sh --help
-tools/cppcheck/use-cppcheck.sh --help
-tools/clang-format/use-clang-format.sh --help
-```
-
-LunarG validation layers are extremely useful when writing and debugging Vulkan.
+LunarG validation layers are extremely useful when debugging Vulkan code.
 The official
 [Vulkan tutorial](https://vulkan-tutorial.com/Development_environment)
 has detailed instructions for all platforms.
 
-In particular, Debian users can run the following command as root:
+Use CMake  option  `VULKAN_ERROR_CHECKING`  to  enable the  use  of  validation
+layers.
+
+Debian/Ubuntu users can install this dependency using APT:
 ```bash
-apt-get install vulkan-validationlayers-dev
+apt install vulkan-validationlayers-dev
 ```
+
+Fedora users can install this dependency using dnf:
+```bash
+dnf install vulkan-validation-layers-devel
+```
+
+Windows users can install this dependency when installing LunarG distribution.
+
+## memcheck
+
+`tools/valgrind-memcheck-suppressions.supp` contains useful suppressions for
+memcheck.