FetchContent's GoogleTest example causes confusion

Development
1

FetchContent’s documentation uses this snippet (and variations of it) frequently:

  FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG        703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
  )

It’s surprising that the content name is “googletest” instead of “GTest”. The latter would transparently make it work with FETCHCONTENT_TRY_FIND_PACKAGE_MODE.

Further complicating matters, the version of GoogleTest referenced (1.10.0) has a bug that breaks using “GTest” as the content name. It’s since been fixed.

A lot of people will copy/paste documentation and use it in their projects and it is unfortunate that doing so in this case may inadvertently break expectations of FETCHCONTENT_TRY_FIND_PACKAGE_MODE for GTest. We ran into this in the Beman project and it sucked a lot of developer time.

I see three options for moving forward:

  1. Do nothing. People will continue to run into this problem.
  2. Bump the googletest version used in the example. This is low risk and people won’t hit the issue we did when they try to change the content name to GTest. People still may be surprised when FETCHCONTENT_TRY_FIND_PACKAGE_MODE doesn’t work out of the box.
  3. Change all the examples (aside from the one illustrating FIND_PACKAGE_ARGS NAMES) to use GTest as the content name. Newer code will work with FETCHCONTENT_TRY_FIND_PACKAGE_MODE. The drawback is that there may be an issue when people mix old copy/pasted code with new copy/pasted code and end up with both GTest and googletest as content names.

Any suggestions on how to proceed?

2 
# Set up googletest
include(FetchContent)
FetchContent_Declare(
    googletest
    GIT_TAG v1.16.0
    GIT_REPOSITORY https://github.com/google/googletest.git
    FIND_PACKAGE_ARGS 1.16.0 NAMES GTest COMPONENTS gmain_main
    EXCLUDE_FROM_ALL
    SYSTEM
)

# For Windows: Prevent overriding the parent project's compiler/linker settings
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(googletest)

# Create example test
file(
    WRITE
    ${CMAKE_BINARY_DIR}/gtest-tidy-mwe.cpp
    "#include <gtest/gtest.h>\n"
    "TEST(HelloTest, BasicAssertions) {\n"
    "  EXPECT_EQ(7 * 6, 42);\n"
    "}\n"
)

add_executable(gtest-tidy-mwe ${CMAKE_BINARY_DIR}/gtest-tidy-mwe.cpp)
target_link_libraries(gtest-tidy-mwe PUBLIC GTest::gtest_main)

NOTE: find_package needs a VERSION and the right NAMES, git clone a GIT_TAG!

Do not set FETCHCONTENT_TRY_FIND_PACKAGE_MODE in project code.

see too manual pages

P.S: Do not use deprecated or old versions.

3

The official name of that project is in fact googletest, not gtest (the top level CMakeLists.txt in the GitHub project actually uses project(googletest-distribution), and the GitHub repo name is also googletest). It is unfortunate that CMake’s own previous Find module used FindGTest rather than Findgoogletest as its name. The googletest project is also inconsistent with what name it uses for itself, using googletest, gtest, and GTest in different places. There’s also the complication of googlemock/gmock, which is also contained in the same repository.

  1. Change all the examples (aside from the one illustrating FIND_PACKAGE_ARGS NAMES) to use GTest as the content name.

I’d be willing to consider a merge request that made this change. As you hinted at, it would be important to also update the whole “Integrating With find_package()” example, not just the one code block mentioning FIND_PACKAGE_ARGS. One of the goals of that section is to highlight how to handle dependencies that have more than one commonly used name. There are also a couple of similar example code blocks in the Using Dependencies Guide in the Downloading And Building From Source With FetchContent and FetchContent And find_package() Integration sections that should be updated for consistency.

You’d also need to check that after making such changes, there’s still some examples showing use of FIND_PACKAGE_ARGS with some non-empty args after that keyword. The googletest example is so far providing that precisely because of the historical naming mess. You are proposing to clean that up, so you’d have to find some other example that demonstrates that capability and update places where that’s needed.

1 Like
4

The naming problem is historical. gtest, and gmock were two separate projects (where gmock depended on gtest), but Google decided to make googletest out of those two. CMake find module’s name is older than this merge.

So yeah, there’s some mess involved :stuck_out_tongue_winking_eye: