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 all commits
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
60 changes: 31 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,38 @@ Note: `Kokkos` must be configured with `Kokkos_ENABLE_LIBDL=ON` to load profilin

## General Usage

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.

CMake and Makefiles are supported for building Kokkos Tools. The following provides instructions for both.

## Using cmake

### Build

1. Create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild`
2. To configure, type `cmake .. -DCMAKE_INSTALL_PREFIX=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}`. There are more options but in most cases the defaults are sufficient.
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`
Comment on lines +24 to +28
Copy link
Contributor

Choose a reason for hiding this comment

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

There is no reason to distinguish between Makefiles and CMake for running.

Suggested change
### 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`

Copy link
Contributor Author

Choose a reason for hiding this comment

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

There is a subtle difference. Maybe that should be changed in the build, but that's another PR.

The difference is that Makefiles generate <name_of_tool_shared_lib>.so in the source directory of the tool connector, while the cmake generates a library lib<name_of_tool_shared_lib>.so in the install directory.

Copy link
Contributor

Choose a reason for hiding this comment

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

Homogenizing the library names sounds like worth fixing.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Homogenizing the library names sounds like worth fixing.

I agree with you and thanks for that feedback.

This would be a separate PR and is outside the scope of this PR (if you disagree, let me know).

Note the updated and more specific goal of this PR that I put in the description, so it is clear what needs to be fixed in this PR.



## 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 generates 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