Catch2's docs are installed into my project's directory when using CMake's GNUInstallDirs

[JuliusR]

Description

I am still learning CMake, but the following behavior of Catch2 seems odd to me: If I use CMake's GNUInstallDirs to install a small test project on Debian (GNU/Linux), then Catch2's documentation is installed into a subdirectory of my Project's name:

usr
└── local
    ├── include
    │   └── catch2
    ├── lib
    │   └── cmake
    │       └── Catch2
    └── share
        ├── Catch2
        ├── doc
        │   └── MyCustomProject     <--     Catch2's docs are installed here
        │       ├── assertions.md
        │       ⋮
        │       └── why-catch.md
        └── pkgconfig

Instead, I expect an installation path like this:

usr
└── local
    ├── include
    │   └── catch2
    ├── lib
    │   └── cmake
    │       └── Catch2
    └── share
        ├── Catch2
        ├── doc
        │   └── Catch2     <--     This is what I expect
        │       ├── assertions.md
        │       ⋮
        │       └── why-catch.md
        └── pkgconfig

Steps to reproduce

1. Create a minimal CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)

project(MyCustomProject)

include(GNUInstallDirs)

add_subdirectory(vendor/Catch2)

add_executable(my_setup_test tests/my_setup_test.cpp)
target_link_libraries(my_setup_test Catch2::Catch2)

2. download Catch2 into vendor/:

mkdir vendor && cd vendor && git clone https://github.com/catchorg/Catch2 && cd ..

3. create minimal test in tests/my_setup_test.cpp:

#define CATCH_CONFIG_MAIN
#include <catch2/catch.hpp>

TEST_CASE("Test Setup") {
  REQUIRE(1 + 1 == 2);
}

4. Build and install

CMAKE=cmake

$CMAKE -E make_directory build &&
$CMAKE -E chdir build $CMAKE .. &&
$CMAKE --build build -- -j8 &&
$CMAKE --build build --target install -- DESTDIR=..

5. View the installed directory structure:

tree usr

Extra information

• Catch version: v2.3.0
• Operating System: Debian (GNU/Linux) testing
• Compiler+version: g++ (Debian 8.2.0-4) 8.2.0
• cmake version 3.12.1

[JuliusR]

I could follow Catch2's CMakeLists.txt to understand why this behavior is like I observed:

• L9: set the PROJECT_NAME with the help of the project command (CMake doc)
• L14: include GNUInstallDirs; this sets CMAKE_INSTALL_DOCDIR to share/doc/${PROJECT_NAME} only if this is the first include(GNUInstallDirs) command
• L138: use install command for the docs/ directory with the destination ${CMAKE_INSTALL_DOCDIR}

My problem is caused by including GNUInstallDirs in the CMakeLists.txt of my project before using add_subdirectory(vendor/Catch2). By this, the CMAKE_INSTALL_DOCDIR is set according to my project's PROJECT_NAME.

I see three possible solutions:

1. not including GNUInstallDirs before using Catch2 as a subdirectory
2. filing bug report for GNUInstallDirs because it should update CMAKE_INSTALL_DOCDIR for new subprojects
3. change Catch2's CMakeLists.txt to not rely on GNUInstallDirs' CMAKE_INSTALL_DOCDIR, but install docs/ to "${DATAROOTDIR}/doc/${PROJECT_NAME}"; this means changing L138 to

# Install documentation
if(CATCH_INSTALL_DOCS)
  install(
    DIRECTORY
      docs/
    DESTINATION
      "${CMAKE_INSTALL_DATAROOTDIR}/doc/${PROJECT_NAME}"
  )
endif()

[horenmar]

I've had some discussion about this off-site and I think the actual answer is to not provide install steps when Catch is being used as a subproject of a different project.