Merge pull request #624 from dalg24/improve_quickstart_guide

Improve the Get Started section

docs/source/faq.rst

@@ -1,6 +1,8 @@
 FAQ
 ###
 
+.. _join-slack-workspace:
+
 **How do I join the Kokkos slack channel?**
   You can find the slack channel at `kokkosteam.slack.com <https://kokkosteam.slack.com>`_. Register a new account with your email. We reached the limit of whitelisted organizations, but every member of the Kokkos Slack workspace can invite more people. If no one you know is in the Slack workspace you can contact the Kokkos maintainers (their emails are in the LICENSE file).
 

docs/source/quick_start.rst

@@ -4,83 +4,171 @@ Quick Start
 This guide is intended to jump start new Kokkos users (and beginners, in particular).
 
 
-Download Latest and Build 
------------------------------
+Prerequisites
+~~~~~~~~~~~~~
 
-.. note::
+To complete this tutorial, you'll need:
+
+* a compatible operating system (e.g. Linux, macOS, Windows).
+* a compatible C++ compiler that supports at least C++17.
+* `CMake <https://cmake.org/>`_ and a compatible build tool for building the
+  project.
+
+  * Compatible build tools include `Make
+    <https://www.gnu.org/software/make/>`_, `Ninja <https://ninja-build.org>`_,
+    and others - see `CMake Generators
+    <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_ for
+    more information.
+
+See :doc:`requirements` for more information about platforms compatible with
+Kokkos and a list of supported versions of compilers and software development
+kits (SDKs).
 
-  Please become familiar with `Kokkos Requirements <https://kokkos.org/kokkos-core-wiki/requirements.html>`_, and verify that your machine has all necessary compilers, backend GPU SDK (e.g., CUDA, ROCM, Intel oneAPI, etc.),and build system components.
+If you don’t already have CMake installed, see the `CMake installation guide
+<https://cmake.org/install>`_.
 
 
-:bdg-link-primary:`Latest Release <https://github.com/kokkos/kokkos/releases/latest>`
+Set up a project
+~~~~~~~~~~~~~~~~
+
+CMake uses a file named ``CMakeLists.txt`` to configure the build system for a
+project. You’ll use this file to set up your project and declare a dependency
+on Kokkos.
+
+First, create a directory for your project:
 
 .. code-block:: sh
+
+  > mkdir MyProject && cd MyProject
+
+Next, you’ll create the ``CMakeLists.txt`` file and declare a dependency on
+Kokkos. There are many ways to express dependencies in the CMake ecosystem; in
+this tutorial, you’ll use the `FetchContent CMake module
+<https://cmake.org/cmake/help/latest/module/FetchContent.html>`_. To do this,
+in your project directory (``MyProject``), create a file named
+``CMakeLists.txt`` with the following contents:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.16)
+  project(MyProject)
   
-  # Uncomment according to the type of file you've downloaded (zip or tar)
-  unzip kokkos-x.y.z.zip 
-  # tar -xzf kokkos-x.y.z.tar.gz
-  cd kokkos-x.y.z
+  include(FetchContent)
+  FetchContent_Declare(
+    Kokkos
+    URL https://github.com/kokkos/kokkos/archive/refs/tags/4.5.01.zip
+  )
+  FetchContent_MakeAvailable(Kokkos)
 
+The above configuration declares a dependency on Kokkos which is downloaded
+from GitHub.
+``4.5.01`` is the Kokkos version to use; we generally recommend using the
+`latest available <https://github.com/kokkos/kokkos/releases/latest>`_.
 
-Basic Configure, Build, Install Recipes
-----------------------------------------
+For more information about how to create ``CMakeLists.txt files``, see the
+`CMake Tutorial
+<https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`_.
 
 
-OpenMP (CPU Parallelism)
-~~~~~~~~~~~~~~~~~~~~~~~~
+Create and run an executable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: sh
+With Kokkos declared as a dependency, you can use Kokkos code within your own
+project.
 
-  cmake -B <build-directory> -DKokkos_ENABLE_OPENMP=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory>
-  cmake --build <build-directory>
-  cmake --install <build-directory>
+As an example, create a ``HelloKokkos.cpp`` with the following content:
 
+.. code-block:: c++
 
-.. note::
+  #include <Kokkos_Core.hpp>
 
