### Catch2 Vector Test Case with Sections

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/tutorial.md

Demonstrates using Catch2's SECTION macro to share setup and teardown code for testing std::vector operations. Each section is executed from the start of the TEST_CASE, providing a fresh state. This example showcases resizing and reserving operations.

```c++
TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
    // This setup will be done 4 times in total, once for each section
    std::vector<int> v( 5 );

    REQUIRE( v.size() == 5 );
    REQUIRE( v.capacity() >= 5 );

    SECTION( "resizing bigger changes size and capacity" ) {
        v.resize( 10 );

        REQUIRE( v.size() == 10 );
        REQUIRE( v.capacity() >= 10 );
    }
    SECTION( "resizing smaller changes size but not capacity" ) {
        v.resize( 0 );

        REQUIRE( v.size() == 0 );
        REQUIRE( v.capacity() >= 5 );
    }
    SECTION( "reserving bigger changes capacity but not size" ) {
        v.reserve( 10 );

        REQUIRE( v.size() == 5 );
        REQUIRE( v.capacity() >= 10 );
    }
    SECTION( "reserving smaller does not change size or capacity" ) {
        v.reserve( 0 );

        REQUIRE( v.size() == 5 );
        REQUIRE( v.capacity() >= 5 );
    }
}
```

--------------------------------

### CMakeLists.txt for Alpaka Integration via find_package

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/example.rst

This CMake configuration file integrates Alpaka into your project using the 'find_package' method. It requires Alpaka to be installed and discoverable by CMake. The example links the executable to the Alpaka library.

```cmake
cmake_minimum_required(VERSION 3.25)
project("myexample" CXX)

find_package(alpaka REQUIRED)
alpaka_add_executable(${PROJECT_NAME} helloWorld.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC alpaka::alpaka)
```

--------------------------------

### Fixture Example: Persistent Fixtures in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Demonstrates persistent fixtures in Alpaka, where setup and teardown logic is executed only once for a group of tests, improving efficiency for expensive resource initialization.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("Persistent fixture example") {
    // Setup is done once before all tests using this fixture
    // Teardown is done once after all tests using this fixture
    REQUIRE(true);
}
```

--------------------------------

### Install and Use Pre-commit Hooks in Bash

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/style.rst

Commands to install and utilize pre-commit hooks for automated code style checks and formatting within the Alpaka project. This includes initial setup and running hooks on all files. Requires pre-commit to be installed separately.

```bash
cd /path/to/alpaka-working-clone
pre-commit install

git commit --no-verify [...]

pre-commit run --all-files
```

--------------------------------

### Install Alpaka from Source

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/install.rst

Clones the Alpaka repository, creates a build directory, configures the installation path using CMake, and then installs the header-only library.

```bash
# Clone alpaka from github.com
git clone --branch 1.2.0 https://github.com/alpaka-group/alpaka.git
cd alpaka
mkdir build && cd buildcmake -DCMAKE_INSTALL_PREFIX=/install/ ..
cmake --install .
```

--------------------------------

### Fixture Example: Class-based Fixtures in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Illustrates the implementation of class-based fixtures in Alpaka. This allows setup and teardown logic to be shared across multiple test cases within a class.

```cpp
#include <alpaka/test.hpp>

class MyFixture {
public:
    MyFixture() { /* Setup */ }
    ~MyFixture() { /* Teardown */ }
    // Test members
};

TEST_CASE_FIXTURE(MyFixture, "Test case using class fixture") {
    REQUIRE(true);
}
```

--------------------------------

### CMakeLists.txt for Alpaka Integration via add_subdirectory

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/example.rst

This CMake configuration file integrates Alpaka by including its source directory directly into your project using 'add_subdirectory'. This method does not require a separate installation of Alpaka. The example assumes Alpaka is located in 'project_path/thirdParty/alpaka'.

```cmake
cmake_minimum_required(VERSION 3.25)
project("myexample" CXX)

add_subdirectory(thirdParty/alpaka)
alpaka_add_executable(${PROJECT_NAME} helloWorld.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC alpaka::alpaka)
```

--------------------------------

### Build and Run Alpaka Examples

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/install.rst

Configures the build with examples enabled, builds a specific example ('vectorAdd'), and then executes it. This requires CMake and Alpaka headers from the source directory.

```bash
# ..
cmake -Dalpaka_BUILD_EXAMPLES=ON ..
cmake --build . -t vectorAdd
./example/vectorAdd/vectorAdd # execution
```

--------------------------------

### Configuration Example: Compile-time Configuration in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example demonstrating compile-time configuration options for Alpaka. This allows customizing framework behavior during the build process.

```cpp
// Example: Defining preprocessor macros to configure Alpaka
// #define ALPACA_CONFIG_SOME_FEATURE

#include <alpaka/test.hpp>

TEST_CASE("Compile-time configuration") {
    REQUIRE(true);
}
```

--------------------------------

### Report Example: Automake Reporter in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example demonstrating the Automake reporter for Alpaka, which generates output compatible with the Automake build system.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("Automake reporter output") {
    // Test execution with Automake reporter enabled.
    REQUIRE(true);
}
```

--------------------------------

