In all the answers to this question, there is a whole lot of "how" (to get what you want), and precious little "why" (digging into the problem that motivated the question and what the asker may have misunderstood about the ways in which different types of tools like IDEs and build tools do / do not interact and share information with each other, and what information CMake passes / needs to pass to those tools).
This question is vexing, as it is motivated by a specific behaviour of a specific IDE- Code::Blocks) and CMake, but then poses a question unrelated to that IDE and instead about Makefiles and CMake, assuming that they have done something wrong with CMake which led to a problem with Makefiles, which led to a problem with their IDE.
TL;DR CMake and Makefiles have their own way of tracking header dependencies given include directories and source files. How CMake configures the Code::Blocks IDE is a completely separate story.
What is an "external" header in CMake? (no such thing)
I realized recently that the issue seemed to be that CMake considered those header files to be external to the project. [...]
It therefore seems to me that CMake consider those headers to be external to the project, and does not track them in the depends
As far as I know, there is no official or useful definition of "external header" when it comes to CMake. I have not seen that phrase used in documentation. Also note that the word "project" is a quite overloaded term. Each buildsystem generated by CMake consists of one top-level project, possibly including other external or subdirectory projects. Each project can contain multiple targets (libraries, executables, etc.). What CMake refers to as a target sometimes translates to what IDEs call projects (Ix. Visual Studio, and possibly Code::Blocks). If you had to given such a phrase a meaning, here's what would make sense to me:
In the case that the question is referring to some IDEs' sense of the word "project", which CMake calls "targets", header files are external to a project would be those that aren't intended to be accessed through any of the include directories of a target (Ex. Include directories that come from targets linked to the target in question).
In the case that the question is referring to CMake's sense of the word "project": Targets are either part of a project (defined/created by a call to the project()
command, and built by the generated buildsystem), or IMPORTED
, (not built by the generated buildsystem and expected to already exist, or built by some custom step added to the generated buildsystem, such as via ExternalProject_Add
). Include directories of IMPORTED
targets would be those headers which are external to the CMake project in question, and include directories of non-IMPORTED
targets would be those that are "part of" the project.
Does CMake track header dependencies? (It depends!)
[...] CMake consider those headers to be external to the project, and does not track them in the depends
I'm not super familiar with the history of CMake, or with header dependency tracking in build tooling, but here is what I've gathered from the searching I have done on the topic.
CMake itself doesn't have much to do with any information related to header/include dependencies of implmentation files / translation units. The only way in which that information is important to CMake is if CMake needs to be the one to tell the generated buildsystem what those dependencies are. It's the generated buildsystem which wants to track changes in header file dependencies to avoid any unnecessary recompilation. For the Unix Makefiles generator in particular, before CMake 3.20, CMake would do the job of scanning header/include dependencies to tell the Makefiles buildsystem about those dependencies. Since v3.20, where supported by the compiler, CMake delegates that responsibility to the compiler by default. See the option which can be used to revert that behaviour here.
The exact details of how header/include dependency scanning differs for each supported CMake generator. For example, you can find some high-level description about the Ninja capabilities/approach on their manual. Since this question is only about Makefiles, I won't attempt to go into detail about other generators.
Notice how to get the header/include dependency information for the buildsystem, you only need to give CMake a list of a target's include directories, and a list of the implementation source files to compile? You don't need to give it a list of header files because that information can be scanned for (either by CMake or by a compiler).
Do IDEs get information about target headers by scanning? (they could)
Each IDE can display information in whatever way it wants. Problems like you are having with the IDE not showing headers usually only happen for IDE display formats of the project layout other than the filesystem layout (project headers files are usually in the same project directory as implementation files). For example, such non-filesystem layout views are available in Visual Studio and Code::Blocks.
Each IDE can get header information in whatever way it chooses. As far as I am aware (but I may be wrong for Visual Studio), both Visual Studio and Code::Blocks expect the list of project headers to be explicitly listed in the IDE project configuration files. There are other possible approaches (Ex. header dependency scanning), but it seems that many IDEs choose the explicit list approach. My guess would be because it is simple implementation-wise.
Why would scanning be burdensome for an IDE to find header files associated with a target?(Note: this is somewhat speculation, since I am not a maintainer of any such tools and have only used a couple of them) An IDE could implement the file scanning (which itself is a complicated task), but to know which headers are "in" the target, they'd either need to get information from the buildsystem about how the translation units of the target will get compiled, and that's assuming that all "not-in-target" header include paths are specified with a "system"-like flag, which doesn't have to be the case. Or, it could try to get that information from the meta-buildsystem, which here is CMake. Or it could try to do what CMake now does and try to invoke the selected compiler to scan dependencies. But in either case, they'd have to make some difficult decision about which buildsystems, meta buildsystems, and/or compilers to support, and then do the difficult work of extracting that information from whatever formats those tools store that information in, possibly without any guarantees that those formats will be the same in future tool versions (supporting a change in the format in a newer tool version could be similar to having to supporting a completely separate tool). The IDE could do all that work, or it could just ask you to give it a list of the headers belonging to each target. As you can see, there are cons to the diversity in tooling that the C/C++ ecosystem has. There are pros too, but that's outside the scope of this question.
On the bright side, CMake actually does have a mechanism to try to take some of that work off your shoulders. For such IDEs that have non-filesystem-views, it does implement a simple-heuristic to try to find header files that are associated with source files...
How does header file discovery work for the Code::Blocks IDE generator for CMake?
At least, when generating a Code::Blocks project the header files do not appear within the project (the source files do).
Here's something interesting: The Code::Blocks editor has the concept of source files and header files that are part of a project, and since CMake doesn't expect/require its users to tell it about each and every header file in the project (it only needs to know about what include directories should be associated with targets), it tries to use a certain heuristic to discover header files that are associated to implementation files. That heuristic is very basic: take the path of each source file in a project, and try changing the extenstion to be like one that is usually given to header files, and see if any such file exists. See the cmExtraCodeBlocksGenerator::CreateNewProjectFile
member function in :/Source/cmExtraCodeBlocksGenerator.cxx
.
In "Pitchfork Layout" terminology, it would be said that the heuristic assumes that the project uses "merged-header" placement instead of "split-header" placement, where there are separate src/
and include/
directories. So if you don't use merged-header layout, or otherwise have any target headers that don't meet that heuristic, such as utility header files, you'll need to explicitly tell CMake about those files (Ex. using target_sources
) for it to pass that knowledge on to the IDE config it generates.
Further readings:
Closing Words
I'm certain there are many people who know these tools better than I do. If you are one of those people and notice that I have made a mistake, please graciously correct me in the comments or in chat, or just to edit this post.
Note that while installation of build artifacts is an important part of many projects' lifecycles and is therefore incorporated into the designs of most C/C++ buildsystems, since the question didn't explicitly ask about the configuring the installation part, I have chosen to leave it out of this answer, since it in itself is not a trivial topic to cover (just see how long the related chapters in the "Mastering CMake" book are: The chapter on installation, and the chapter on importing and exporting).
.cbp
project file. Now if the cmake dependency scanner fails to correctly identify a header file as a dependency for a Makefile there are ways to fix that but in some cases it will get it wrong because it doesn't include a full preprocessor.