Document how to integrate kokkos into a cmake project

docs/source/building.md

@@ -6,31 +6,7 @@ As C++ continues to develop for C++20 and beyond, CMake is likely to provide the
 for C++.  Applications heavily leveraging Kokkos are strongly encouraged to use a CMake build system.
 
 You can either use Kokkos as an installed package (encouraged) or use Kokkos in-tree in your project.
-Modern CMake is exceedingly simple at a high-level (with the devil in the details).
-Once Kokkos is installed In your `CMakeLists.txt` simply use:
-````cmake
-find_package(Kokkos REQUIRED)
-````
-Then for every executable or library in your project:
-````cmake
-target_link_libraries(myTarget Kokkos::kokkos)
-````
-That's it! There is no checking Kokkos preprocessor, compiler, or linker flags.
-Kokkos propagates all the necessary flags to your project.
-This means not only is linking to Kokkos easy, but Kokkos itself can actually configure compiler and linker flags for *your*
-project.
-When configuring your project just set:
-````bash
-> cmake ${srcdir} \
-  -DKokkos_ROOT=${kokkos_install_prefix} \
-  -DCMAKE_CXX_COMPILER=${compiler_used_to_build_kokkos}
-````
-Note: You may need the following if using some versions of CMake (e.g. 3.12):
-````cmake
-cmake_policy(SET CMP0074 NEW)
-````
-If building in-tree, there is no `find_package`. You can use `add_subdirectory(kokkos)` with the Kokkos source and again just link with `target_link_libraries(Kokkos::kokkos)`.
-The examples in `examples/cmake_build_installed` and `examples/cmake_build_in_tree` can help get you started.
+See [Integrating Kokkos into Your Project](https://kokkos.org/kokkos-core-wiki/integrating_kokkos_into_your_cmake_project.html).
 
 ## Configuring CMake
 A very basic installation of Kokkos is done with:

docs/source/index.rst

@@ -87,6 +87,7 @@ Website Content
    programmingguide
    requirements
    building
+   ./integrating_kokkos_into_your_cmake_project
    keywords
    ./API/core-index
    ./API/containers-index

docs/source/integrating_kokkos_into_your_cmake_project.rst

@@ -0,0 +1,115 @@
+# Integrating Kokkos into Your Project
+This section describes how to integrate the Kokkos library into your CMake
+project.
+
+Kokkos provides the `Kokkos::kokkos` target, which simplifies the
+process by automatically handling necessary include directories, link
+libraries, compiler options, and other usage requirements.
+
+Here are several integration methods, each with its own advantages:
+
+## 1. External Kokkos (Recommended for most users)
+The recommended approach is to use Kokkos as an external dependency. This
+allows for easier management and updates.  Use CMake's
+[`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html)
+command to locate and link against an existing Kokkos installation:
+```cmake
+# CMakeLists.txt
+find_package(Kokkos 4.2 REQUIRED CONFIG) # Find Kokkos version 4.2 or later
+# ...
+target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)
+```
+* `find_package(Kokkos ...)` searches for a `KokkosConfig.cmake` file, which is
+  generated when Kokkos is built and installed. This file contains the
+  necessary information for linking against Kokkos.
+* The `4.2` argument specifies the minimum required Kokkos version. It's
+  optional but recommended for ensuring compatibility.
+* `Kokkos::kokkos` is the namespaced imported target that provides all
+  necessary build flags.
+* The `CONFIG` keyword tells CMake to use the configuration files.
+
+You can install Kokkos separately and then point CMake to its location using
+the `Kokkos_ROOT` variable.
+```bash
+cmake -DKokkos_ROOT=/path/to/kokkos/install/dir -B build
+```
+
+## 2. Embedded Kokkos via `add_subdirectory()` and Git Submodules
+This method embeds the Kokkos source code directly into your project.  It's
+useful when you need very tight control over the Kokkos version or when you
+can't install Kokkos separately.
+
+1. Add Kokkos as a [Git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules):
+  ```bash
+  git submodule add -b 4.5.01 https://github.com/kokkos/kokkos.git tpls/kokkos
+  git commit -m 'Adding Kokkos v4.5.1 as a submodule'
+  ```
+  `tpls/kokkos` should now contain the full Kokkos source tree.
+2. Use `add_subdirectory()` in your CMakeLists.txt:
+  ```cmake
+  add_subdirectory(tpls/kokkos)
+  # ...
+  target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)
+  ```
+
+## 3. Embedded Kokkos via `FetchContent`
+[FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)
+simplifies the process of downloading and including Kokkos as a dependency
+during the CMake configuration stage.
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+    Kokkos
+    URL      https://github.com/kokkos/kokkos/releases/download/4.5.01/kokkos-4.5.01.tar.gz
+    URL_HASH SHA256=52d003ffbbe05f30c89966e4009c017efb1662b02b2b73190670d3418719564c
+)
+FetchContent_MakeAvailable(Kokkos)
+# ...
+target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)
+```
+* `URL_HASH` is highly recommended for verifying the integrity of the
+  downloaded archive. You can find the SHA256 checksums for Kokkos releases in
+  the `kokkos-X.Y.Z-SHA-256.txt` file on the [Kokkos releases
+  page](https://github.com/kokkos/kokkos/releases).
+
+
+## 4. Supporting Both External and Embedded Kokkos
+This approach allows your project to use either an external Kokkos installation
+or an embedded version, providing flexibility for different build environments.
+
+```cmake
+find_package(Kokkos CONFIG) # Try to find Kokkos externally
+if(Kokkos_FOUND)
+    message(STATUS "Found Kokkos: ${Kokkos_DIR} (version \"${Kokkos_VERSION}\")")
+else()
+    message(STATUS "Kokkos not found externally. Fetching via FetchContent.")
+    include(FetchContent)
+    FetchContent_Declare(
+        Kokkos
+        URL https://github.com/kokkos/kokkos/archive/refs/tags/4.4.01.tar.gz
+    )
+    FetchContent_MakeAvailable(Kokkos)
+endif()
+# ...
+target_link_libraries(MyTarget PRIVATE Kokkos::kokkos)
+```
+
+Controlling the Kokkos integration:
+
+* [`CMAKE_DISABLE_FIND_PACKAGE_Kokkos`](https://cmake.org/cmake/help/latest/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html):
+  Set this variable to `TRUE` to force the use of the embedded Kokkos, even if
+  an external installation is found.
+* [`CMAKE_REQUIRE_FIND_PACKAGE_Kokkos`](https://cmake.org/cmake/help/latest/variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName.html):
+  Set this variable to `TRUE` to require an external Kokkos installation. The
+  build will fail if Kokkos is not found.
+* `Kokkos_ROOT`: Use this variable to specify the directory where CMake should
+  search for Kokkos when using `find_package()`.
+
+For example:
+```bash
+cmake -DCMAKE_REQUIRE_FIND_PACKAGE_Kokkos=ON -DKokkos_ROOT=/path/to/kokkos/install/dir
+```
+or
+```bash
+cmake -DCMAKE_DISABLE_FIND_PACKAGE_Kokkos=ON
+```