From 3547899147dc2d1e234cbad090a196adcfb26b5b Mon Sep 17 00:00:00 2001
From: Patrick Stotko
-Features | -Examples | -Documentation | -Getting Started | -Usage | -Contributing | -License | -Contact +Features | +Examples | +Documentation | +Building | +Integration | +Contributing | +License | +Contact
+ ## Features @@ -160,18 +162,13 @@ More examples can be found in the https://stotko.github.io/stdgpu. -## Getting Started +## Building -To compile the library, please make sure to fulfill the build requirements and execute the respective build scripts. - - -### Prerequisites - -The following general and backend-specific dependencies (or newer versions) are required to compile the library. +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++14 compiler (one of the following) +- C++14 compiler - GCC 7 - (Ubuntu 18.04) `sudo apt install g++ make` - Clang 6 @@ -207,37 +204,25 @@ The following general and backend-specific dependencies (or newer versions) are - (Ubuntu) https://github.com/RadeonOpenCompute/ROCm - Includes thrust -Optional - -- Doxygen 1.8.13 - - (Ubuntu 18.04) `sudo apt install doxygen` - - (Windows) http://www.doxygen.nl/download.html -- lcov 1.13 - - (Ubuntu 18.04) `sudo apt install lcov` +The library can be built as every other project which makes use of the CMake build system. -### Building - -For convenience, we provide several cross-platform scripts to build the project. Note that some scripts depend on the build type, so there are scripts for both `debug` and `release` builds. +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 --- | ---sh scripts/setup_<build_type>.sh
| Performs a full clean build of the project. Removes old build, configures the project (build path: `./build`), builds the project, and runs the unit tests.
-sh scripts/build_<build_type>.sh
| (Re-)Builds the project. Requires that project is configured (or set up).
-sh scripts/run_tests_<build_type>.sh
| Runs the unit tests. Requires that project is built.
-sh scripts/create_documentation.sh
| Builds the documentation locally. Requires doxygen and that project is configured (or set up).
-sh scripts/run_coverage.sh
| Builds a test coverage report locally. Requires lcov and that project is configured (or set up).
+sh scripts/build_<build_type>.sh
| (Re-)Builds the project. Requires that the project is set up.
+sh scripts/run_tests_<build_type>.sh
| Runs the unit tests. Requires that the project is built.
sh scripts/install_<build_type>.sh
| Installs the project at the configured install path (default: `./bin`).
-## Usage
+## 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 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)
@@ -264,21 +249,20 @@ 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:
+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_TREAT_WARNINGS_AS_ERRORS` | Treats compiler warnings as errors | `OFF`
-`STDGPU_ANALYZE_WITH_CLANG_TIDY` | Analyzes the code with clang-tidy | `OFF`
-`STDGPU_ANALYZE_WITH_CPPCHECK` | Analyzes the code with cppcheck | `OFF`
-`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_BUILD_EXAMPLES` | Build the examples | `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:
@@ -303,7 +287,7 @@ Distributed under the Apache 2.0 License. See stdgpu: Efficient STL-like Data Structures on the GPU
+sh scripts/setup_<build_type>.sh
| Performs a full clean build of the project. Removes old build, configures the project (build path: `./build`), builds the project, and runs the unit tests.
-sh scripts/build_<build_type>.sh
| (Re-)Builds the project. Requires that project is configured (or set up).
-sh scripts/run_tests_<build_type>.sh
| Runs the unit tests. Requires that project is built.
-sh scripts/create_documentation.sh
| Builds the documentation locally. Requires doxygen and that project is configured (or set up).
-sh scripts/run_coverage.sh
| Builds a test coverage report locally. Requires lcov and that project is configured (or set up).
+sh scripts/build_<build_type>.sh
| (Re-)Builds the project. Requires that the project is set up.
+sh scripts/run_tests_<build_type>.sh
| Runs the unit tests. Requires that the project is built.
sh scripts/install_<build_type>.sh
| Installs the project at the configured install path (default: `./bin`).
-\section usage Usage
+\section integration Integration
In the following, we show some examples on how the library can be integrated into and used in a project.
-\subsection cmake-integration CMake Integration
-
-To use the library in your project, you can either install it externally first and then include it using `find_package`:
+CMake Integration. To use the library in your project, you can either install it externally first and then include it using `find_package`:
\code{.cmake}
find_package(stdgpu 1.0.0 REQUIRED)
@@ -218,21 +201,19 @@ target_link_libraries(foo PUBLIC stdgpu::stdgpu)
\endcode
-\subsection cmake-options CMake Options
-
-To configure the library, two sets of options are provided. The following build options control the build process:
+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_TREAT_WARNINGS_AS_ERRORS` | Treats compiler warnings as errors | `OFF`
-`STDGPU_ANALYZE_WITH_CLANG_TIDY` | Analyzes the code with clang-tidy | `OFF`
-`STDGPU_ANALYZE_WITH_CPPCHECK` | Analyzes the code with cppcheck | `OFF`
-`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_BUILD_EXAMPLES` | Build the examples | `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:
@@ -257,7 +238,7 @@ Distributed under the Apache 2.0 License. See stdgpu: Efficient STL-like Data Structures on the GPU
+