From 0b60f3d3138e5889b18d6154bb1cfa5b1cb0d858 Mon Sep 17 00:00:00 2001 From: Vivek Kale <11766050+vlkale@users.noreply.github.com> Date: Tue, 16 Apr 2024 09:39:32 -0700 Subject: [PATCH 1/5] README.md: fix build/run instructions Fix build and run instructions, put information at the top. --- README.md | 64 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 1d54302ba..929b0b305 100644 --- a/README.md +++ b/README.md @@ -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. +3. To compile, type `make` +4. To install, type `make install` + +### Run + +Given your installed tool shared library `lib.so` and an application executable called yourApplication.exe, type: + +`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}/lib.so; ./yourApplication.exe` + + +## Using make + +### Build + +To build some library `` 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 `.so` and an application executable called yourApplication.exe, type: + +`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}/.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 @@ -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 `.so` (which contains kokkos profiling callback functions) and an application executable called yourApplication.exe, type: - -`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_DIR}/; ./yourApplication.exe` - # Tutorial A tutorial on Kokkos Tools can be found here: https://github.com/kokkos/kokkos-tutorials/blob/main/LectureSeries/KokkosTutorial_07_Tools.pdf From 3f205dc05328a02bd733f24157437321caf8e4e6 Mon Sep 17 00:00:00 2001 From: Vivek Kale <11766050+vlkale@users.noreply.github.com> Date: Wed, 17 Apr 2024 19:58:08 -0700 Subject: [PATCH 2/5] README.md: fix install dir, revert unrelated changes --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 929b0b305..4eab3f4a0 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # 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. -# Using Kokkos Tools +## 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. Many of the tools will produce an output file that uses the hostname as well as the process id as part of the filename. @@ -16,8 +16,8 @@ Use the route of either CMake or Makefile to build and run Kokkos Tools. The fol ### 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. +1. Create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild` +2. To configure, type `ccmake .. -DCMAKE_INSTALL_PREFIX=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}` for any options you would like to enable/disable. 3. To compile, type `make` 4. To install, type `make install` @@ -25,20 +25,20 @@ Use the route of either CMake or Makefile to build and run Kokkos Tools. The fol Given your installed tool shared library `lib.so` and an application executable called yourApplication.exe, type: -`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}/lib.so; ./yourApplication.exe` +`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}/lib.so; ./yourApplication.exe` ## Using make -### Build +### Build -To build some library `` 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. +To build some library `` 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 `.so` and an application executable called yourApplication.exe, type: +Given your installed tool shared library `.so` and an application executable called `yourApplication.exe`, type: -`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}/.so; ./yourApplication.exe` +`export KOKKOS_TOOLS_LIBS=${YOUR_KOKKOS_TOOLS_LIB_SRC_DIR}/.so; ./yourApplication.exe` ## Explicit Instrumentation From 7076047ec5e845829077511e8fee7424f3a5b0e6 Mon Sep 17 00:00:00 2001 From: Vivek Kale <11766050+vlkale@users.noreply.github.com> Date: Thu, 18 Apr 2024 07:48:41 -0700 Subject: [PATCH 3/5] Update README.md Co-authored-by: Daniel Arndt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4eab3f4a0..a378f6569 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Note: `Kokkos` must be configured with `Kokkos_ENABLE_LIBDL=ON` to load profilin 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. +CMake and Makefiles are supported for building Kokkos Tools. The following provides instructions for both. ## Using cmake From fda69f0b41d575bc50a4a18cff78d3ead672f5c6 Mon Sep 17 00:00:00 2001 From: Vivek Kale <11766050+vlkale@users.noreply.github.com> Date: Thu, 18 Apr 2024 08:04:51 -0700 Subject: [PATCH 4/5] Update README.md: remove output file mention Co-authored-by: Daniel Arndt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a378f6569..edd4cebb9 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ 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. Many of the tools will produce an output file that uses the hostname as well as the process id as part of the filename. +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. From 21305380b115f1af626262176fc5971eb3cdec3e Mon Sep 17 00:00:00 2001 From: Christian Trott Date: Thu, 25 Apr 2024 11:13:45 -0600 Subject: [PATCH 5/5] Update README.md Co-authored-by: Daniel Arndt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index edd4cebb9..44643fc9c 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ CMake and Makefiles are supported for building Kokkos Tools. The following provi ### Build 1. Create a build directory in Kokkos Tools, e.g., type `mkdir myBuild; cd myBuild` -2. To configure, type `ccmake .. -DCMAKE_INSTALL_PREFIX=${YOUR_KOKKOS_TOOLS_INSTALL_DIR}` for any options you would like to enable/disable. +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`