User Documentation of Kokkos Tools TPL Connectors

[vlkale]

This issue aims to lay groundwork on the centralized documentation of Kokkos Tools vendor aTPL connectors, i.e., advanced TPL connectors.

Documentation of aTPLs is different from the documentation for basic Kokkos Tools in-house tooling libraries that are being documented. These are well-established external libaries that are maintained by third parties developing their own connectors. They don't operate on Kokkos project timelines. They do need an centralized/common location to come to for providing users information on how to use their tooling library within the Kokkos ecosystem.

Of immediate importance: ScoreP needs to be part a third-party library subsection in the Wiki, alongside timemory, given its importance of profiling+tracing in HPC. Though it is not in the category of so-called 'sophisticated tools' with intelligent analysis and/or tuning, e.g., Apex, it does provide advanced capabilities needed for tracing from a third-party library. It is also not as heavily used as nvtx-connector. It doesn't need to be in the top-level README.md of Kokkos Tools. At the same time, there are a number of Kokkos users using it.

In time, this documentation could propagate up the Kokkos Tools Wiki and the kokkos.org webpage, perhaps as a blog post or within tools documentation itself.

[vlkale]

I have put the Wiki page for ScoreP here: https://github.com/kokkos/kokkos-tools/wiki/ScoreP

The page contains a starter description of the tool connector and links to pertinent documentation.\

@wrwilliams Are you able to pull and push to this repository to make changes?

We will probably want to integrate scoreP Kokkos Tools library into the Kokkos Tools repository in some form, either as a git submodule or simply redirecting users to download the scoreP Kokkos Tools library from the scoreP GitHub repo.

[wrwilliams]

@wrwilliams Are you able to pull and push to this repository to make changes?

It appears not:

remote: Permission to kokkos/kokkos-tools.wiki.git denied to wrwilliams.
fatal: unable to access 'https://github.com/kokkos/kokkos-tools.wiki.git/': The requested URL returned error: 403

[masterleinad]

You should still be able to open pull requests, though.

[vlkale]

@wrwilliams

Yes, as @masterleinad suggested, you can open a PR to the wiki page for ScoreP here:

https://github.com/kokkos/kokkos-tools/wiki/ScoreP

It will be reviewed and merged once it's there.

It would be useful to get some content on that page in the next month or so if possible. It will help to have a common ground / go-to guide on building and running with ScoreP Kokkos Tool for Kokkos programmers. Let me know if I can help with writing.

See https://github.com/kokkos/kokkos-tools/wiki/Timemory as a reference.

[wrwilliams]

Actually I cannot presently open a PR, as the wiki repo is not accessible to non-collaborators.

https://github.com/kokkos/kokkos-tools.wiki.git leads to the GitHub 404 page for me, and the wiki pages are not visible in the Kokkos-tools repo either here or on my fork.

[vlkale]

Actually I cannot presently open a PR, as the wiki repo is not accessible to non-collaborators.

https://github.com/kokkos/kokkos-tools.wiki.git leads to the GitHub 404 page for me, and the wiki pages are not visible in the Kokkos-tools repo either here or on my fork.

Thanks for bringing this up - this should be fixed, especially given the number of external Kokkos Tools connector libraries like the ScoreP Kokkos Tools connector.

I will look into this and get back to you next week.

@crtrott @dalg24

Does it make sense to create a new Team in the Kokkos project called something like 'Kokkos Tools connector developers'?

[vlkale]

@wrwilliams To follow-up, I don't have an easy solution for the moment on the wiki. However, you do have the ability to create a PR to the Kokkos Tools repo.

Perhaps you can also put documentation in a README.md in a scoreP folder for your specific documentation, similar to what was done for the caliper connector.

I think a non-urgent but important action item that follows from this is for me/us to create a git submodule for the Kokkos Tools ScoreP connector, and also potentially allow building it via a new Spack package for Kokkos Tools that has already been started (just today) here: https://github.com/spack/spack/pull/45382/files .

As for this github issue, I have put up the basic documentation here https://github.com/kokkos/kokkos-tools/wiki/ScoreP and have mentioned documentation for the Kokkos Tools ScoreP connector on your webpage. I will close this github issue.

[dalg24]

What prevents you to create a docs/ directory and document in a markdown file?

[vlkale]

What prevents you to create a docs/ directory and document in a markdown file?

This is a good idea, and it could complement or replace having a README.md file per tool library mentioned above.

The reason for not creating a docs is that I had thought that since the docs folder in Kokkos-core isn't maintained, this isn't a route to go for Kokkos Tools. I see that the kokkos-kernels docs folder is maintained.

I will create a PR in Kokkos Tools with a new folder /docs/ (using the docs folder in Kokkos-kernels as a guideline) - and then create a .md file there for @wrwilliams to edit

A separate but related topic to note: We do need to migrate the Kokkos Tools wiki to either kokkos.github.io/kokkos-core-wiki or create a new subpage kokkos.github.io/kokkos-tools-wiki sometime in the near future, as discussed with @ajpowelsnl. Perhaps we go directly to starting that?