diff --git a/.gitignore b/.gitignore index 6ea113dc6099..6c946c893997 100644 --- a/.gitignore +++ b/.gitignore @@ -38,7 +38,7 @@ build/ /.settings/ # Visual Studio Code project files -.vscode/ +.vscode # Visual Studio project files .vs/ @@ -57,3 +57,6 @@ jobs.yml # pipenv files Pipfile Pipfile.lock + +# user specific cmake preset settings +CMakeUserPresets.json diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 000000000000..facf23187c44 --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,198 @@ +{ + "version": 3, + "cmakeMinimumRequired": { + "major": 3, + "minor": 22, + "patch": 0 + }, + "configurePresets": [ + { + "name": "develop", + "description": "enable tests and examples", + "hidden": true, + "binaryDir": "${sourceDir}/build/${presetName}", + "cacheVariables": { + "alpaka_BUILD_EXAMPLES": "ON", + "BUILD_TESTING": "ON" + } + }, + { + "name": "cpu-serial", + "description": "enable serial back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON" + } + }, + { + "name": "cpu-omp2b", + "description": "enable OpenMP 2 Grid Block back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_OMP2_T_SEQ_ENABLE": "ON" + } + }, + { + "name": "cpu-omp2t", + "description": "enable OpenMP 2 Block Thread back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_SEQ_T_OMP2_ENABLE": "ON" + } + }, + { + "name": "cpu-stdthreads", + "description": "enable std::thread back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE": "ON" + } + }, + { + "name": "cpu-tbb", + "description": "enable Intel TBB back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_TBB_T_SEQ_ENABLE": "ON" + } + }, + { + "name": "cpu-all", + "description": "enable all cpu back-ends (serial, OpenMP 2 Grid Block and Block Thread, std::thread and Intel TBB back-end", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON", + "alpaka_ACC_CPU_B_OMP2_T_SEQ_ENABLE": "ON", + "alpaka_ACC_CPU_B_SEQ_T_OMP2_ENABLE": "ON", + "alpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE": "ON", + "alpaka_ACC_CPU_B_TBB_T_SEQ_ENABLE": "ON" + } + }, + { + "name": "gpu-hip", + "description": "use HIP back-end on AMD GPUs", + "inherits": "develop", + "cacheVariables": { + "CMAKE_CXX_COMPILER": "hipcc", + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON", + "alpaka_ACC_GPU_HIP_ENABLE": "ON" + } + }, + { + "name": "gpu-sycl-intel", + "description": "use Sycl back-end on Intel GPUs", + "inherits": "develop", + "cacheVariables": { + "CMAKE_CXX_COMPILER": "icpx", + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON", + "alpaka_ACC_SYCL_ENABLE": "ON", + "alpaka_SYCL_ONEAPI_GPU": "ON", + "alpaka_SYCL_ONEAPI_GPU_DEVICES": "spir64" + } + }, + { + "name": "gpu-cuda-nvcc", + "description": "use cuda back-end on Nvidia GPUs with nvcc device compiler", + "inherits": "develop", + "cacheVariables": { + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON", + "alpaka_ACC_GPU_CUDA_ENABLE": "ON" + } + }, + { + "name": "gpu-cuda-clang", + "description": "use cuda back-end on Nvidia GPUs with clang++ device compiler", + "inherits": "develop", + "cacheVariables": { + "CMAKE_CXX_COMPILER": "clang++", + "CMAKE_CUDA_COMPILER": "clang++", + "alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE": "ON", + "alpaka_ACC_GPU_CUDA_ENABLE": "ON" + } + } + ], + "buildPresets": [ + { + "name": "cpu-serial", + "configurePreset": "cpu-serial" + }, + { + "name": "cpu-omp2b", + "configurePreset": "cpu-omp2b" + }, + { + "name": "cpu-omp2t", + "configurePreset": "cpu-omp2t" + }, + { + "name": "cpu-stdthreads", + "configurePreset": "cpu-stdthreads" + }, + { + "name": "cpu-tbb", + "configurePreset": "cpu-tbb" + }, + { + "name": "cpu-all", + "configurePreset": "cpu-all" + }, + { + "name": "gpu-hip", + "configurePreset": "gpu-hip" + }, + { + "name": "gpu-sycl-intel", + "configurePreset": "gpu-sycl-intel" + }, + { + "name": "gpu-cuda-nvcc", + "configurePreset": "gpu-cuda-nvcc" + }, + { + "name": "gpu-cuda-clang", + "configurePreset": "gpu-cuda-clang" + } + ], + "testPresets": [ + { + "name": "cpu-serial", + "configurePreset": "cpu-serial" + }, + { + "name": "cpu-omp2b", + "configurePreset": "cpu-omp2b" + }, + { + "name": "cpu-omp2t", + "configurePreset": "cpu-omp2t" + }, + { + "name": "cpu-stdthreads", + "configurePreset": "cpu-stdthreads" + }, + { + "name": "cpu-tbb", + "configurePreset": "cpu-tbb" + }, + { + "name": "cpu-all", + "configurePreset": "cpu-all" + }, + { + "name": "gpu-hip", + "configurePreset": "gpu-hip" + }, + { + "name": "gpu-sycl-intel", + "configurePreset": "gpu-sycl-intel" + }, + { + "name": "gpu-cuda-nvcc", + "configurePreset": "gpu-cuda-nvcc" + }, + { + "name": "gpu-cuda-clang", + "configurePreset": "gpu-cuda-clang" + } + ] +} diff --git a/docs/source/advanced/cmake.rst b/docs/source/advanced/cmake.rst index a5f5ebeccd05..df0541094943 100644 --- a/docs/source/advanced/cmake.rst +++ b/docs/source/advanced/cmake.rst @@ -1,12 +1,99 @@ CMake Arguments =============== -Alpaka configures a lot of its functionality at compile time. Therefore a lot of compiler and link flags are needed, which are set by CMake arguments. The beginning of this section introduces the general Alpaca flag. The last parts of the section describe back-end specific flags. +Alpaka configures a large part of its functionality at compile time. Therefore, a lot of compiler and link flags are needed, which are set by CMake arguments. First, we show a simple way to build alpaka for different back-ends using `CMake Presets `_. The second part of the documentation shows the general and back-end specific alpaka CMake flags. .. hint:: To display the cmake variables with value and type in the build folder of your project, use ``cmake -LH ``. +CMake Presets +------------- + +The `CMake Presets `_ are defined in the ``CMakePresets.json`` file. Each preset contains a set of CMake arguments. We use different presets to build the examples and tests with different back-ends. Execute the following command to display all presets: + +.. code-block:: bash + + cd + cmake --list-presets + +To configure, build and run the tests of a specific preset, run the following commands (for the example, we use the ``cpu-serial`` preset): + +.. code-block:: bash + + cd + # configure a specific preset + cmake --preset cpu-serial + # build the preset + cmake --build --preset cpu-serial + # run test of the preset + ctest --preset cpu-serial + +All presets are configure and build in a subfolder of the ``/build`` folder. + +Modifying and Extending Presets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way to change a preset is to set CMake arguments during configuration: + +.. code-block:: bash + + cd + # configure the cpu-serial preset with clang++ as C++ compiler + cmake --preset cpu-serial -DCMAKE_CXX_COMPILER=clang++ + # build the preset + cmake --build --preset cpu-serial + # run test of the preset + ctest --preset cpu-serial + +It is also possible to configure the default setting first and then change the arguments with ``ccmake``: + +.. code-block:: bash + + cd + # configure the cpu-serial preset with clang++ as C++ compiler + cmake --preset cpu-serial + cd build/cpu-serial + ccmake . + cd ../.. + # build the preset + cmake --build --preset cpu-serial + # run test of the preset + ctest --preset cpu-serial + +CMake presets also offer the option of creating personal, user-specific configurations based on the predefined CMake presets. To do this, you can create the file ``CMakeUserPresets.json`` in the root directory of your project (the file is located directly next to ``CMakePresets.json``). You can then create your own configurations from the existing CMake presets. The following example takes the cpu-serial configuration, uses ``ninja`` as the generator instead of the standard generator and uses the build type ``RELEASE``. + +.. code-block:: json + + { + "version": 3, + "cmakeMinimumRequired": { + "major": 3, + "minor": 22, + "patch": 0 + }, + "configurePresets": [ + { + "name": "cpu-serial-ninja-release", + "inherits": "cpu-serial", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": { + "type": "STRING", + "value": "RELEASE" + } + } + } + ] + } + +.. hint:: + + Many IDEs like `Visual Studio Code `_ and `CLion `_ support CMake presets. + +Arguments +--------- + **Table of back-ends** * :ref:`CPU Serial ` @@ -18,7 +105,7 @@ Alpaka configures a lot of its functionality at compile time. Therefore a lot of * :ref:`HIP ` Common ------- +^^^^^^ alpaka_CXX_STANDARD .. code-block:: @@ -89,7 +176,7 @@ alpaka_USE_MDSPAN .. _cpu-serial: CPU Serial ----------- +^^^^^^^^^^ alpaka_ACC_CPU_B_SEQ_T_SEQ_ENABLE .. code-block:: @@ -105,7 +192,7 @@ alpaka_BLOCK_SHARED_DYN_MEMBER_ALLOC_KIB .. _cpp-threads: C++ Threads ------------ +^^^^^^^^^^^ alpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE .. code-block:: @@ -115,7 +202,7 @@ alpaka_ACC_CPU_B_SEQ_T_THREADS_ENABLE .. _intel-tbb: Intel TBB ---------- +^^^^^^^^^ alpaka_ACC_CPU_B_TBB_T_SEQ_ENABLE .. code-block:: @@ -131,7 +218,7 @@ alpaka_BLOCK_SHARED_DYN_MEMBER_ALLOC_KIB .. _openmp2-grid-block: OpenMP 2 Grid Block -------------------- +^^^^^^^^^^^^^^^^^^^ alpaka_ACC_CPU_B_OMP2_T_SEQ_ENABLE .. code-block:: @@ -147,7 +234,7 @@ alpaka_BLOCK_SHARED_DYN_MEMBER_ALLOC_KIB .. _openmp2-block-thread: OpenMP 2 Block thread ---------------------- +^^^^^^^^^^^^^^^^^^^^^ alpaka_ACC_CPU_B_SEQ_T_OMP2_ENABLE .. code-block:: @@ -157,7 +244,7 @@ alpaka_ACC_CPU_B_SEQ_T_OMP2_ENABLE .. _cuda: CUDA ----- +^^^^ alpaka_ACC_GPU_CUDA_ENABLE .. code-block:: @@ -203,7 +290,7 @@ alpaka_RELOCATABLE_DEVICE_CODE Enable relocatable device code. Note: This affects all targets in the CMake scope where ``alpaka_RELOCATABLE_DEVICE_CODE`` is set. For the effects on CUDA code see NVIDIA's blog post: - + https://developer.nvidia.com/blog/separate-compilation-linking-cuda-device-code/ alpaka_CUDA_SHOW_CODELINES @@ -221,7 +308,7 @@ alpaka_CUDA_SHOW_REGISTER .. _hip: HIP ---- +^^^ To enable the HIP back-end please extend ``CMAKE_PREFIX_PATH`` with the path to the HIP installation. @@ -255,13 +342,13 @@ alpaka_RELOCATABLE_DEVICE_CODE CMake scope where ``alpaka_RELOCATABLE_DEVICE_CODE`` is set. For the effects on HIP code see the NVIDIA blog post linked below; HIP follows CUDA's behaviour. - + https://developer.nvidia.com/blog/separate-compilation-linking-cuda-device-code/ .. _sycl: SYCL ----- +^^^^ alpaka_RELOCATABLE_DEVICE_CODE .. code-block:: @@ -269,5 +356,5 @@ alpaka_RELOCATABLE_DEVICE_CODE Enable relocatable device code. Note: This affects all targets in the CMake scope where ``alpaka_RELOCATABLE_DEVICE_CODE`` is set. For the effects on SYCL code see Intel's documentation: - + https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2023-2/fsycl-rdc.html