Initial commit

docs/BuildingGuide.md

@@ -0,0 +1,88 @@
+# Building guide
+
+At this time, building  is only supported in GNU/Linux  targeting GNU/Linux X11.
+See also [Development Setup Guide](DevelopmentSetupGuide.md) if you want to make
+git commits.
+
+## Prerequisites
+
+Install the following software:
+  - a C++ compiler (GCC or clang preferably),
+  - CMake,
+  - pkg-config,
+  - Python 3,
+  - glslc.
+
+Install the following libraries with headers:
+  - Vulkan (loader library and headers),
+  - GLFW3,
+  - GLM,
+  - STB,
+  - Boost (only core library required).
+
+### Debian
+
+On Debian, you  can run  the following  commands  as root  to install almost all
+required software:
+```bash
+apt-get install \
+    g++ \
+    cmake \
+    pkg-config \
+    python3 &&
+apt-get install --no-install-recommends \
+    libvulkan-dev \
+    libglfw3-dev \
+    libglm-dev \
+    libstb-dev \
+    libboost-dev
+```
+
+However, glslc, the shader compiler, is not available as a Debian package at the
+moment. You can install it manually from official sources or use the download it
+from windcorp.ru by running these commands as root:
+```bash
+apt-get install wget &&
+mkdir -p /opt/glslc &&
+wget --output-file=/opt/glslc/glslc \
+     'https://windcorp.ru/other/glslc-v2022.1-6-ga0a247d-static' &&
+chmod +x /opt/glslc/glslc
+```
+
+Alternatively, packages provided by  LunarG are available for Ubuntu. Follow the
+instructions   on  [LunarG.com](https://vulkan.lunarg.com/sdk/home)   to install
+`vulkan-sdk`.
+
+## Setup
+
+```bash
+git clone <clone url>
+cd Progressia
+chmod +x tools/setup.sh
+tools/setup.sh
+```
+
+`tools/setup.sh`  will  check  the availability  of  all  required commands  and
+libraries.
+
+Build   tools    use   enviroment   variables    `PATH`, `PKG_CONFIG_PATH`   and
+`CMAKE_MODULE_PATH`;  you  can   edit   these  variables   system-wide   or  use
+`tools/private.sh` to make project-specific changes.
+(Your changes to `tools/private.sh` are ignored by git.)
+For example, of you ran the script to download glslc on Debian, you will need to
+add the following line to `tools/private.sh`:
+```bash
+PATH="$PATH:/opt/glslc"
+```
+
+## Building
+
+```bash
+tools/build.sh
+```
+
+## Running
+
+```bash
+tools/build.sh -R
+```

docs/DevelopmentSetupGuide.md

@@ -0,0 +1,63 @@
+# 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
+
+Additionally, git  hooks prevent committing code that  is formatted incorrectly,
+does  not  compile  or  produces  warnings. You  can  bypass  this  check  using
+  `git commit --no-verify`
+in case of dire need.
+
+## Prerequisites
+
+Perform the setup described in the [Building Guide](BuildingGuide.md) first.
+
+Install the following software:
+  - cppcheck,
+  - clang-format (version 13 is recommended)
+  - valgrind
+
+### 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.
+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:
+```bash
+apt-get install vulkan-validationlayers-dev
+```