Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README.md: fix build/run instructions #250

Merged
merged 5 commits into from
Apr 25, 2024
Merged

README.md: fix build/run instructions #250

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0b60f3d
README.md: fix build/run instructions
vlkale Apr 16, 2024
3f205dc
README.md: fix install dir, revert unrelated changes
vlkale Apr 18, 2024
7076047
Update README.md
vlkale Apr 18, 2024
fda69f0
Update README.md: remove output file mention
vlkale Apr 18, 2024
2130538
Update README.md
crtrott Apr 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 33 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,45 @@
# Kokkos Tools

Kokkos Tools provide a set of light-weight of profiling and debugging utilities, which interface with instrumentation hooks built directly into the Kokkos runtime. Compared to 3rd party tools these tools can provide much cleaner, context-specific information: in particular, they allow kernel-centric analysis and they use labels provided to Kokkos constructs (kernel launches and views).
Kokkos Tools provide a set of light-weight of profiling and debugging utilities, which interface with instrumentation hooks built directly into the Kokkos runtime. Compared to 3rd party tools, these tools can provide much cleaner, context-specific information: in particular, they allow kernel-centric analysis and they use labels provided to Kokkos constructs (kernel launches and views).

Under most circumstances, the profiling hooks are compiled into Kokkos executables by default assuming that the profiling hooks' version is compatible with the tools' version. No recompilation or changes to your build procedures are required.

Note: `Kokkos` must be configured with `Kokkos_ENABLE_LIBDL=ON` to load profiling hooks dynamically. This is the default for most cases anyway.

## General Usage
# Using Kokkos Tools

To use one of the tools you have to compile it, which will generate a dynamic library. Before executing the Kokkos application you then have to set the environment variable `KOKKOS_TOOLS_LIBS` to point to the dynamic library e.g. in the `bash` shell:
```
export KOKKOS_TOOLS_LIBS=${HOME}/kokkos-tools/src/tools/memory-events/kp_memory_event.so
```
To use one of the tools you have to compile it, which will generate a dynamic library. Before executing the Kokkos application you then have to set the environment variable `KOKKOS_TOOLS_LIBS` to point to the dynamic library. Many of the tools will produce an output file that uses the hostname as well as the process id as part of the filename.

Use the route of either CMake or Makefile to build and run Kokkos Tools. The following provides instructions on both routes.

## Using cmake

### Build

1. create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild`
2. To configure the Type `ccmake .. -DCMAKE_INSTALL_PREFIX=` for any options you would like to enable/disable.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

???

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, thanks - I intended to put here:

'ccmake .. -DCMAKE_INSTALL_PREFIX='${YOUR_KOKKOS_TOOLS_INSTALL_DIR}'

By the way, just doing ccmake .. and not putting the install prefix may still work (by luck) on some platforms/environments, but we ought to highly recommended Kokkos Tools users to not do this. Maybe we can go into that detail in more detailed documentation in a section like "Dos and Don'ts".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not going to get into it because it is outside the scope of the PR but using ccmake isn't exactly the first thing we should showcase. It may be mentioned as a possibly convenient way to discover available options but a plain vanilla build (invoke cmake without any extra option besides installation prefix) will be just right in the vast majority of cases. The ccmake interface will overwhelm beginners and introduce unnecessary cognitive load for new users.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am NOT suggesting you fix it here (please don't) just pointing out this is a poor choice.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it

3. To compile, type `make`
4. To install, type `make install`

### Run

Given your installed tool shared library `lib<name_of_tool_shared_lib>.so` and an application executable called yourApplication.exe, type:

`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}/lib<name_of_tool_shared_lib>.so; ./yourApplication.exe`


## Using make

### Build

To build some library `<name_of_tool_shared_lib>` with make, simply type `make` within that library's subdirectory `${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}` of Kokkos Tools. This generate the shared library within that subdirectory.

### Run

Given your installed tool shared library `<name_of_tool_shared_lib>.so` and an application executable called yourApplication.exe, type:

`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}/<name_of_tool_shared_lib>.so; ./yourApplication.exe`

Many of the tools will produce an output file that uses the hostname as well as the process id as part of the filename.

## Explicit Instrumentation

Expand Down Expand Up @@ -88,30 +114,6 @@ The following provides an overview of the tools available in the set of Kokkos T
accumulate statistics, and utilize various portable function calls for common needs w.r.t. timers,
resource usage, etc.

# Building Kokkos Tools

Use either CMake or Makefile to build Kokkos Tools.

## Using cmake

1. create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild`
2. To configure the Type `ccmake ..` for any options you would like to enable/disable.
3. To compile, type `make`
4. To install, type `make install`

## Using make

To build with make, simply type `make` within each subdirectory of Kokkos Tools.


Building using `make` is currently recommended. Eventually, the preferred method of building will be `cmake`.

# Running a Kokkos-based Application with a tool

Given your tool shared library `<name_of_tool_shared_library>.so` (which contains kokkos profiling callback functions) and an application executable called yourApplication.exe, type:

`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_DIR}/<name_of_tool_shared_lib>; ./yourApplication.exe`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For those who also wondered what changed:

--- before
+++ after
@@ -1,19 +1,27 @@
-## Using cmake
+## Using cmake

+### Build
+
 1. create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild`
-2. To configure the Type `ccmake ..`  for any options you would like to enable/disable.
+2. To configure the Type `ccmake .. -DCMAKE_INSTALL_PREFIX=`  for any options you would like to enable/disable.
 3. To compile, type `make`
 4. To install, type `make install`

-## Using make
+### Run

-To build with make, simply type `make` within each subdirectory of Kokkos Tools.
+Given your installed tool shared library `lib<name_of_tool_shared_lib>.so` and an application executable called yourApplication.exe, type:

+`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}/lib<name_of_tool_shared_lib>.so; ./yourApplication.exe`

-Building using `make` is currently recommended. Eventually, the preferred method of building will be `cmake`.

-# Running a Kokkos-based Application with a tool
+## Using make

-Given your tool shared library `<name_of_tool_shared_library>.so` (which contains kokkos profiling callback functions) and an application executable called yourApplication.exe, type:
+### Build

-`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_DIR}/<name_of_tool_shared_lib>; ./yourApplication.exe`
+To build some library `<name_of_tool_shared_lib>` with make, simply type `make` within that library's subdirectory `${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}` of Kokkos Tools. This generate the shared library within that subdirectory.
+
+### Run
+
+Given your installed tool shared library `<name_of_tool_shared_lib>.so` and an application executable called yourApplication.exe, type:
+
+`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}/<name_of_tool_shared_lib>.so; ./yourApplication.exe`

When you make changes and craft commits, please think about the audit-ability to help reviewers.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't add trailing whitespaces (after the cmake header for instance)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, got it and thanks.

I will see if I can make the changes clean.

# Tutorial

A tutorial on Kokkos Tools can be found here: https://github.com/kokkos/kokkos-tutorials/blob/main/LectureSeries/KokkosTutorial_07_Tools.pdf
Expand Down
Loading