From 3547899147dc2d1e234cbad090a196adcfb26b5b Mon Sep 17 00:00:00 2001 From: Patrick Stotko Date: Thu, 21 May 2020 20:17:48 +0200 Subject: [PATCH] README,doc: Remove unnecessary information and improve wording --- README.md | 68 +++++++++++----------------- azure-pipelines.yml | 4 +- cmake/config_summary.cmake | 16 +++---- doc/stdgpu/index.doxy | 49 ++++++-------------- scripts/{ => ci}/run_coverage.sh | 0 scripts/create_documentation.sh | 6 --- scripts/utils/build_documentation.sh | 6 +++ 7 files changed, 57 insertions(+), 92 deletions(-) rename scripts/{ => ci}/run_coverage.sh (100%) delete mode 100644 scripts/create_documentation.sh create mode 100644 scripts/utils/build_documentation.sh diff --git a/README.md b/README.md index 07cc94993..f76dae044 100644 --- a/README.md +++ b/README.md @@ -37,16 +37,18 @@

+

-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 +

stdgpu: Efficient STL-like Data Structures on the GPU

``` @UNPUBLISHED{stotko2019stdgpu, @@ -316,7 +300,7 @@ If you use stdgpu in one of your projects, please cite the following publication } ``` -SLAMCast: Large-Scale, Real-Time 3D Reconstruction and Streaming for Immersive Multi-Client Live Telepresence +

SLAMCast: Large-Scale, Real-Time 3D Reconstruction and Streaming for Immersive Multi-Client Live Telepresence

``` @article{stotko2019slamcast, diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 7e112748d..92208619e 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -164,7 +164,7 @@ jobs: targetType: 'inline' script: | set -e - sh scripts/run_coverage.sh + sh scripts/ci/run_coverage.sh - task: Bash@3 displayName: Upload coverage report @@ -310,4 +310,4 @@ jobs: targetType: 'inline' script: | set -e - sh scripts/create_documentation.sh + sh scripts/utils/build_documentation.sh diff --git a/cmake/config_summary.cmake b/cmake/config_summary.cmake index 351fba527..575c80fbc 100644 --- a/cmake/config_summary.cmake +++ b/cmake/config_summary.cmake @@ -12,17 +12,17 @@ function(stdgpu_print_configuration_summary) message(STATUS "Build:") message(STATUS " STDGPU_BACKEND : ${STDGPU_BACKEND}") - message(STATUS " STDGPU_SETUP_COMPILER_FLAGS : ${STDGPU_SETUP_COMPILER_FLAGS} (depends on usage method)") + message(STATUS " STDGPU_BUILD_SHARED_LIBS : ${STDGPU_BUILD_SHARED_LIBS}") + message(STATUS " STDGPU_SETUP_COMPILER_FLAGS : ${STDGPU_SETUP_COMPILER_FLAGS}") message(STATUS " STDGPU_TREAT_WARNINGS_AS_ERRORS : ${STDGPU_TREAT_WARNINGS_AS_ERRORS}") message(STATUS " STDGPU_ANALYZE_WITH_CLANG_TIDY : ${STDGPU_ANALYZE_WITH_CLANG_TIDY}") message(STATUS " STDGPU_ANALYZE_WITH_CPPCHECK : ${STDGPU_ANALYZE_WITH_CPPCHECK}") - message(STATUS " STDGPU_BUILD_SHARED_LIBS : ${STDGPU_BUILD_SHARED_LIBS} (depends on BUILD_SHARED_LIBS)") message(STATUS "") message(STATUS "Configuration:") message(STATUS " STDGPU_ENABLE_AUXILIARY_ARRAY_WARNING : [deprecated] ${STDGPU_ENABLE_AUXILIARY_ARRAY_WARNING}") - message(STATUS " STDGPU_ENABLE_CONTRACT_CHECKS : ${STDGPU_ENABLE_CONTRACT_CHECKS} (depends on build type)") + message(STATUS " STDGPU_ENABLE_CONTRACT_CHECKS : ${STDGPU_ENABLE_CONTRACT_CHECKS}") message(STATUS " STDGPU_ENABLE_MANAGED_ARRAY_WARNING : [deprecated] ${STDGPU_ENABLE_MANAGED_ARRAY_WARNING}") message(STATUS " STDGPU_USE_32_BIT_INDEX : ${STDGPU_USE_32_BIT_INDEX}") message(STATUS " STDGPU_USE_FAST_DESTROY : [deprecated] ${STDGPU_USE_FAST_DESTROY}") @@ -30,14 +30,14 @@ function(stdgpu_print_configuration_summary) message(STATUS "") - message(STATUS "Tests:") - message(STATUS " STDGPU_BUILD_TESTS : ${STDGPU_BUILD_TESTS}") - message(STATUS " STDGPU_BUILD_TEST_COVERAGE : ${STDGPU_BUILD_TEST_COVERAGE}") + message(STATUS "Examples:") + message(STATUS " STDGPU_BUILD_EXAMPLES : ${STDGPU_BUILD_EXAMPLES}") message(STATUS "") - message(STATUS "Examples:") - message(STATUS " STDGPU_BUILD_EXAMPLES : ${STDGPU_BUILD_EXAMPLES}") + message(STATUS "Tests:") + message(STATUS " STDGPU_BUILD_TESTS : ${STDGPU_BUILD_TESTS}") + message(STATUS " STDGPU_BUILD_TEST_COVERAGE : ${STDGPU_BUILD_TEST_COVERAGE}") message(STATUS "") diff --git a/doc/stdgpu/index.doxy b/doc/stdgpu/index.doxy index bd3a4689b..d79466508 100644 --- a/doc/stdgpu/index.doxy +++ b/doc/stdgpu/index.doxy @@ -114,18 +114,13 @@ More examples can be found in the https://stotko.github.io/stdgpu. -\section getting-started Getting Started +\section building Building -To compile the library, please make sure to fulfill the build requirements and execute the respective build scripts. - - -\subsection prerequisites 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 @@ -161,37 +156,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. -\subsection building 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`). -\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 +

stdgpu: Efficient STL-like Data Structures on the GPU

\code{.bib} @UNPUBLISHED{stotko2019stdgpu, @@ -270,7 +251,7 @@ If you use stdgpu in one of your projects, please cite the following publication } \endcode -SLAMCast: Large-Scale, Real-Time 3D Reconstruction and Streaming for Immersive Multi-Client Live Telepresence +

SLAMCast: Large-Scale, Real-Time 3D Reconstruction and Streaming for Immersive Multi-Client Live Telepresence

\code{.bib} @article{stotko2019slamcast, diff --git a/scripts/run_coverage.sh b/scripts/ci/run_coverage.sh similarity index 100% rename from scripts/run_coverage.sh rename to scripts/ci/run_coverage.sh diff --git a/scripts/create_documentation.sh b/scripts/create_documentation.sh deleted file mode 100644 index b0837d043..000000000 --- a/scripts/create_documentation.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/sh -set -e - -# Create and install documentation -cmake -E cmake_echo_color --blue ">>>>> Create documentation" -cmake --build build --target stdgpu_doc diff --git a/scripts/utils/build_documentation.sh b/scripts/utils/build_documentation.sh new file mode 100644 index 000000000..20a04a47e --- /dev/null +++ b/scripts/utils/build_documentation.sh @@ -0,0 +1,6 @@ +#!/bin/sh +set -e + +# Build documentation +cmake -E cmake_echo_color --blue ">>>>> Build documentation" +cmake --build build --target stdgpu_doc