### Configuration Example: Run-time Configuration in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example showcasing run-time configuration options for Alpaka. This allows modifying framework behavior based on command-line arguments or configuration files.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("Run-time configuration") {
    // Example: Reading configuration from command line arguments
    // alpaka::cfg::load("--my-option", "value");
    REQUIRE(true);
}
```

--------------------------------

### Configuration Example: Provide Own main() in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for providing a custom `main()` function when using Alpaka. This allows for more control over the test runner's initialization and execution.

```cpp
#include <alpaka/test.hpp>

// int main(int argc, char* argv[]) {
//     // Custom main function logic
//     return alpaka::run(argc, argv);
// }

TEST_CASE("Custom main function") {
    REQUIRE(true);
}
```

--------------------------------

### CMake Project Setup and Dependency Finding

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/useBLASInAlpaka/useCuBLASInAlpaka/CMakeLists.txt

This snippet configures the CMake project, sets the minimum required version, and finds the necessary CUDA and Alpaka libraries. It includes conditional logic to use Alpaka from the source tree or a pre-installed version. The cuBLAS library is explicitly added.

```cmake
cmake_minimum_required(VERSION 3.25)

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

set(_TARGET_NAME useCuBLASInAlpaka)

project(${_TARGET_NAME} LANGUAGES CXX)

if(NOT alpaka_ACC_GPU_CUDA_ONLY_MODE)
    message(WARNING "Skipping build of 'useCuBLASInAlpaka' because alpaka_ACC_GPU_CUDA_ONLY_MODE is not enabled.")
    return()
endif()

find_package(CUDA REQUIRED)
set(CUDA_LIBRARIES ${CUDA_LIBRARIES} cublas)

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Hello World Example in C++ with Alpaka

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/example.rst

A basic 'Hello World' program demonstrating the use of the Alpaka library for parallel computation. This example showcases a simple task that can be executed on various processors supported by Alpaka.

```C++
#include <alpaka/alpaka.hpp>

int main() {
    // Your Alpaka code here
    return 0;
}
```

--------------------------------

### Install Documentation Dependencies (Bash)

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/sphinx.rst

Installs the necessary Python packages for building the documentation using pip and a requirements file. Assumes doxygen is installed separately.

```bash
cd docs/
pip install -r requirements.txt
```

--------------------------------

### CMake Project Setup and Alpaka Integration

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/complex/CMakeLists.txt

This snippet sets the minimum CMake version, configures the project name and language, and handles finding the Alpaka library. It supports using Alpaka from its source tree or an installed version. Dependencies include CMake version 3.25 and the Alpaka library.

```cmake
cmake_minimum_required(VERSION 3.25)

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

set(_TARGET_NAME complexNumbers)

project(${_TARGET_NAME} LANGUAGES CXX)

if(NOT TARGET alpaka::alpaka)
    option(USE_ALPAKA_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(USE_ALPAKA_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Configure CMake Project and Find Alpaka

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/matrixMulWithMdspan/CMakeLists.txt

This snippet sets the minimum CMake version, defines the project name, and attempts to find the alpaka library. It supports using alpaka from its source tree or an installed version, and checks for the mdspan feature.

```cmake
cmake_minimum_required(VERSION 3.25)

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

set(_TARGET_NAME matrixMulMdSpan)

project(${_TARGET_NAME} LANGUAGES CXX)

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()


if (alpaka_USE_MDSPAN STREQUAL "OFF")
    message(STATUS "The matrixMulMdSpan example requires mdspan. Please set alpaka_USE_MDSPAN accordingly. Example disabled.")
    return()
endif ()
```

--------------------------------

### Enable Building Examples

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/advanced/cmake.rst

CMake variable to control whether Alpaka's example programs are built. Setting this to ON includes the examples in the compilation process.

```cmake
set(alpaka_BUILD_EXAMPLES ON)
```

--------------------------------

### Find and Configure Alpaka Dependency

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/counterBasedRng/CMakeLists.txt

Locates the Alpaka library, allowing the project to link against it. It supports using Alpaka from its source tree or an installed version, with options to control example building and mdspan usage.

```cmake
if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()

if (alpaka_USE_MDSPAN STREQUAL "OFF")
    message(STATUS "The counterBasedRng example requires mdspan. Please set alpaka_USE_MDSPAN accordingly. Example disabled.")
    return()
endif ()
```

--------------------------------

### Define Project and Find Alpaka Dependency

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/bufferCopy/CMakeLists.txt

Defines the project name as 'bufferCopy' and specifies CXX as the language. It then handles finding the alpaka library, either from a source tree or an installed version, making it a required dependency.

```cmake
set(_TARGET_NAME bufferCopy)

project(${_TARGET_NAME} LANGUAGES CXX)

