How to integrate Catch2 as external library with CMake?

Question

I am trying to set up a learning project using Catch2 and I decided that it was best to clone the repository in a Cpp folder, so I could get updates and use it for other C++ projects. The installing method is as described here.

The basic folder structure is:

Cpp
├───TestProject
│   ├───main.cpp
│   ├───.vscode
│   └───build
│       ├───CMakeFiles
│       └───Testing
└───Catch2
   ├─── ...
  ...

As per Catch2 documentation I put this on my CMake file:

find_package(Catch2 REQUIRED)
target_link_libraries(tests Catch2::Catch2)

However, when I try to configure the project in VS Code, I get the following error message:

[cmake] CMake Error at CMakeLists.txt:5 (target_link_libraries):
[cmake]   Cannot specify link libraries for target "tests" which is not built by this
[cmake]   project.

main.cpp is just a Hello World file and the complete CMakeLists.txt file contents are:

cmake_minimum_required(VERSION 3.0.0)
project(TestProject VERSION 0.1.0)

find_package(Catch2 REQUIRED)
target_link_libraries(tests Catch2::Catch2)
enable_testing()

add_library(TestProject TestProject.cpp)

set(CPACK_PROJECT_NAME ${PROJECT_NAME})
set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})
include(CPack)

I am unsure why this happens. I am a complete newcomer to CMake, save for very basic commands I had to use at work. I guess it would be less work to just drop it as a header file like it's intended to, but this approach made more sense to me...

Note: I have read this SO question. However his question had to do with Catch2 as a header file inside the project.

Note 2: desired behaviour is to build the project using Catch2 as an external library.

(Additional information: CMake --version is 3.13.3, using CMakeTools in VS Code, OS is Windows 10)

Answer 1

First, since the library has been installed through CMake (same applies for installs using a package manager), it is recommended to flag find_package with CONFIG (read about Config mode here). This is because even if Catch2 repository is in a parent, common folder to the project, the CMake installation process installs it in your Program Files folder (in Windows); i.e. the repository is just that.

Additionally you should add_executable(tests main.cpp) so CMake has "tests" as a target. This solves the original problem.

However, for it to completely work, you need to follow these additional steps:

1. Use catch_discover_tests(tests)
2. include(CTest) possibly necessary.
3. The include preprocessor command should be: #include <catch2/catch.hpp> instead of simply #include "catch.hpp".

Also, make sure your editor is aware of the environmental variables created during the installation of Catch2. That is, if you are having problems, restart the editor so it re-reads environmental variables.

Full CMakeLists.txt:

cmake_minimum_required(VERSION 3.5.0)
project(TestProject LANGUAGES CXX VERSION 0.1.0)

find_package(Catch2 REQUIRED)
add_executable(tests main.cpp) # solution to the original problem
target_link_libraries(tests Catch2::Catch2)

include(CTest) # not sure if this is 100% necessary
include(Catch)
catch_discover_tests(tests)
enable_testing()

Note: Instead of add_executable, we should use add_library, although no tests are recognized in library mode for some reason; however that is beyond the scope of this question as it lies more in the knowledge of use pf Catch2.