-  Kokkos will attempt to autodetect GPU microarchitecture, but it is also possible to specify the desired `GPU architecture <https://kokkos.org/kokkos-core-wiki/keywords.html#gpu-architectures>`_.  In scenarios where a device (GPU) backend (e.g., CUDA, HIP) is enabled, Kokkos will default to serial execution on the host (CPU).
+  int main(int argc, char** argv) {
+    Kokkos::initialize(argc, argv);
+    {
+      // Allocate a 1-dimensional view of integers
+      Kokkos::View<int*> v("v", 5);
+      // Fill view with sequentially increasing values v=[0,1,2,3,4]
+      Kokkos::parallel_for("fill", 5, KOKKOS_LAMBDA(int i) { v(i) = i; });
+      // Compute accumulated sum of v's elements r=0+1+2+3+4
+      int r;
+      Kokkos::parallel_reduce(
+        "accumulate", 5,
+        KOKKOS_LAMBDA(int i, int& partial_r) { partial_r += v(i); }, r);
+      // Check the result
+      KOKKOS_ASSERT(r == 10);
+    }
+    Kokkos::printf("Goodbye World\n");
+    Kokkos::finalize();
+    return 0;
+  }
 
-CUDA
-~~~~
+The above program code includes the main Kokkos header file and demonstrates
+how to initialize and finalize the Kokkos execution environment.
 
-.. code-block:: sh
+To build the code, add the following couple lines to the end of your
+``CMakeLists.txt`` file:
 
-  cmake -B <build-directory> -DKokkos_ENABLE_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory> 
-  cmake --build <build-directory>
-  cmake --install <build-directory>
-  
+.. code-block:: cmake
 
-HIP
-~~~
+  add_executable(HelloKokkos HelloKokkos.cpp)
+  target_link_libraries(HelloKokkos Kokkos::kokkos)
 
-.. code-block:: sh
 
-  cmake -B <build-directory> -DKokkos_ENABLE_HIP=ON -DCMAKE_CXX_COMPILER=hipcc -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory>
-  cmake --build <build-directory>
-  cmake --install <build-directory>
+The above configuration declares the executable you want to build
+(``HelloKokkos``), and links it to Kokkos.
 
+Now you can build and run your Kokkos program.
+
+Start with calling ``cmake`` to configure the project and generate a native
+build system:
+
+.. code-block:: sh
+
+  MyProject> cmake -B build
+  -- The C compiler identification is GNU 10.2.1
+  -- The CXX compiler identification is GNU 10.2.1
+  ...
+  -- Build files have been written to: .../MyProject/build
 
-Building and Linking a Kokkos "Hello World"
--------------------------------------------
 
 .. note::
 
-  ``Kokkos_ROOT`` and the root directory for you target backend SDK (i.e., ``CUDA_ROOT``, ``ROCM_PATH``) will need to be set.  ``Kokkos_ROOT`` should be set to the path of your Kokkos installation.  In a modules environment, the SDK variables will be typically automatically set upon module loading (e.g., ``module load rocm/5.7.1``).  Please see `Build, Install and Use <https://kokkos.org/kokkos-core-wiki/building.html>`_ for additional details.  The example detailed below is in the Kokkos Core `example` directory.
+  If you want to target a NVIDIA GPU, you will need to pass an extra
+  ``-DKokkos_ENABLE_CUDA=ON`` argument to the cmake command above. For an AMD
+  or an Intel GPU, you would use ``-DKokkos_ENABLE_HIP=ON`` or
+  ``-DKokkos_ENABLE_SYCL=ON`` respectively. For a list of options and variables
+  available at configuration time, see :doc:`keywords`.
 
 
+Then invoke that build system to actually compile/link the project:
 
 .. code-block:: sh
 
-  git clone https://github.com/kokkos/kokkos.git 
-  cd example/build_cmake_installed
-  cmake -B <build-directory> -S . -DKokkos_ROOT=<install-directory>
-  cd <build-directory>
-  cmake --build . 
-  ./example
-  
+  MyProject> cmake --build build
+  Scanning dependencies of target ...
+  ...
+  [100%] Built target HelloKokkos
+
+Finally try to use the newly built ``HelloKokkos``:
+
+.. code-block:: sh
+
+  MyProject> cd build
+
+  MyProject/build> HelloKokkos
+  Goodbye World
+
+.. note::
+
+   Depending on your shell, the correct syntax may be ``HelloKokkos``,
+   ``./HelloKokkos`` or ``.\HelloKokkos``.
+
+Congratulations! You’ve successfully built and run a test binary using Kokkos.
 
 
-Getting Help
-------------
+Getting help
+~~~~~~~~~~~~
 
-If you need additional help getting started, please join the `Kokkos Slack Channel <https://kokkosteam.slack.com>`_.  Here are `sign up details <https://kokkos.org/kokkos-core-wiki/faq.html#faq>`_.  Joining Kokkos Slack is the on ramp for becoming a project contributor.
+If you need additional help getting started, please join the `Kokkos Slack
+Workspace <https://kokkosteam.slack.com>`_. If you have trouble signing up see the
+:ref:`FAQ entry on how to join <join-slack-workspace>`.