Skip to content

Commit 733285e

Browse files
crtrottcrtrott
authored
Merge pull request #624 from dalg24/improve_quickstart_guide
Improve the Get Started section
2 parents d6c75cc + ee48189 commit 733285e

File tree

2 files changed

+135
-45
lines changed

2 files changed

+135
-45
lines changed

‎docs/source/faq.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
FAQ
22
###
33

4+
.. _join-slack-workspace:
5+
46
**How do I join the Kokkos slack channel?**
57
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).
68

‎docs/source/quick_start.rst

+133-45
Original file line numberDiff line numberDiff line change
@@ -4,83 +4,171 @@ Quick Start
44
This guide is intended to jump start new Kokkos users (and beginners, in particular).
55

66

7-
Download Latest and Build
8-
-----------------------------
7+
Prerequisites
8+
~~~~~~~~~~~~~
99

10-
.. note::
10+
To complete this tutorial, you'll need:
11+
12+
* a compatible operating system (e.g. Linux, macOS, Windows).
13+
* a compatible C++ compiler that supports at least C++17.
14+
* `CMake <https://cmake.org/>`_ and a compatible build tool for building the
15+
project.
16+
17+
* Compatible build tools include `Make
18+
<https://www.gnu.org/software/make/>`_, `Ninja <https://ninja-build.org>`_,
19+
and others - see `CMake Generators
20+
<https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_ for
21+
more information.
22+
23+
See :doc:`requirements` for more information about platforms compatible with
24+
Kokkos and a list of supported versions of compilers and software development
25+
kits (SDKs).
1126

12-
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.
27+
If you don’t already have CMake installed, see the `CMake installation guide
28+
<https://cmake.org/install>`_.
1329

1430

15-
:bdg-link-primary:`Latest Release <https://github.com/kokkos/kokkos/releases/latest>`
31+
Set up a project
32+
~~~~~~~~~~~~~~~~
33+
34+
CMake uses a file named ``CMakeLists.txt`` to configure the build system for a
35+
project. You’ll use this file to set up your project and declare a dependency
36+
on Kokkos.
37+
38+
First, create a directory for your project:
1639

1740
.. code-block:: sh
41+
42+
> mkdir MyProject && cd MyProject
43+
44+
Next, you’ll create the ``CMakeLists.txt`` file and declare a dependency on
45+
Kokkos. There are many ways to express dependencies in the CMake ecosystem; in
46+
this tutorial, you’ll use the `FetchContent CMake module
47+
<https://cmake.org/cmake/help/latest/module/FetchContent.html>`_. To do this,
48+
in your project directory (``MyProject``), create a file named
49+
``CMakeLists.txt`` with the following contents:
50+
51+
.. code-block:: cmake
52+
53+
cmake_minimum_required(VERSION 3.16)
54+
project(MyProject)
1855
19-
# Uncomment according to the type of file you've downloaded (zip or tar)
20-
unzip kokkos-x.y.z.zip
21-
# tar -xzf kokkos-x.y.z.tar.gz
22-
cd kokkos-x.y.z
56+
include(FetchContent)
57+
FetchContent_Declare(
58+
Kokkos
59+
URL https://github.com/kokkos/kokkos/archive/refs/tags/4.5.01.zip
60+
)
61+
FetchContent_MakeAvailable(Kokkos)
2362
63+
The above configuration declares a dependency on Kokkos which is downloaded
64+
from GitHub.
65+
``4.5.01`` is the Kokkos version to use; we generally recommend using the
66+
`latest available <https://github.com/kokkos/kokkos/releases/latest>`_.
2467

25-
Basic Configure, Build, Install Recipes
26-
----------------------------------------
68+
For more information about how to create ``CMakeLists.txt files``, see the
69+
`CMake Tutorial
70+
<https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`_.
2771

2872

29-
OpenMP (CPU Parallelism)
30-
~~~~~~~~~~~~~~~~~~~~~~~~
73+
Create and run an executable
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3175

32-
.. code-block:: sh
76+
With Kokkos declared as a dependency, you can use Kokkos code within your own
77+
project.
3378

34-
cmake -B <build-directory> -DKokkos_ENABLE_OPENMP=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory>
35-
cmake --build <build-directory>
36-
cmake --install <build-directory>
79+
As an example, create a ``HelloKokkos.cpp`` with the following content:
3780

81+
.. code-block:: c++
3882

39-
.. note::
83+
#include <Kokkos_Core.hpp>
4084

