Canonical way to #include pystring.h

[dg0yt]

Today I stumbled over vcpkg's wiring between pystring and OpenColorIO. I didn't find documentation:
What is the canonical way to include pystring.h?

a) #include <pystring.h>

• found in OpenColorIO
• could work with installations in include (global) or in include/pystring (isolated).
• could easily be covered by a uniform CMake target (pystring::pystring) for installed or sub-project usage.

b) #include <pystring/pystring.h>

• found in https://github.com/imageworks/KatanaUsdPlugins.
• found in cmake config installed by vcpkg port.
• depends on header being in pystring subdir.
  • not so e.g. in Debian, https://packages.debian.org/sid/amd64/libpystring-dev/filelist
  • not so in this repo (repo name left aside), preventing a uniform CMake target for installed or sub-project usage (unless changing this repo's layout).

[grdanny]

I think I would say that your B is the canonical way.
Historically the pystring project did not have a CMake build system and I think the projects that you are seeing that are doing it the A way are from that era.

But once we added the CMakeLists.txt it explicitly says:

install (FILES pystring.h
DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}
COMPONENT developer
)

So that kind of enshrines it to be as B with that pystring subdirectory.

[lgritz]

I think our expectations of these open source projects has evolved over the years, too, and these days we greatly prefer that each project keep their headers in a separate subdirectory rather than just making a huge pile of everything all directly in the top level include.

[dg0yt]

This issue is not about whether pystring.h should go to ${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}. This is given at this point.

The question is whether the required interface include directory is

${CMAKE_INSTALL_INCLUDEDIR}

or

${CMAKE_INSTALL_INCLUDEDIR}/${PROJECT_NAME}

(And this isn't really related to cmake.)

[grdanny]

I think the recommendation is to use the second notation.
That's what we use in all of our internal projects that use this library.
(Though you were right to point out the open color io and others use the first notation).