What is the difference between include_directories and target_include_directories in CMake?

Question

I have a directory structure for my C++ code which goes like this :

|
|->include
|->src

I am writing a CMakeLists.txt file for my code. I want to understand the difference between include_directories and target_include_directories in CMake.

What is the difference between their usage and in order to add my include file path which one should I be using?

Infraction

There is no clarity in the documentation. I read it and surmised what Angew has written in his answer, but there are no descriptions, no examples and for a system that is meant for project building, there are no project based examples in CMake documentation. Had there been a good and exhaustive documentation of CMake, I would not have been burdening the community with these questions. – Infraction

Concepts of cmake is poorly documented. Particularly target and “untargeted”. – Backcourt

Agree that CMake documentation is bad, how much effort do they save to not provide examples? When I was new to CMake I was often confused with old/new syntaxes. – Cheju

30 years of coding experience has taught me that undocumented software is as good as non-existent software and poorly documented software is worse than code that doesn't even compile. As such I think this question should be treated like a bug report. – Keitt

Answer 1

include_directories(x/y) affects directory scope. All targets in this CMakeList, as well as those in all subdirectories added after the point of its call, will have the path x/y added to their include path.

target_include_directories(t x/y) has target scope—it adds x/y to the include path for target t.

You want the former one if all of your targets use the include directories in question. You want the latter one if the path is specific to a target, or if you want finer control of the path's visibility. The latter comes from the fact that target_include_directories() supports the PRIVATE, PUBLIC, and INTERFACE qualifiers.

Bristling

I think the latter one should generally be preferred (as long as one is using cmake 3). It has the added benefit of putting x/y in the include path of any dependent targets that use t in their target_link_libraries commands. Of course there is a place for the former, but I believe the latter is generally better. – Compression

The original answer stated that only targets and subdirs added after include_directories will be affected. I'm editing the answer: the documentation clearly states that all targets in the current CMakeLists are affected. The documentation does not mention but only subdirs after the call are affected (as was correctly stated in the original answer) – Cupule

@Phil, target_include_directories has been introduced in CMake 2.8.11 (May 2013) – Cupule

@Cupule Thanks for bringing this to my attention, fixed. I was quite convinced it was a "from now on" thing. – Bristling

I should Greasemonkey your answer onto the official documentation for include_directories, concise and clear, thank you! So then target_include_directories is a carpenter's hammer and include_directories is a sledge hammer. – Keitt

so can we say that include_directories will need more compile time than target_include_directories since every library will need to search the directories in include_directories ? – Rexer

100x clearer than the docs. as of July 2022 they never mention "include path" anywhere and all I needed was these two little words put next to each other – Depreciable

Anyone know how to print out the directories stored by target_include_directories? I tried the code provided here, and the result is always empty: #6902649 – Hortenciahortensa

@Hortenciahortensa You need to retrieve the property INCLUDE_DIRECTORIES of the target. The question you're linking to retrieves the property of the directory. – Bristling

@AngewisnolongerproudofSO Thanks! I did realize that at some point and got it working. – Hortenciahortensa

Answer 2

Besides what Angew's answer correctly says, another very important difference between include_directories and target_include_directories is that, when used with PUBLIC or INTERFACE, the latter populates the INTERFACE_INCLUDE_DIRECTORIES property of the target. This property is useful when another target uses target_link_libraries to link to the original target, as the linking target will have automatically those include directories added. See example.

This important feature is pretty well hidden in the documentation: target_include_directories mention populating INTERFACE_INCLUDE_DIRECTORIES, whose documentation says:

When target dependencies are specified using target_link_libraries(), CMake will read this property from all target dependencies to determine the build properties of the consumer.

Sheet

This is the first time I ever read an understandable explanation of the PUBLIC etc. properties! Thanks :D – Th

Removing the ambiguity: when you use PUBLIC or INTERFACE with target_include_directories, the property INTERFACE_INCLUDE_DIRECTORIES is filled with the include directories required to compile against the headers for the target. – Dylandylana

Check here if you want know more about the meaning of the keywords PRIVATE, PUBLIC and INTERFACE using target_include_directories – Dylandylana

Answer 3

As @Angew said, the very difference is :

1. include_directories() is accessible for all the files in the source-tree
2. target_include_directories() is-only accessible for a specific target when compile.

Carchemish