#-------------------------------------------------------------------------------
# Find alpaka.

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Link Examples to Catch2 Library (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/examples/CMakeLists.txt

This CMake snippet links a collection of example executables to the `Catch2WithMain` target. This ensures that the Catch2 testing framework, including its main function, is properly integrated into each example. It uses `set` and `foreach` to manage the targets and `target_link_libraries` for linking.

```cmake
set(ALL_EXAMPLE_TARGETS
  ${TARGETS_IDIOMATIC_EXAMPLES}
  010-TestCase
  020-MultiFile
)

foreach( name ${ALL_EXAMPLE_TARGETS} )
    target_link_libraries( ${name} Catch2WithMain )
endforeach()
```

--------------------------------

### Add Subdirectories for Alpaka Examples

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/CMakeLists.txt

Includes various subdirectories into the CMake build process. Each subdirectory represents a distinct example or module within the Alpaka library, allowing for modular development and testing.

```cmake
add_subdirectory("bufferCopy/")
add_subdirectory("complex/")
add_subdirectory("convolution1D/")
add_subdirectory("convolution2D/")
add_subdirectory("conv2DWithMdspan/")
add_subdirectory("counterBasedRng/")
add_subdirectory("heatEquation/")
add_subdirectory("heatEquation2D/")
add_subdirectory("helloWorld/")
add_subdirectory("helloWorldLambda/")
add_subdirectory("kernelSpecialization/")
add_subdirectory("ls/")
add_subdirectory("matrixMulWithMdspan/")
add_subdirectory("monteCarloIntegration/")
add_subdirectory("openMPSchedule/")
add_subdirectory("parallelLoopPatterns/")
add_subdirectory("randomStrategies/")
add_subdirectory("randomCells2D/")
add_subdirectory("reduce/")
add_subdirectory("tagSpecialization/")
add_subdirectory("useBLASInAlpaka/useCuBLASInAlpaka/")
add_subdirectory("useBLASInAlpaka/useRocBLASInAlpaka/")
add_subdirectory("vectorAdd/")
```

--------------------------------

### Project Definition and Alpaka Integration (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/convolution2D/CMakeLists.txt

Defines the project name and language, then handles finding and including the Alpaka library. It supports using Alpaka from its source tree or an installed version.

```cmake
set(_TARGET_NAME convolution2D)

project(${_TARGET_NAME} LANGUAGES CXX)

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Report Example: Multiple Reporters in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example showing how to use multiple reporters simultaneously with Alpaka, allowing test results to be output in different formats.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("Using multiple reporters") {
    // Configuration to enable multiple reporters would be needed.
    REQUIRE(true);
}
```

--------------------------------

### Find and Link Alpaka Library

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/heatEquation2D/CMakeLists.txt

Checks if the 'alpaka::alpaka' target exists. If not, it provides an option to use alpaka's source tree. It then either adds alpaka's source directory or finds an installed alpaka package. The executable will be linked against alpaka.

```cmake
#-------------------------------------------------------------------------------
# Find alpaka.

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Configuration Example: Custom Output Streams in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Illustrates how to provide custom output streams for test reporting in Alpaka. This allows redirecting test output to files, network sockets, or other custom destinations.

```cpp
#include <alpaka/test.hpp>
#include <iostream>
#include <fstream>

// Custom output stream class (example)
class MyOutputStream : public std::ostream {
public:
    MyOutputStream() : std::ostream(new std::streambuf()) {}
    ~MyOutputStream() { delete rdbuf(); }
};

// Configuration to use custom output stream (details may vary)
// alpaka::cfg::setOutputStreams({new MyOutputStream()});

TEST_CASE("Test with custom output stream") {
    std::cout << "This message might go to a custom stream." << std::endl;
    REQUIRE(true);
}
```

--------------------------------

### CMake Project Configuration and Alpaka Integration

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/ls/CMakeLists.txt

This snippet configures a CMake project named 'alpaka-ls' using C++. It sets the minimum required CMake version and manages the inclusion of the Alpaka library, either by adding its source directory or by finding an installed package. It also defines an executable and adds it as a test.

```cmake
cmake_minimum_required(VERSION 3.25)
set_property(GLOBAL PROPERTY USE_FOLDERS ON)

project(alpaka-ls LANGUAGES CXX)
if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)
    if(alpaka_USE_SOURCE_TREE)
        set(alpaka_BUILD_EXAMPLES OFF) # Don't build the examples recursively
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()

alpaka_add_executable(${PROJECT_NAME} src/ls.cpp)
target_link_libraries(${PROJECT_NAME} PUBLIC alpaka::alpaka)
set_target_properties(${PROJECT_NAME} PROPERTIES FOLDER example)
add_test(NAME ${PROJECT_NAME} COMMAND ${PROJECT_NAME})
```

--------------------------------

### Install Boost Dependency on Windows

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/install.rst

Installs the Boost libraries on Windows using the vcpkg package manager. This is a prerequisite for using Alpaka on Windows.

```bash
# Using vcpkg, https://github.com/microsoft/vcpkg
vcpkg install boost
```

--------------------------------

### CMake: Project Initialization and Options

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/CMakeLists.txt

Initializes the CMake project, sets the project name, version, languages, and homepage URL. It also defines various build options using `option()` and `cmake_dependent_option()` for features like documentation, testing, examples, and coverage. These options control which components of the project are built and installed.

```cmake
cmake_minimum_required(VERSION 3.16)

# detect if Catch is being bundled, 
# disable testsuite in that case
if(NOT DEFINED PROJECT_NAME)
  set(NOT_SUBPROJECT ON)
else()
  set(NOT_SUBPROJECT OFF)
endif()

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