41-
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).
85+
int main(int argc, char** argv) {
86+
Kokkos::initialize(argc, argv);
87+
{
88+
// Allocate a 1-dimensional view of integers
89+
Kokkos::View<int*> v("v", 5);
90+
// Fill view with sequentially increasing values v=[0,1,2,3,4]
91+
Kokkos::parallel_for("fill", 5, KOKKOS_LAMBDA(int i) { v(i) = i; });
92+
// Compute accumulated sum of v's elements r=0+1+2+3+4
93+
int r;
94+
Kokkos::parallel_reduce(
95+
"accumulate", 5,
96+
KOKKOS_LAMBDA(int i, int& partial_r) { partial_r += v(i); }, r);
97+
// Check the result
98+
KOKKOS_ASSERT(r == 10);
99+
}
100+
Kokkos::printf("Goodbye World\n");
101+
Kokkos::finalize();
102+
return 0;
103+
}
42104

43-
CUDA
44-
~~~~
105+
The above program code includes the main Kokkos header file and demonstrates
106+
how to initialize and finalize the Kokkos execution environment.
45107

46-
.. code-block:: sh
108+
To build the code, add the following couple lines to the end of your
109+
``CMakeLists.txt`` file:
47110

48-
cmake -B <build-directory> -DKokkos_ENABLE_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory>
49-
cmake --build <build-directory>
50-
cmake --install <build-directory>
51-
111+
.. code-block:: cmake
52112
53-
HIP
54-
~~~
113+
add_executable(HelloKokkos HelloKokkos.cpp)
114+
target_link_libraries(HelloKokkos Kokkos::kokkos)
55115
56-
.. code-block:: sh
57116
58-
cmake -B <build-directory> -DKokkos_ENABLE_HIP=ON -DCMAKE_CXX_COMPILER=hipcc -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<install-directory> -S <source-directory>
59-
cmake --build <build-directory>
60-
cmake --install <build-directory>
117+
The above configuration declares the executable you want to build
118+
(``HelloKokkos``), and links it to Kokkos.
61119

120+
Now you can build and run your Kokkos program.
121+
122+
Start with calling ``cmake`` to configure the project and generate a native
123+
build system:
124+
125+
.. code-block:: sh
126+
127+
MyProject> cmake -B build
128+
-- The C compiler identification is GNU 10.2.1
129+
-- The CXX compiler identification is GNU 10.2.1
130+
...
131+
-- Build files have been written to: .../MyProject/build
62132
63-
Building and Linking a Kokkos "Hello World"
64-
-------------------------------------------
65133
66134
.. note::
67135

68-
``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.
136+
If you want to target a NVIDIA GPU, you will need to pass an extra
137+
``-DKokkos_ENABLE_CUDA=ON`` argument to the cmake command above. For an AMD
138+
or an Intel GPU, you would use ``-DKokkos_ENABLE_HIP=ON`` or
139+
``-DKokkos_ENABLE_SYCL=ON`` respectively. For a list of options and variables
140+
available at configuration time, see :doc:`keywords`.
69141

70142

143+
Then invoke that build system to actually compile/link the project:
71144

72145
.. code-block:: sh
73146
74-
git clone https://github.com/kokkos/kokkos.git
75-
cd example/build_cmake_installed
76-
cmake -B <build-directory> -S . -DKokkos_ROOT=<install-directory>
77-
cd <build-directory>
78-
cmake --build .
79-
./example
80-
147+
MyProject> cmake --build build
148+
Scanning dependencies of target ...
149+
...
150+
[100%] Built target HelloKokkos
151+
152+
Finally try to use the newly built ``HelloKokkos``:
153+
154+
.. code-block:: sh
155+
156+
MyProject> cd build
157+
158+
MyProject/build> HelloKokkos
159+
Goodbye World
160+
161+
.. note::
162+
163+
Depending on your shell, the correct syntax may be ``HelloKokkos``,
164+
``./HelloKokkos`` or ``.\HelloKokkos``.
165+
166+
Congratulations! You’ve successfully built and run a test binary using Kokkos.
81167

82168

83-
Getting Help
84-
------------
169+
Getting help
170+
~~~~~~~~~~~~
85171

86-
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.
172+
If you need additional help getting started, please join the `Kokkos Slack
173+
Workspace <https://kokkosteam.slack.com>`_. If you have trouble signing up see the
174+
:ref:`FAQ entry on how to join <join-slack-workspace>`.

0 commit comments

Comments
 (0)