From eacf1066e5008646fb1178912911c741868a297f Mon Sep 17 00:00:00 2001
From: Patrick Stotko <stotko@cs.uni-bonn.de>
Date: Sun, 3 Sep 2023 14:14:03 +0200
Subject: [PATCH] docs: Add overhauled Getting Started guide

---
 README.md                                     | 144 +-------
 docs/development/contributing.md              |   2 +-
 .../development/contributing/documentation.md |   2 +-
 docs/development/contributing/tests.md        |   2 +-
 docs/getting_started/building_from_source.md  | 322 ++++++++++++++++++
 .../integrating_into_your_project.md          |  90 +++++
 docs/index.md                                 |   8 +
 7 files changed, 429 insertions(+), 141 deletions(-)
 create mode 100644 docs/getting_started/building_from_source.md
 create mode 100644 docs/getting_started/integrating_into_your_project.md

diff --git a/README.md b/README.md
index d9016a7a9..c5428236f 100644
--- a/README.md
+++ b/README.md
@@ -36,9 +36,7 @@
 <p align="center">
 <a style="font-weight:bold" href="#features">Features</a> |
 <a style="font-weight:bold" href="#examples">Examples</a> |
-<a style="font-weight:bold" href="#documentation">Documentation</a> |
-<a style="font-weight:bold" href="#building">Building</a> |
-<a style="font-weight:bold" href="#integration">Integration</a> |
+<a style="font-weight:bold" href="#getting-started">Getting Started</a> |
 <a style="font-weight:bold" href="#contributing">Contributing</a> |
 <a style="font-weight:bold" href="#license">License</a> |
 <a style="font-weight:bold" href="#contact">Contact</a>
