Trompeloeil should work with CMake FetchContent

[kevinchannon]

FetchContent is a simple and effective way to manage dependencies in a CMake-based project and it would be great if Trompeloeil worked well with it.

Adding the following to a project's CMakeLists.txt should allow a user to use Trompeloeil:

FetchContent_Declare(
  trompeloeil
  GIT_REPOSITORY https://github.com/rollbear/trompeloeil.git
  GIT_TAG        v43
)

FetchContent_MakeAvailable(trompeloeil)

Currently, the include path is not correctly set, so additional work is required to use Trompeloiel in this way. I added this to my project:

target_include_directories(<my target name> PRIVATE "${CMAKE_BINARY_DIR}/_deps/trompeloeil-src/include" )

[Leon0402]

Haven't actually tried it out with a more recent version, but used to work without any problems (v39), so it might be a regression.

You are right that it should work out of the box. But in case of a regression, you can at least use:

target_include_directories(<my target name> PRIVATE "${trompeloeil_SOURCE_DIR}/include")

to make it a little bit less ugly :)

[rollbear]

Can you explain what you are seeing?

I've tried this as a dummy project, and it works fine.

CMakeLists.txt

cmake_minimum_required(VERSION 3.11)
project(tst)
include(FetchContent)
FetchContent_Declare(
  trompeloeil
  GIT_REPOSITORY https://github.com/rollbear/trompeloeil.git
  GIT_TAG v43)

FetchContent_MakeAvailable(trompeloeil)

add_executable(
  test
  test.cpp
)

test.cpp

#include <trompeloeil.hpp>

int main()
{
}

[rollbear]

OK, never mind, I can reproduce now. Looking into it.

[rollbear]

No, actually, I can't reproduce. If I add:

target_link_libraries(
  test
  PUBLIC
  trompeloeil::trompeloeil
)

to CMakeLists.txt above, it works.

I have the sources in /tmp/1, and run cmake and make. I add -DCMAKE_VERBOSE_MAKEFILE=yes to get visibility into the process:

bjorn@protopteryx /t/2> cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_VERBOSE_MAKEFILE=yes /tmp/1
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done
-- Generating done
-- Build files have been written to: /tmp/2
bjorn@protopteryx /t/2> make
/usr/bin/cmake -S/tmp/1 -B/tmp/2 --check-build-system CMakeFiles/Makefile.cmake 0
/usr/bin/cmake -E cmake_progress_start /tmp/2/CMakeFiles /tmp/2//CMakeFiles/progress.marks
make  -f CMakeFiles/Makefile2 all
make[1]: Entering directory '/tmp/2'
make  -f CMakeFiles/test.dir/build.make CMakeFiles/test.dir/depend
make[2]: Entering directory '/tmp/2'
cd /tmp/2 && /usr/bin/cmake -E cmake_depends "Unix Makefiles" /tmp/1 /tmp/1 /tmp/2 /tmp/2 /tmp/2/CMakeFiles/test.dir/DependInfo.cmake --color=
make[2]: Leaving directory '/tmp/2'
make  -f CMakeFiles/test.dir/build.make CMakeFiles/test.dir/build
make[2]: Entering directory '/tmp/2'
[ 50%] Building CXX object CMakeFiles/test.dir/test.cpp.o
/usr/bin/c++  -I/tmp/2/_deps/trompeloeil-src/include -g -MD -MT CMakeFiles/test.dir/test.cpp.o -MF CMakeFiles/test.dir/test.cpp.o.d -o CMakeFiles/test.dir/test.cpp.o -c /tmp/1/test.cpp
[100%] Linking CXX executable test
/usr/bin/cmake -E cmake_link_script CMakeFiles/test.dir/link.txt --verbose=1
/usr/bin/c++ -g CMakeFiles/test.dir/test.cpp.o -o test 
make[2]: Leaving directory '/tmp/2'
[100%] Built target test
make[1]: Leaving directory '/tmp/2'
/usr/bin/cmake -E cmake_progress_start /tmp/2/CMakeFiles 0

It builds it fine with the right include path.

What are the steps you do, and what are the observations?

[kevinchannon]

Ah, I see. I didn't have anything in the target_link_libraries call. Trompeloeil is header-only library, so I had assumed the linker didn't need to care about it. Seems strange that FetchContent doesn't add it to the include paths unless you tell the linker about it, right? Maybe I don't understand CMake/compilers/linkers well enough!

EDIT: Just to confirm, if I add the link libraries bit, things work fine.

[Leon0402]

Well the target_link_libraries is actually not (only) about linking C++ libraries. So you can link C++ libraries like mylib.a or something like this, but it is highly discouraged. Instead, CMake works with targets, which is a form of abstraction. Cmake targets can be anything like classic C++ Libraries, Exectuables, Header Only libraries, .... Think of it like metadata. It contains information about source files (cpp & h), compiler flags, compiler definitions, include paths, dependencies, ... In modern Cmake all of these settings are associated to a target as either PRIVATE, INTERFACE or PUBLIC. Private means the setting is just for the target itself (for instance the cpp files), INTERFACE means the setting is just for targets dependencing on this target (For instance the include path in a header only library), PUBLIC applies for the target itself and the dependent targets (for instance the include path is a non header only library). So the important thing is that targets can with PUBLIC / INTERFACE kind of inherit information to other targets.

So target_link_libraries should not be used to link a raw C++ library to a cmake target, but actually to link a cmake target to another target. This leads to this "interhitance" of the properties.

As an example take the trompeloeil::trompeloeil target. It it header only as you said, but still there is a cmake target defined. This target is of type "INTERFACE Library". So it specified option which will only be inherited to other options. For instance the target might specify an include path as INTERFACE. If you do target_link_libraries(test PUBLIC trompeloeil::trompeloeil) the interface include path of the trompeloeil target is inherited to the test target.

The real power of all this is when it comed to dependencies of dependencies. For instance trompeloeil could link against the boost target (in case it would need that) and then you test target would also receive all information about boost. No need to specify anything yourself. In theory you should never need much more than just the line to find the target (find_package or FetchContent) and the linking against the target. Unfortunatly many libraries don't use modern cmake, so at the moment you probably will experience that it is not as easy as that. Best thing you can do in such a case is to report it to maintainers or even better fix it.

I can only recommend you to learn more about targets and how they work. It's really the most crucial concept of cmake and it will help you a lot to master it.

[kevinchannon]

Thanks! An absolutely brilliant explanation.

[rollbear]

Awesome @Leon0402 . Thank you!