option(CATCH_INSTALL_DOCS "Install documentation alongside library" ON)
option(CATCH_INSTALL_EXTRAS "Install extras (CMake scripts, debugger helpers) alongside library" ON)
option(CATCH_DEVELOPMENT_BUILD "Build tests, enable warnings, enable Werror, etc" OFF)
option(CATCH_ENABLE_REPRODUCIBLE_BUILD "Add compiler flags for improving build reproducibility" ON)

include(CMakeDependentOption)
cmake_dependent_option(CATCH_BUILD_TESTING "Build the SelfTest project" ON "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_BUILD_EXAMPLES "Build code examples" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_BUILD_EXTRA_TESTS "Build extra tests" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_BUILD_FUZZERS "Build fuzzers" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_ENABLE_COVERAGE "Generate coverage for codecov.io" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_ENABLE_WERROR "Enables Werror during build" ON "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_BUILD_SURROGATES "Enable generating and building surrogate TUs for the main headers" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_ENABLE_CONFIGURE_TESTS "Enable CMake configuration tests. WARNING: VERY EXPENSIVE" OFF "CATCH_DEVELOPMENT_BUILD" OFF)
cmake_dependent_option(CATCH_ENABLE_CMAKE_HELPER_TESTS "Enable CMake helper tests. WARNING: VERY EXPENSIVE" OFF "CATCH_DEVELOPMENT_BUILD" OFF)


# Catch2's build breaks if done in-tree. You probably should not build
# things in tree anyway, but we can allow projects that include Catch2
# as a subproject to build in-tree as long as it is not in our tree.
if (CMAKE_BINARY_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR) 
    message(FATAL_ERROR "Building in-source is not supported! Create a build dir and remove ${CMAKE_SOURCE_DIR}/CMakeCache.txt")
endif()

project(Catch2
  VERSION 3.8.1 # CML version placeholder, don't delete
  LANGUAGES CXX
  HOMEPAGE_URL "https://github.com/catchorg/Catch2"
  DESCRIPTION "A modern, C++-native, unit test framework."
)
```

--------------------------------

### Install Catch2 Documentation

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/CMakeLists.txt

Installs the documentation for Catch2. It targets the 'docs/' directory and installs it to the CMAKE_INSTALL_DOCDIR, excluding any 'doxygen' subdirectories. This requires the CATCH_INSTALL_DOCS variable to be set.

```cmake
if(CATCH_INSTALL_DOCS)
      install(
        DIRECTORY
          docs/
        DESTINATION
          "${CMAKE_INSTALL_DOCDIR}"
        PATTERN "doxygen" EXCLUDE
      )
    endif()
```

--------------------------------

### Configure Project and Find Alpaka (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/heatEquation/CMakeLists.txt

Sets the minimum required CMake version to 3.25, enables folder organization in the CMake GUI, and defines the project name as 'heatEquation' using C++. It then attempts to find the Alpaka library, offering an option to use the source tree if Alpaka is not installed.

```cmake
cmake_minimum_required(VERSION 3.25)

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

set(_TARGET_NAME heatEquation)

project(${_TARGET_NAME} LANGUAGES CXX)


#-------------------------------------------------------------------------------#
# Find alpaka.

if(NOT TARGET alpaka::alpaka)
    option(alpaka_USE_SOURCE_TREE "Use alpaka's source tree instead of an alpaka installation" OFF)

    if(alpaka_USE_SOURCE_TREE)
        # Don't build the examples recursively
        set(alpaka_BUILD_EXAMPLES OFF)
        add_subdirectory("${CMAKE_CURRENT_LIST_DIR}/../.." "${CMAKE_BINARY_DIR}/alpaka")
    else()
        find_package(alpaka REQUIRED)
    endif()
endif()
```

--------------------------------

### Single-file Test Case Example in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Demonstrates how to create a single-file test case using the Alpaka testing framework. This example is self-contained and requires no external dependencies beyond the framework itself.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("A simple test case") {
    REQUIRE(true);
}
```

--------------------------------

### Report Example: User-defined Reporter in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for creating and integrating custom reporters in Alpaka. This allows full control over how test results are presented.

```cpp
#include <alpaka/test.hpp>
#include <alpaka/reporter.hpp> // Assuming reporter header

class MyCustomReporter : public alpaka::reporter::IReporter {
public:
    void testCaseStart(const alpaka::reporter::TestCaseInfo&) override {}
    // Other reporting methods
};

TEST_CASE("Using a custom reporter") {
    // Configuration to set the custom reporter would be needed here.
    REQUIRE(true);
}
```

--------------------------------

### Add Executable and Link Libraries

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/matrixMulWithMdspan/CMakeLists.txt

This CMake snippet defines the executable for the matrixMulMdSpan example, specifies its source file, links the alpaka library to it, and sets target properties for organization and testing.

```cmake
alpaka_add_executable(
    ${_TARGET_NAME}
    src/matrixMulMdSpan.cpp)
target_link_libraries(
    ${_TARGET_NAME}
    PUBLIC alpaka::alpaka)

set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```

--------------------------------

### Install Pre-commit Hooks for Alpaka

Source: https://github.com/alpaka-group/alpaka/blob/develop/CONTRIBUTING.md

Installs the pre-commit framework for the Alpaka project. This ensures that code adheres to style guidelines automatically before commits. Requires Git and the pre-commit executable.

```bash
cd /path/to/alpaka-working-clone
pre-commit install
```