@@ -154,144 +152,14 @@ compute_update_set(const short3* blocks,
 More examples can be found in the [`examples`](https://github.com/stotko/stdgpu/tree/master/examples) directory.
 
 
-## Documentation
+## Getting Started
 
-A comprehensive introduction into the design and API of stdgpu can be found here:
+stdgpu requires a **C++17 compiler** as well as minimal backend dependencies and can be easily built and integrated into your project via **CMake**:
 
-- [stdgpu API documentation](https://stotko.github.io/stdgpu)
-- [thrust algorithms documentation](https://thrust.github.io/doc/group__algorithms.html)
-- [Research paper](https://www.researchgate.net/publication/335233070_stdgpu_Efficient_STL-like_Data_Structures_on_the_GPU)
+- [Building From Source](https://stotko.github.io/stdgpu/getting_started/building_from_source.html)
+- [Integrating Into Your Project](https://stotko.github.io/stdgpu/getting_started/integrating_into_your_project.html)
 
-Since a core feature and design goal of stdgpu is its **interoperability** with thrust, it offers **full support for all thrust algorithms** instead of reinventing the wheel. More information about the design can be found in the related [research paper](https://www.researchgate.net/publication/335233070_stdgpu_Efficient_STL-like_Data_Structures_on_the_GPU).
-
-
-## Building
-
-Before building the library, please make sure that all required tools and dependencies are installed on your system. Newer versions are supported as well.
-
-**Required**
-
-- C++17 compiler
-    - GCC 9
-        - (Ubuntu 20.04/22.04) `sudo apt install g++`
-    - Clang 10
-        - (Ubuntu 20.04/22.04) `sudo apt install clang`
-    - MSVC 19.20
-        - (Windows) Visual Studio 2019 <https://visualstudio.microsoft.com/downloads/>
-- CMake 3.18
-    - (Ubuntu 20.04) <https://apt.kitware.com>
-    - (Ubuntu 22.04) `sudo apt install cmake`
-    - (Windows) <https://cmake.org/download>
-- thrust 1.9.9
-    - (Ubuntu/Windows) <https://github.com/NVIDIA/thrust>
-    - May already be installed by backend dependencies
-
-**Required for CUDA backend**
-
-- CUDA compiler
-    - NVCC
-        - Already included in CUDA Toolkit
-    - Clang 10
-        - (Ubuntu 20.04/22.04) `sudo apt install clang`
-- CUDA Toolkit 11.0
-    - (Ubuntu/Windows) <https://developer.nvidia.com/cuda-downloads>
-    - Includes thrust
-
-**Required for OpenMP backend**
-
-- OpenMP 2.0
-    - GCC 9
-        - (Ubuntu 20.04/22.04) Already installed
-    - Clang 10
-        - (Ubuntu 20.04/22.04) `sudo apt install libomp-dev`
-    - MSVC 19.20
-        - (Windows) Already installed
-
-**Required for HIP backend (experimental)**
-
-- HIP compiler
-    - Clang
-        - Already included in ROCm
-- ROCm 5.1
-    - (Ubuntu) <https://github.com/RadeonOpenCompute/ROCm>
-    - Includes thrust
-- CMake 3.21.3
-    - (Ubuntu 20.04) <https://apt.kitware.com>
-    - (Ubuntu 22.04) `sudo apt install cmake`
-    - (Windows) <https://cmake.org/download>
-    - Required for first-class HIP language support
-
-
-The library can be built as every other project which makes use of the CMake build system.
-
-In addition, we also provide cross-platform scripts to make the build process more convenient. Since these scripts depend on the selected build type, there are scripts for both `debug` and `release` builds.
-
-Command | Effect
---- | ---
-`bash tools/setup.sh [<build_type>]` | Performs a full clean build of the project. Removes old build, configures the project (build path: `./build`, default build type: `Release`), builds the project, and runs the unit tests.
-`bash tools/build.sh [<build_type>]` | (Re-)Builds the project. Requires that the project is set up (default build type: `Release`).
-`bash tools/run_tests.sh [<build_type>]` | Runs the unit tests. Requires that the project is built (default build type: `Release`).
-`bash tools/install.sh [<build_type>]` | Installs the project to the configured install path (default install dir: `./bin`, default build type: `Release`).
-`bash tools/uninstall.sh [<build_type>]` | Uninstalls the project from the configured install path (default build type: `Release`).
-
-
-## Integration
-
-In the following, we show some examples on how the library can be integrated into and used in a project.
-
-
-**CMake Integration**. To use the library in your project, you can either install it externally first and then include it using `find_package`:
-
-```cmake
-find_package(stdgpu 1.0.0 REQUIRED)
-
-add_library(foo ...)
-
-target_link_libraries(foo PUBLIC stdgpu::stdgpu)
-```
-
-Or you can embed it into your project and build it from a subdirectory:
-
-```cmake
-# Exclude the examples from the build
-set(STDGPU_BUILD_EXAMPLES OFF CACHE INTERNAL "")
-
-# Exclude the benchmarks from the build
-set(STDGPU_BUILD_BENCHMARKS OFF CACHE INTERNAL "")
-
-# Exclude the tests from the build
-set(STDGPU_BUILD_TESTS OFF CACHE INTERNAL "")
-
-add_subdirectory(stdgpu)
-
-add_library(foo ...)
-
-target_link_libraries(foo PUBLIC stdgpu::stdgpu)
-```
-
-
-**CMake Options**. To configure the library, two sets of options are provided. The following build options control the build process:
-
-Build Option | Effect | Default
---- | --- | ---
-`STDGPU_BACKEND` | Device system backend | `STDGPU_BACKEND_CUDA`
-`STDGPU_BUILD_SHARED_LIBS` | Builds the project as a shared library, if set to `ON`, or as a static library, if set to `OFF` | `BUILD_SHARED_LIBS`
-`STDGPU_SETUP_COMPILER_FLAGS` | Constructs the compiler flags | `ON` if standalone, `OFF` if included via `add_subdirectory`
-`STDGPU_COMPILE_WARNING_AS_ERROR` | Treats compiler warnings as errors | `OFF`
-`STDGPU_BUILD_EXAMPLES` | Build the examples | `ON`
-`STDGPU_BUILD_BENCHMARKS` | Build the benchmarks | `ON`
-`STDGPU_BUILD_TESTS` | Build the unit tests | `ON`
-`STDGPU_BUILD_TEST_COVERAGE` | Build a test coverage report | `OFF`
-`STDGPU_ANALYZE_WITH_CLANG_TIDY` | Analyzes the code with clang-tidy | `OFF`
-`STDGPU_ANALYZE_WITH_CPPCHECK` | Analyzes the code with cppcheck | `OFF`
-
-
-In addition, the implementation of some functionality can be controlled via configuration options:
-
-Configuration Option | Effect | Default
---- | --- | ---
-`STDGPU_ENABLE_CONTRACT_CHECKS` | Enable contract checks | `OFF` if `CMAKE_BUILD_TYPE` equals `Release` or `MinSizeRel`, `ON` otherwise
-`STDGPU_USE_32_BIT_INDEX` | Use 32-bit instead of 64-bit signed integer for `index_t` | `ON`
+More guidelines as well as a comprehensive introduction into the design and API of stdgpu can be found in the [documentation](https://stotko.github.io/stdgpu).
 
 
 ## Contributing
diff --git a/docs/development/contributing.md b/docs/development/contributing.md
index 51c98e80e..440b9e587 100644
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -30,7 +30,7 @@ To submit your changes, follow the standard *Fork & Pull Request Workflow*:
 5. Push the branch to your fork.
 6. Open a new pull request with a brief motivation of the problem and how you addressed it in your changes. If there already exists a related [GitHub Issue](https://github.com/stotko/stdgpu/issues), please mention it there as well.
 
-You can find more information for the development of your changes in the [building guide](../index.md#building) as well as on the following pages:
+You can find more information for the development of your changes in the [building guide](../getting_started/building_from_source.md) as well as on the following pages:
 
 
 :::::{grid} 2 2 3 3
diff --git a/docs/development/contributing/documentation.md b/docs/development/contributing/documentation.md
index f6f5caa60..237f97a7c 100644
--- a/docs/development/contributing/documentation.md
+++ b/docs/development/contributing/documentation.md
@@ -37,7 +37,7 @@ bash tools/dev/build_documentation.sh
 
 
 :::{note}
-The `STDGPU_BUILD_DOCUMENTATION` option must be enabled for this purpose, e.g. via `-D<option>=<value>`, see [Configuration Options](../../index.md#integration).
+The `STDGPU_BUILD_DOCUMENTATION` option must be enabled for this purpose, e.g. via `-D<option>=<value>`, see [](../../getting_started/building_from_source.md#configuration-options).
 :::
 
 
diff --git a/docs/development/contributing/tests.md b/docs/development/contributing/tests.md
index 135565226..5c7932601 100644
--- a/docs/development/contributing/tests.md
+++ b/docs/development/contributing/tests.md
@@ -28,5 +28,5 @@ bash tools/run_tests.sh Release
 
 
 :::{note}
-The `STDGPU_BUILD_TESTS` option must be enabled to also compile the tests, which is already the default if not manually altered, see [Configuration Options](../../index.md#integration).
+The `STDGPU_BUILD_TESTS` option must be enabled to also compile the tests, which is already the default if not manually altered, see [](../../getting_started/building_from_source.md#configuration-options).
 :::
diff --git a/docs/getting_started/building_from_source.md b/docs/getting_started/building_from_source.md
new file mode 100644
index 000000000..af7857399
--- /dev/null
+++ b/docs/getting_started/building_from_source.md
@@ -0,0 +1,322 @@
+# Building From Source
+
+This guide shows you how to build stdgpu from source. Since we use CMake for cross-platform building, the building instructions should work across operating systems and distributions. Furthermore, the prerequisites cover specific instructions to install the build dependencies on Linux (Ubuntu) and Windows.
+
+
+## Prerequisites
+
+Before building the library, please make sure that all required development tools and dependencies for the respective backend are installed on your system. The following table shows the **minimum required versions** of each depenency. *Newer versions* of these tools are supported as well.
+
+
+::::::{tab-set}
+
+:::::{tab-item} Linux (Ubuntu)
+:sync: linux
+
+::::{tab-set}
+
+:::{tab-item} CUDA
+:sync: cuda
+
+- C++17 compiler
+    - GCC 9: `sudo apt install g++`
+    - Clang 10: `sudo apt install clang`
+- CUDA compiler
+    - NVCC (Already included in CUDA Toolkit)
+    - Clang 10: `sudo apt install clang`
+- CUDA Toolkit 11.0: <https://developer.nvidia.com/cuda-downloads>
+- CMake 3.18: `sudo apt install cmake`
+
+:::
+
+:::{tab-item} OpenMP
+:sync: openmp
+
+- C++17 compiler with OpenMP 2.0
+    - GCC 9: `sudo apt install g++`
+    - Clang 10: `sudo apt install clang libomp-dev`
+- CMake 3.18: `sudo apt install cmake`
+- thrust 1.9.9: <https://github.com/NVIDIA/thrust>
+
+:::
+
+:::{tab-item} HIP (experimental)
+:sync: hip
+
+- C++17 compiler
+    - GCC 9: `sudo apt install g++`
+    - Clang 10: `sudo apt install clang`
+- HIP compiler
+    - Clang (Already included in ROCm)
+- ROCm 5.1 <https://github.com/RadeonOpenCompute/ROCm>
+- CMake 3.21.3: `sudo apt install cmake`
+
+:::
+
+::::
+
+:::::
+
+:::::{tab-item} Windows
+:sync: windows
+
+::::{tab-set}
+
+:::{tab-item} CUDA
+:sync: cuda
+
+- C++17 compiler
+    - MSVC 19.20 (Visual Studio 2019) <https://visualstudio.microsoft.com/downloads/>
+- CUDA compiler
+    - NVCC (Already included in CUDA Toolkit)
+- CUDA Toolkit 11.0: <https://developer.nvidia.com/cuda-downloads>
+- CMake 3.18: <https://cmake.org/download>
+
+:::
+
+:::{tab-item} OpenMP
+:sync: openmp
+
+- C++17 compiler including OpenMP 2.0
+    - MSVC 19.20 (Visual Studio 2019) <https://visualstudio.microsoft.com/downloads/>
+- CMake 3.18: <https://cmake.org/download>
+- thrust 1.9.9: <https://github.com/NVIDIA/thrust>
+
+:::
+
+:::{tab-item} HIP (experimental)
+:sync: hip
+
+- C++17 compiler
+    - MSVC 19.20 (Visual Studio 2019) <https://visualstudio.microsoft.com/downloads/>
+- HIP compiler
+    - Clang (Already included in ROCm)
+- ROCm 5.1 <https://github.com/RadeonOpenCompute/ROCm>
+- CMake 3.21.3: <https://cmake.org/download>
+
+:::
+
+::::
+
+:::::
+
+::::::
+
+While the instructions will likely also work for instance for Debian, other Linux distributions (e.g. Arch Linux and derivatives) may use a different naming scheme for the required packages.
+
+
+## Downloading the Source Code
+
+In order to get the source code needed for building, the most common approach is to clone the upstream GitHub repository.
+
+```sh
+git clone https://github.com/stotko/stdgpu
+```
+
+
+## Build Instructions
+
+Since stdgpu is built with CMake, the usual steps for building CMake-based projects can be performed here as well. In the examplary instructions below, we built stdgpu in **Release** mode and installed it into a local **bin** directory. Different modes and installation directories works can be used in a similar way.
+
+
+### Configuring
+
+First, a build directory (usually `build/`) should be created and the build configuration should be evaluated by CMake and stored into this directory.
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+mkdir build
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=bin
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/backend/configure_cuda.sh Release
+```
+
+:::
+
+::::
+
+
+If you leave out `CMAKE_INSTALL_PREFIX`, CMake will automatically select an appropriate (platform-dependent) system directory for installation instead.
+
+
+:::{seealso}
+A complete list of options used via `-D<option>=<value>` to control the build of stdgpu can be found in [](#configuration-options).
+:::
+
+
+### Compiling
+
+Then, the library itself as well as further components (examples, benchmarks, or tests depending on the configuration) are compiled. To speed-up the compilation, the maximum number of parallel jobs used for building can be specified to override the default number.
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake --build build --config Release --parallel 8
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/build.sh Release
+```
+
+:::
+
+::::
+
+
+### Testing
+
+Running the unit tests is **optional** but *recommended* to verify that all features of stdgpu work correctly on your system. This requires the CMake option `STDGPU_BUILD_TESTS` to be set to `ON` during configuration (already the default if not altered), see [](#configuration-options) for a complete list of options.
+
+::::{tab-set}
+
+:::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake -E chdir build ctest -V -C Release
+```
+
+:::
+
+:::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/run_tests.sh Release
+```
+
+:::
+
+::::
+
+
+### Installing
+
+As a final **optional** step, you can install the locally compiled version of stdgpu on your system.
+
+:::::{tab-set}
+
+::::{tab-item} Direct Command
+:sync: direct
+
+```sh
+cmake --install build --config Release
+```
+
+:::{admonition} Uninstalling
+:class: tip dropdown
+If the `build/` directory from which stdgpu has been installed has not been deleted, you can also revert the installation by calling the `uninstall` target:
+
+```sh
+cmake --build build --config Release --target uninstall
+```
+:::
+
+::::
+
+::::{tab-item} Provided Script
+:sync: script
+
+```sh
+bash tools/install.sh Release
+```
+
+:::{admonition} Uninstalling
+:class: tip dropdown
+If the `build/` directory from which stdgpu has been installed is still present, you can revert the installation by running the `uninstall` script:
+
+```sh
+bash tools/uninstall.sh Release
+```
+:::
+
+::::
+
+:::::
+
+
+
+## Configuration Options
+
+Building stdgpu from source can be customized in various ways. The following list of CMake options divided into *build-related* and *library-related* options can be used for this purpose.
+
+
+### Build-related Options
+
+The build process can be controlled by the following options and allow to enable/disable certains parts of the library sources:
+
+`STDGPU_BACKEND`
+: Selected device system backend. Must be either `STDGPU_BACKEND_CUDA`, `STDGPU_BACKEND_OPENMP`, or `STDGPU_BACKEND_HIP`. \
+**default:** `STDGPU_BACKEND_CUDA`
+
+`STDGPU_BUILD_SHARED_LIBS`
+: Build the project as a shared library if set to `ON`, or as a static library if set to `OFF`. \
+**default:** `BUILD_SHARED_LIBS`
+
+`STDGPU_SETUP_COMPILER_FLAGS`
+: Construct and use a set of common compiler flags for the C++ and further involved compilers (e.g. the CUDA compiler). This is usually only useful if stdgpu is built as a standalone project. \
+**default:** `ON` if standalone, `OFF` if included via `add_subdirectory` or `FetchContent`
+
+`STDGPU_COMPILE_WARNING_AS_ERROR`
+: Treat compiler warnings as errors. Useful in CI environments. \
+**default:** `OFF`
+
+`STDGPU_BUILD_DOCUMENTATION`
+: Enable building the documentation. Note that this will not actually generate the documentation during building, which instead must be separately built using a dedicated CMake target/script. \
+**default:** `OFF`
+
+`STDGPU_BUILD_EXAMPLES`
+: Enable building the examples. \
+**default:** `ON`
+
+`STDGPU_BUILD_BENCHMARKS`
+: Enable building the benchmarks. \
+**default:** `ON`
+
+`STDGPU_BUILD_TESTS`
+: Enable building the tests. \
+**default:** `ON`
+
+`STDGPU_BUILD_TEST_COVERAGE`
+: Enable building a test coverage report. Note that this will not actually generate the report during building, which instead must be separately built using a dedicated CMake target/script. \
+**default:** `OFF`
+
+`STDGPU_ANALYZE_WITH_CLANG_TIDY`
+: Analyze the code with clang-tidy while building. \
+**default:** `OFF`
+
+`STDGPU_ANALYZE_WITH_CPPCHECK`
+: Analyze the code with cppcheck while building. \
+**default:** `OFF`
+
+
+### Library-related Options
+
+In addition, the behavior of the library implementation can also be customized to, e.g., provide maximum performance:
+
+`STDGPU_ENABLE_CONTRACT_CHECKS`
+: Enable contract checks. Useful for debugging purposes, but comes with a significant impact on the runtime performance. \
+**default:** `OFF` if `CMAKE_BUILD_TYPE` equals `Release` or `MinSizeRel`, `ON` otherwise
+
+`STDGPU_USE_32_BIT_INDEX`
+: Use 32-bit instead of 64-bit signed integer for `index_t`. Useful for tuning the performance if processing of more than 2.1 billion elements is not required. \
+**default:** `ON`
diff --git a/docs/getting_started/integrating_into_your_project.md b/docs/getting_started/integrating_into_your_project.md
new file mode 100644
index 000000000..ed0c25da2
--- /dev/null
+++ b/docs/getting_started/integrating_into_your_project.md
@@ -0,0 +1,90 @@
+# Integrating Into Your Project
+
+This guide shows you how to integrate stdgpu into your project such that you can use its functionality. In particular, since CMake is used as the primary build system for stdgpu, the following instructions will focus on projects that use CMake as well for building.
+
+
+In order to use stdgpu in your project, you need to either find a pre-installed version of it, or alternatively embed it as part of your project and build it alongside with your project from source.
+
+
+:::::{tab-set}
+
+::::{tab-item} Pre-Installed
+
+```cmake
+find_package(stdgpu REQUIRED)
+
+add_library(your_project ...)
+# ...
+
+# Link your project against stdgpu
+target_link_libraries(your_project PUBLIC stdgpu::stdgpu)
+```
+
+::::
+
+::::{tab-item} From Source (git submodule)
+
+```cmake
+# Exclude unneeded parts from the build
+set(STDGPU_BUILD_EXAMPLES OFF CACHE INTERNAL "")
+set(STDGPU_BUILD_BENCHMARKS OFF CACHE INTERNAL "")
+set(STDGPU_BUILD_TESTS OFF CACHE INTERNAL "")
+
+add_subdirectory(stdgpu)
+
+add_library(your_project ...)
+# ...
+
+# Link your project against stdgpu
+target_link_libraries(your_project PUBLIC stdgpu::stdgpu)
+```
+
+:::{note}
+Make sure that all dependencies listed in the [](building_from_source.md#prerequisites) are installed to build stdgpu within your project.
+:::
+
+:::{seealso}
+A complete list of options to control the build of stdgpu within your project can be found in [](building_from_source.md#configuration-options).
+:::
+
+::::
+
+::::{tab-item} From Source (Modern CMake)
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+    stdgpu
+    GIT_REPOSITORY https://github.com/stotko/stdgpu.git
+    GIT_TAG        master
+)
+
+# Exclude unneeded parts from the build
+set(STDGPU_BUILD_EXAMPLES OFF CACHE INTERNAL "")
+set(STDGPU_BUILD_BENCHMARKS OFF CACHE INTERNAL "")
+set(STDGPU_BUILD_TESTS OFF CACHE INTERNAL "")
+
+FetchContent_MakeAvailable(stdgpu)
+
+add_library(your_project ...)
+# ...
+
+# Link your project against stdgpu
+target_link_libraries(your_project PUBLIC stdgpu::stdgpu)
+```
+
+:::{note}
+Make sure that all dependencies listed in the [](building_from_source.md#prerequisites) are installed to build stdgpu within your project.
+:::
+
+:::{seealso}
+A complete list of options to control the build of stdgpu within your project can be found in [](building_from_source.md#configuration-options).
+:::
+
+::::
+
+:::::
+
+
+In all of the above cases, the `stdgpu::stdgpu` target will become available in your project. The only further step required is to link your project target(s) against this target which will then propagate all necessary properties from stdgpu such as compile flags, include directories, library files, etc. to them.
diff --git a/docs/index.md b/docs/index.md
index cfef15f98..06d7314e0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,6 +20,14 @@
 self
 ```
 
+```{toctree}
+:hidden:
+:caption: Getting Started
+
+getting_started/building_from_source
+getting_started/integrating_into_your_project
+```
+
 ```{toctree}
 :hidden:
 :caption: API Reference