--------------------------------

### Build Multiple Idiomatic Examples (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/examples/CMakeLists.txt

This CMake code iterates through a list of C++ source files, creating a separate executable for each. This is useful for organizing and building numerous distinct Catch2 examples. It uses `set`, `string(REPLACE)`, and `foreach` loops.

```cmake
# These examples use the standard separate compilation
set( SOURCES_IDIOMATIC_EXAMPLES
    030-Asn-Require-Check.cpp
    100-Fix-Section.cpp
    110-Fix-ClassFixture.cpp
    111-Fix-PersistentFixture.cpp
    120-Bdd-ScenarioGivenWhenThen.cpp
    210-Evt-EventListeners.cpp
    232-Cfg-CustomMain.cpp
    300-Gen-OwnGenerator.cpp
    301-Gen-MapTypeConversion.cpp
    302-Gen-Table.cpp
    310-Gen-VariablesInGenerators.cpp
    311-Gen-CustomCapture.cpp
)

string( REPLACE ".cpp" "" BASENAMES_IDIOMATIC_EXAMPLES "${SOURCES_IDIOMATIC_EXAMPLES}" )
set( TARGETS_IDIOMATIC_EXAMPLES ${BASENAMES_IDIOMATIC_EXAMPLES} )


foreach( name ${TARGETS_IDIOMATIC_EXAMPLES} )
    add_executable( ${name} ${name}.cpp )
endforeach()
```

--------------------------------

### Logging Example: INFO Message in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for using the `INFO` macro in Alpaka to provide additional information during test failures. This can be useful for adding context to assertion failures.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("INFO message on failure") {
    int result = 0;
    // REQUIRE(result == 1); // This would fail
    // INFO("Expected result to be 1, but got " << result);
    REQUIRE(result == 0);
}
```

--------------------------------

### Report Example: TAP Reporter in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for the Test Anything Protocol (TAP) reporter in Alpaka. TAP is a simple text-based format for reporting test results.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("TAP reporter output") {
    // Test execution with TAP reporter enabled.
    REQUIRE(true);
}
```

--------------------------------

### Set Target Properties and Add Test

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/bufferCopy/CMakeLists.txt

Sets the 'FOLDER' property for the 'bufferCopy' target to 'example', organizing it in IDEs. It also adds a test named 'bufferCopy' that executes the built target.

```cmake
set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```

--------------------------------

### Build and Install ROCRAND for HIP Backend

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/backends.rst

Steps to clone, build, and install the ROCRAND library for the HIP backend. This process involves using CMake with specific variables to configure the installation path and disable benchmarks and tests. Dependencies include Git, CMake, and a HIP development environment.

```shell
git clone https://github.com/ROCmSoftwarePlatform/rocRAND
cd rocRAND
mkdir -p build
cd buildcmake -DCMAKE_INSTALL_PREFIX=${HIP_PATH} -DBUILD_BENCHMARK=OFF -DBUILD_TEST=OFF -DCMAKE_MODULE_PATH=${HIP_PATH}/cmake ..
make
```

--------------------------------

### Install Alpaka Target and Configuration Files (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/CMakeLists.txt

Installs the Alpaka library target, package configuration files (alpakaConfig.cmake and alpakaConfigVersion.cmake), and CMake helper scripts. This prepares the project for use by other CMake projects.

```cmake
include(CMakePackageConfigHelpers)
include(GNUInstallDirs)

set(_alpaka_INSTALL_CMAKEDIR "${CMAKE_INSTALL_LIBDIR}/cmake/alpaka")

install(TARGETS alpaka
        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

write_basic_package_version_file(
    "alpakaConfigVersion.cmake"
    VERSION ${PROJECT_VERSION}
    COMPATIBILITY SameMajorVersion)

configure_package_config_file(
    "${_alpaka_ROOT_DIR}/cmake/alpakaConfig.cmake.in"
    "${PROJECT_BINARY_DIR}/alpakaConfig.cmake"
    INSTALL_DESTINATION "${_alpaka_INSTALL_CMAKEDIR}")

install(FILES "${PROJECT_BINARY_DIR}/alpakaConfig.cmake"
              "${PROJECT_BINARY_DIR}/alpakaConfigVersion.cmake"
        DESTINATION "${_alpaka_INSTALL_CMAKEDIR}")

if(alpaka_INSTALL_TEST_HEADER)
    install(DIRECTORY "${_alpaka_SUFFIXED_INCLUDE_DIR}"
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
else()
install(DIRECTORY "${_alpaka_SUFFIXED_INCLUDE_DIR}"
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
            PATTERN "test" EXCLUDE)
endif()

install(FILES "${_alpaka_ROOT_DIR}/cmake/addExecutable.cmake"
              "${_alpaka_ROOT_DIR}/cmake/addLibrary.cmake"
              "${_alpaka_ROOT_DIR}/cmake/alpakaCommon.cmake"
              "${_alpaka_ROOT_DIR}/cmake/common.cmake"
        DESTINATION "${_alpaka_INSTALL_CMAKEDIR}")
install(DIRECTORY "${_alpaka_ROOT_DIR}/cmake/tests"
        DESTINATION "${_alpaka_INSTALL_CMAKEDIR}")

install(TARGETS alpaka EXPORT alpakaTargets)
install(EXPORT alpakaTargets DESTINATION "${_alpaka_INSTALL_CMAKEDIR}" NAMESPACE alpaka::)
```

--------------------------------

### C++ BDD Scenario: Fixture Setup

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/tests/SelfTest/Baselines/console.sw.approved.txt

Example of a Behavior-Driven Development (BDD) scenario in C++ that requires fixtures for setup. It demonstrates a precondition 'Given: No operations precede me'.

```cpp
#include <catch2/catch_test_macros.hpp>

SCENARIO("BDD tests requiring Fixtures to provide commonly-accessed data or methods", "[bdd_fixtures]") {
    GIVEN("No operations precede me") {
        // Fixture setup would go here
        int before = 0;
        REQUIRE( before == 0 );
    }
}
```

--------------------------------

### Check and Install Software with agc-manager (Bash)

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/ci.rst

This bash script demonstrates how to check if a specific software version (e.g., boost) is installed using the 'agc-manager' tool. If the software is not found, it provides a placeholder comment for installation logic. This pattern is common for managing dependencies within containers.

```bash
if agc-manager -e boost@${ALPAKA_CI_BOOST_VER} ; then
  export ALPAKA_CI_BOOST_ROOT=$(agc-manager -b boost@${ALPAKA_CI_BOOST_VER})
else
  # install boost
fi
```

--------------------------------

### Add Executable and Test Target

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/counterBasedRng/CMakeLists.txt

Defines the main executable for the example and links it with the Alpaka library. It also sets a folder property for organization and adds a test case to run the executable.

```cmake
alpaka_add_executable(
    ${_TARGET_NAME}
    src/counterBasedRng.cpp)
target_link_libraries(
    ${_TARGET_NAME}
    PUBLIC alpaka::alpaka)

set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```

--------------------------------

### Fixture Example: Sections in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Shows how to use sections within a test case for better organization and reporting in Alpaka. Sections allow grouping related assertions within a single test case.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("Test case with sections") {
    REQUIRE(true);

    SECTION("First section") {
        REQUIRE(1 == 1);
    }

    SECTION("Second section") {
        CHECK(2 == 2);
    }
}
```

--------------------------------

### Assertion Examples: REQUIRE and CHECK in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Demonstrates the usage of `REQUIRE` and `CHECK` macros for assertions in Alpaka. `REQUIRE` stops test execution on failure, while `CHECK` continues.

```cpp
#include <alpaka/test.hpp>

TEST_CASE("REQUIRE and CHECK assertions") {
    REQUIRE(10 == 10); // Test continues if true
    CHECK(5 < 3);     // Test continues even if false
    REQUIRE(true);    // This will pass
}
```

--------------------------------

### Building Alpaka Project with CUDA Accelerator

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/basic/example.rst

These bash commands demonstrate the CMake configuration and build process for a project using Alpaka with the CUDA accelerator enabled. It involves creating a build directory, configuring CMake with the appropriate flag, and then building the project.

```bash
cd <path/to/the/project/root>
mkdir build && cd build
cmake .. -Dalpaka_ACC_GPU_CUDA_ENABLE=ON
cmake --build .
./myexample
```

--------------------------------

### Generator Example: Table-driven Tests in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Illustrates how to run tests with a table of input values using Alpaka's generator functionality. Table-driven tests are efficient for testing multiple input/output combinations.

```cpp
#include <alpaka/test.hpp>
#include <vector>

TEST_CASE("Table-driven tests with generators") {
    // Example: GENERATE(table<int, int>({ {1, 2}, {3, 4} }));
    // This would run the test case twice with different pairs of values.
    int a, b;
    REQUIRE(a + 1 == b);
}
```

--------------------------------

### Set Target Properties and Add Test

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/useBLASInAlpaka/useRocBLASInAlpaka/CMakeLists.txt

Organizes the executable under an 'example' folder in the build environment and adds a CTest test that will run the created executable.

```cmake
set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)
add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```

--------------------------------

### Set Minimum CMake Version and Project Name

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/reduce/CMakeLists.txt

Configures the minimum required CMake version and sets the project name. It also enables folder organization in the CMake build environment. This is a standard CMake setup step.

```cmake
cmake_minimum_required(VERSION 3.25)

set_property(GLOBAL PROPERTY USE_FOLDERS ON)

set(_TARGET_NAME reduce)

project(${_TARGET_NAME} LANGUAGES CXX)
```

--------------------------------

### C++ Catch2 Event Listener Implementation

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/event-listeners.md

Example of a custom Catch2 event listener in C++. This listener initializes a library when the test run starts. It derives from `Catch::EventListenerBase` and uses `CATCH_REGISTER_LISTENER` for registration. Assertions should not be used within listeners.

```cpp
#include <catch2/reporters/catch_reporter_event_listener.hpp>
#include <catch2/reporters/catch_reporter_registrars.hpp>

class testRunListener : public Catch::EventListenerBase {
public:
    using Catch::EventListenerBase::EventListenerBase;

    void testRunStarting(Catch::TestRunInfo const&) override {
        lib_foo_init();
    }
};

CATCH_REGISTER_LISTENER(testRunListener)
```

--------------------------------

### Instantiate Alpaka Device and Platform

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/test.rst

This C++ code snippet demonstrates how to create instances of an Alpaka platform and a specific device. It initializes a platform object and then retrieves the first available device (index 0) associated with it.

```cpp
auto const platform = Platform{};
Dev const dev = alpaka::getDevByIdx(platform, 0);
```

--------------------------------

### Build Documentation Locally (Bash)

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/sphinx.rst

Commands to build the documentation locally. This includes generating C++ API documentation with Doxygen, rendering a PDF cheatsheet with rst2pdf, building HTML documentation with Sphinx, and building a PDF version via LaTeX. It also includes commands to clean the build and check links.

```bash
# skip this if you are still in docs/
cd docs/

# parse the C++ API documentation (default: xml format)
doxygen Doxyfile

# render the cheatsheet.pdf
rst2pdf -s cheatsheet/cheatsheet.style source/basic/cheatsheet.rst -o cheatsheet/cheatsheet.pdf

# render the '.rst' files with sphinx
make html

# open it, e.g. with firefox :)
firefox build/html/index.html

# now again for the pdf :)
make latexpdf

# open it, e.g. with okular
build/latex/alpaka.pdf

# clean the build directory
make clean

# check existence of links
# cd docs/
make checklinks
```

--------------------------------

### Assertion Example: REQUIRE_THROWS_MATCHES in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for `REQUIRE_THROWS_MATCHES` in Alpaka, allowing assertions on exception properties using matchers.

```cpp
#include <alpaka/test.hpp>
#include <stdexcept>
#include <alpaka/matchers.hpp> // Assuming matchers header

void functionThatThrowsComplex() { throw std::runtime_error("error detail"); }

TEST_CASE("REQUIRE_THROWS_MATCHES example") {
    // REQUIRE_THROWS_MATCHES(functionThatThrowsComplex(), ExceptionWithCode(1) && ExceptionWithMessage("error detail"));
    REQUIRE(true);
}
```

--------------------------------

### Assertion Example: REQUIRE_THROWS in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for `REQUIRE_THROWS` in Alpaka, used to assert that a specific code block throws an exception of any type.

```cpp
#include <alpaka/test.hpp>

void functionThatThrows() { throw std::runtime_error("error"); }

TEST_CASE("REQUIRE_THROWS example") {
    REQUIRE_THROWS(functionThatThrows());
}
```

--------------------------------

### Add Executable and Link Libraries

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/useBLASInAlpaka/useRocBLASInAlpaka/CMakeLists.txt

Adds the main executable for the example using the specified source file. It then links the executable against the Alpaka library and rocBLAS, making their functionality available.

```cmake
alpaka_add_executable(
    ${_TARGET_NAME}
    src/useRocBLASInAlpaka.cpp)
target_link_libraries(
    ${_TARGET_NAME}
    PUBLIC alpaka::alpaka rocblas)
```

--------------------------------

### Assertion Example: REQUIRE_NO_THROW in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example demonstrating `REQUIRE_NO_THROW` in Alpaka, used to assert that a specific code block does not throw any exceptions.

```cpp
#include <alpaka/test.hpp>

void functionThatDoesntThrow() {}

TEST_CASE("REQUIRE_NO_THROW example") {
    REQUIRE_NO_THROW(functionThatDoesntThrow());
}
```

--------------------------------

### Add Executable and Link Alpaka (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/heatEquation/CMakeLists.txt

Uses the custom Alpaka CMake function `alpaka_add_executable` to create the 'heatEquation' executable from the 'src/heatEquation.cpp' source file. It then links the Alpaka library to this executable and sets the target property to place it in the 'example' folder within the build system.

```cmake
#-------------------------------------------------------------------------------#
# Add executable.

alpaka_add_executable(
    ${_TARGET_NAME}
    src/heatEquation.cpp)
target_link_libraries(
    ${_TARGET_NAME}
    PUBLIC alpaka::alpaka)

set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```

--------------------------------

### Compiling HIP from Source with CMake

Source: https://github.com/alpaka-group/alpaka/blob/develop/docs/source/dev/backends.rst

This code snippet demonstrates how to clone the HIP repository, create a build directory, configure the build using CMake with specified installation prefix and disabling testing, and then compile and install HIP.

```bash
git clone --recursive https://github.com/ROCm-Developer-Tools/HIP.git
cd HIP
mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE="${CMAKE_BUILD_TYPE}" -DCMAKE_INSTALL_PREFIX=${YOUR_HIP_INSTALL_DIR} -DBUILD_TESTING=OFF ..
make
make install
```

--------------------------------

### Configure Process with Command Line Arguments

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/tests/SelfTest/Baselines/tap.sw.multi.approved.txt

Demonstrates how to configure process settings like benchmark samples, resamples, confidence interval, disabling analysis, and warmup time using command-line arguments. These settings are parsed and stored in a configuration object.

```C++
# Process can be configured on command line
ok {test-number} - cli.parse({ "test", "--benchmark-samples=200" }) for: {?}
# Process can be configured on command line
ok {test-number} - config.benchmarkSamples == 200 for: 200 == 200
# Process can be configured on command line
ok {test-number} - cli.parse({ "test", "--benchmark-resamples=20000" }) for: {?}
# Process can be configured on command line
ok {test-number} - config.benchmarkResamples == 20000 for: 20000 (0x<hex digits>) == 20000 (0x<hex digits>)
# Process can be configured on command line
ok {test-number} - cli.parse({ "test", "--benchmark-confidence-interval=0.99" }) for: {?}
# Process can be configured on command line
ok {test-number} - config.benchmarkConfidenceInterval == Catch::Approx(0.99) for: 0.98999999999999999 == Approx( 0.98999999999999999 )
# Process can be configured on command line
ok {test-number} - cli.parse({ "test", "--benchmark-no-analysis" }) for: {?}
# Process can be configured on command line
ok {test-number} - config.benchmarkNoAnalysis for: true
# Process can be configured on command line
ok {test-number} - cli.parse({ "test", "--benchmark-warmup-time=10" }) for: {?}
# Process can be configured on command line
ok {test-number} - config.benchmarkWarmupTime == 10 for: 10 == 10
```

--------------------------------

### Assertion Example: REQUIRE_THROWS_AS in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for `REQUIRE_THROWS_AS` in Alpaka, used to assert that a specific code block throws an exception of a particular type.

```cpp
#include <alpaka/test.hpp>
#include <stdexcept>

void functionThatThrowsStdException() { throw std::runtime_error("error"); }

TEST_CASE("REQUIRE_THROWS_AS example") {
    REQUIRE_THROWS_AS(functionThatThrowsStdException(), std::runtime_error);
}
```

--------------------------------

### Print Help and Usage Information

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/command-line.md

Displays the command-line arguments and their descriptions to standard output. This is useful for understanding the available options and how to use the executable.

```bash
-h, -?, --help
```

--------------------------------

### Add Executable Target and Link Libraries (CMake)

Source: https://github.com/alpaka-group/alpaka/blob/develop/test/unit/exec/CMakeLists.txt

Defines an executable target, includes source and header files recursively, sets include directories, links libraries, and configures target properties for organization and testing.

```cmake
set(_TARGET_NAME "execTest")

append_recursive_files_add_to_src_group("src/" "src/" "cpp" _FILES_SOURCE)
append_recursive_files_add_to_src_group("src/" "src/" "hpp" _FILES_HEADER)

alpaka_add_executable(
    ${_TARGET_NAME}
    ${_FILES_SOURCE}
    ${_FILES_HEADER})

target_include_directories(
    ${_TARGET_NAME}
    PRIVATE ${Boost_INCLUDE_DIRS})

target_link_libraries(
    ${_TARGET_NAME}
    PRIVATE common)

set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER "test/unit")

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME} ${_alpaka_TEST_OPTIONS})
```

--------------------------------

### BDD Example: SCENARIO, GIVEN, WHEN, THEN in C++

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Shows how to implement Behavior-Driven Development (BDD) style tests using `SCENARIO`, `GIVEN`, `WHEN`, and `THEN` macros in Alpaka. This promotes writing tests in a more readable, natural language format.

```cpp
#include <alpaka/test.hpp>

SCENARIO("User login scenario") {
    GIVEN("A registered user") {
        WHEN("The user enters correct credentials") {
            THEN("The user should be logged in") {
                REQUIRE(true);
            }
        }
    }
}
```

--------------------------------

### Assertion Example: REQUIRE_THROWS_WITH in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for `REQUIRE_THROWS_WITH` in Alpaka, used to assert that a specific code block throws an exception containing a particular string message.

```cpp
#include <alpaka/test.hpp>
#include <stdexcept>

void functionThatThrowsWithMessage() { throw std::runtime_error("specific message"); }

TEST_CASE("REQUIRE_THROWS_WITH example") {
    REQUIRE_THROWS_WITH(functionThatThrowsWithMessage(), "specific message");
}
```

--------------------------------

### Assertion Example: REQUIRE_THAT and Matchers in C++ (Planned)

Source: https://github.com/alpaka-group/alpaka/blob/develop/thirdParty/catch2/docs/list-of-examples.md

Planned example for using `REQUIRE_THAT` with matchers in Alpaka. This provides a powerful and expressive way to define complex assertion conditions.

```cpp
#include <alpaka/test.hpp>
#include <alpaka/matchers.hpp> // Assuming matchers header

TEST_CASE("REQUIRE_THAT with matchers") {
    int value = 5;
    // REQUIRE_THAT(value, IsPositive() && IsEven()); // Example matcher usage
    REQUIRE(value == 5);
}
```

--------------------------------

### Add Executable and Test Target

Source: https://github.com/alpaka-group/alpaka/blob/develop/example/tagSpecialization/CMakeLists.txt

This snippet defines an executable target named 'tagSpecialization' using the source file 'src/tagSpecialization.cpp'. It links the 'alpaka::alpaka' library to this executable and sets its folder property to 'example'. A test is also added to run the executable.

```cmake
alpaka_add_executable(
    ${_TARGET_NAME}
    src/tagSpecialization.cpp)
target_link_libraries(
    ${_TARGET_NAME}
    PUBLIC alpaka::alpaka)

set_target_properties(${_TARGET_NAME} PROPERTIES FOLDER example)

add_test(NAME ${_TARGET_NAME} COMMAND ${_TARGET_NAME})
```