Using File Sets

In the last lesson, we built a developer utility: a custom format target that automatically runs clang-format on our code. However, it has a flaw.

We collected the source files using get_target_property(... SOURCES), but this property only knows about the .cpp files we passed to add_library() or add_executable(). Our format target is completely unaware of our header files.

To solve this, we need a way for a target to formally declare all of its constituent files, including its public and private headers. This is the job of file sets.

So far, we've been quite loose around how we handle header files. None of our CMake files list which headers our project has. We listed the directory where the header files are, but nowhere do we list the exact files associated with our target

1cmake_minimum_required(VERSION 3.16)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6# We just specify a directory
7target_include_directories(GreeterLib PUBLIC
8  "${CMAKE_CURRENT_SOURCE_DIR}/include"
9)

CMake is effectively unaware that Greeter.h exists. In larger projects, being explicit about what files are in our project and what CMake is responsible for managing is often preferred. Having a complete list of files would be useful for many build tasks (like our format target) and also prevents us from accidentally installing or packaging files we didn't intend.

Version 3.23 of CMake introduced the file sets feature to help with creating and managing these lists of files.

Let's replace our target_include_directories() to use this new file set technique via target_sources(). This command allows us to add files to a target after it has been created. It also lets us associate these files with a named file set.

1cmake_minimum_required(VERSION 3.23) 
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_include_directories(GreeterLib PUBLIC
7  "${CMAKE_CURRENT_SOURCE_DIR}/include"
8)
9
10target_sources(GreeterLib
11  PUBLIC
12  FILE_SET HEADERS
13  BASE_DIRS "include/" 
14  FILES "include/greeter/Greeter.h" 
15)

Let's break down this new command:

• target_sources(GreeterLib ...): We are adding sources to the GreeterLib target.
• PUBLIC: This is the same visibility keyword we've seen before, with the other options being INTERFACE or PRIVATE. A PUBLIC file set means the files and their associated properties are needed by both GreeterLib itself and by any consumer that links to it.
• FILE_SET HEADERS: This declares that we are creating a file set named HEADERS. This name, in conjunction with the PUBLIC argument, helps CMake understand these files are the target's public headers.
• BASE_DIRS: This specifies the base directories for the file set. This is helpful in a few ways, but the immediate utility is that it lets us remove the target_include_directories() command. We're telling CMake that this directory is where some of our target's public headers are, so any target that links against us will need these BASE_DIRS added to their search paths.
• FILES: This is a list of the actual header files to include in the set.

With this change, GreeterLib now formally declares that Greeter.h is part of its public interface.

Multiple Files

If we had more header files, we would add them to our command, and can introduce white space to help with formatting if preferred:

1target_sources(GreeterLib
2  PUBLIC
3  FILE_SET HEADERS#
4  BASE_DIRS "include/"
5  FILES
6    "include/greeter/Greeter.h"
7    "include/greeter/AnotherFile.h"
8    "include/greeter/AndAnother.h"
9)

Now that a target knows about its headers, how do we get that information back out? We can use get_target_property() just like we did for sources. The default set of headers we provided above is available as the HEADER_SET property:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8  FILE_SET HEADERS
9  BASE_DIRS "include/"
10  FILES "include/greeter/Greeter.h"
11)
12
13get_target_property(HeaderList GreeterLib HEADER_SET)
14message(STATUS "GreeterLib headers: ${HeaderList}")

1cmake ..

1-- GreeterLib headers: /project/greeter/include/greeter/Greeter.h

Example 1: Using the File Set for Installation

The biggest benefit of explicitly listing all of our header files is that it allows for precise installation. Instead of installing an entire directory, we can tell CMake to install only the files in our set.

In our lesson on creating installation rules we installed our headers simply by copying everything in the /include directory:

1install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/"
2  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
3  FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
4)

This worked, but what if we have some header files in that directory that we don't want to be shared? We can replace the imprecise install(DIRECTORY ...) with an exact installation rule for our file set.

This can be a new install() rule if we prefer, but it is more typically added to the existing rule:

1install(
2  TARGETS GreeterLib
3  EXPORT GreeterLibTargets
4  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
5  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
6  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
7  # This replaces install(DIRECTORY ...)
8  FILE_SET HEADERS DESTINATION
9    ${CMAKE_INSTALL_INCLUDEDIR}
10)

This will install only the PUBLIC and INTERFACE files that we defined as part of our HEADERS file set. It will also automatically handle creating the directory structure (include/greeter) at the destination, based on the BASE_DIRS we specified in target_sources().

A complete version of greeter/CMakeLists.txt with all of its install rules is provided below for reference:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3include(GNUInstallDirs)
4
5add_library(GreeterLib src/Greeter.cpp)
6add_library(Greeter::Lib ALIAS GreeterLib)
7
8set_target_properties(GreeterLib PROPERTIES
9  OUTPUT_NAME Greeter
10  EXPORT_NAME Lib
11)
12
13# This replaces target_include_directories()
14target_sources(GreeterLib 
15  PUBLIC 
16  FILE_SET HEADERS 
17  BASE_DIRS "${PROJECT_SOURCE_DIR}/include" 
18  FILES
19    "${PROJECT_SOURCE_DIR}/include/greeter/Greeter.h" 
20) 
21
22install(
23  TARGETS GreeterLib
24  EXPORT GreeterLibTargets
25  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
26  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
27  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
28  # This replaces install(DIRECTORY ...)
29  FILE_SET HEADERS DESTINATION
30    ${CMAKE_INSTALL_INCLUDEDIR}
31)
32
33install(EXPORT GreeterLibTargets
34  FILE GreeterLibTargets.cmake
35  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib
36  NAMESPACE Greeter::
37)
38
39include(CMakePackageConfigHelpers)
40
41configure_package_config_file(
42  "cmake/GreeterLibConfig.cmake.in"
43  "GreeterLibConfig.cmake"
44  INSTALL_DESTINATION
45  "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
46)
47
48write_basic_package_version_file(
49  "GreeterLibConfigVersion.cmake"
50  VERSION ${PROJECT_VERSION}
51  COMPATIBILITY AnyNewerVersion
52)
53
54install(FILES
55  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfig.cmake"
56  "${CMAKE_CURRENT_BINARY_DIR}/GreeterLibConfigVersion.cmake"
57  DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/GreeterLib"
58)

Example 2: Passing File Sets to clang-format

Let's fix the flaw in our format target from the previous lesson, where it was only formatting source files and not headers. We can fix this by updating our format target with the following changes:

• We'll now append files from both the SOURCES and HEADER_SET properties into our ALL_SOURCES list for formatting. We'll add a current_target_files variable to help with this.
• Our GreeterApp doesn't have any headers so, if get_target_property() returns an empty variable, we'll skip appending it to ALL_SOURCES. We can do this by adding EXISTS checks to ensure we're only adding files that really exist.

Here's the updated logic in our root CMakeLists.txt:

1cmake_minimum_required(VERSION 3.23)
2project(Greeter)
3add_subdirectory(app)
4add_subdirectory(greeter)
5
6find_program(CLANG_FORMAT_EXE clang-format)
7set(FORMAT_TARGETS GreeterLib GreeterApp)
8set(ALL_SOURCES)
9
10foreach(target IN LISTS FORMAT_TARGETS)
11  get_target_property(target_sources ${target} SOURCES)
12  get_target_property(target_headers ${target} HEADER_SET) 
13  get_target_property(target_source_dir ${target} SOURCE_DIR)
14
15  # Combine sources and headers into one list to process
16  set(current_target_files ${target_sources} ${target_headers}) 
17
18  foreach(file IN LISTS current_target_files) 
19    if(IS_ABSOLUTE ${file} AND EXISTS ${file})
20      list(APPEND ALL_SOURCES ${file})
21    elseif(EXISTS ${target_source_dir}/${file})
22      list(APPEND ALL_SOURCES ${target_source_dir}/${file})
23    endif()
24  endforeach()
25endforeach()
26
27if(CLANG_FORMAT_EXE)
28  add_custom_target(format
29    COMMENT "Formatting files with clang-format..."
30    COMMAND ${CLANG_FORMAT_EXE} -i ${ALL_SOURCES}
31  )
32  message(STATUS "Added 'format' target")
33else()
34  message(WARNING
35    "clang-format not found - format target unavailable")
36endif()

Our format target now correctly identifies and formats all .cpp and .h files that are explicitly associated with our targets.

We're currently calling our header file set HEADERS. This is a special name - when CMake sees a file set with this name, it implicitly understands that we're providing header files.

However, eventually, we'll need multiple file sets. A common reason is that we'll have both public headers and private headers, and we need to separate them into different sets. We'll cover this soon soon.

To help with this, we're free to call our file set anything we want - they don't need to be called HEADERS. However, if we're not using HEADERS, we need to provide additional arguments to inform CMake this this file sets is a list of header files.

Below, we rename our file set to public_headers, but we also pass TYPE HEADERS to help CMake understand what this set represents:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8  FILE_SET public_headers
9  TYPE HEADERS
10  BASE_DIRS "include/"
11  FILES "include/greeter/Greeter.h"
12)

The HEADER_SET_<NAME> Property

Now that we're no longer using the default HEADERS name, our header files are not available in the HEADER_SET property. Our set is called public_headers, so the property we now need is called HEADER_SET_public_headers:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8  FILE_SET public_headers
9  TYPE HEADERS
10  BASE_DIRS "include/"
11  FILES "include/greeter/Greeter.h"
12)
13
14get_target_property( 
15  public_headers GreeterLib HEADER_SET_public_headers 
16) 
17message(STATUS "public_headers: ${public_headers}") 
18
19# Install rules...

1cmake ..

1...
2-- public_headers: /project-root/greeter/include/greeter/Greeter.h
3...

Any install() command we're using would also need updated to use this new name:

1install(
2  TARGETS GreeterLib
3  EXPORT GreeterLibTargets
4  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
5  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
6  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
7  FILE_SET HEADERS DESTINATION
8  FILE_SET public_headers DESTINATION
9    ${CMAKE_INSTALL_INCLUDEDIR}
10)

We'll update our format target to support this new name later in the lesson.

So far, we've covered PUBLIC headers, but what about headers that are internal implementation details? We can define a PRIVATE file set for them. These headers will be available for compiling GreeterLib itself, but they won't be exposed to consumers or included in the installation.

Let's add an internal header to our library and update Greeter.cpp to use it:

1#include <string>
2
3namespace InternalDetails {
4  inline const std::string Name{
5    "the modular Greeting Library"
6  };
7}

We'd normally #include this file using a relative path (#include "InternalDetails.h") as it's in the same directory, but let's use chevrons in this contrived example to ensure that CMake is providing the required search path:

1#include <greeter/Greeter.h>
2#include <string>
3#include <InternalDetails.h>
4
5std::string get_greeting() {
6  return "Hello from " + InternalDetails::Name;
7}

We can now update our target_sources() command to include this second file set:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8    FILE_SET public_headers
9    TYPE HEADERS
10    BASE_DIRS "include/"
11    FILES "include/greeter/Greeter.h"
12  PRIVATE
13    FILE_SET private_headers
14    TYPE HEADERS
15    BASE_DIRS "src/" 
16    FILES "src/InternalDetails.h" 
17)
18
19# Install rules...

Because this file set is PRIVATE, GreeterLib can find and compile InternalDetails.h, but consumers like GreeterApp will not have greeter/src added to their search paths.

This perfectly encapsulates our internal implementation detail.

With our earlier introduction of the public_headers and private_headers file sets, our GreeterLib target's headers are now spread across two properties: HEADER_SET_public_headers and HEADER_SET_private_headers.

We can access these properties in the usual way with get_target_properties(). However, the names of these properties are internal implementation details of GreeterLib so, to keep our code clean, we should be reluctant to directly use these names elsewhere in our project.

If GreeterLib adds or renames a file set, external code that uses those file sets shouldn't need to be updated. To help with this, targets have a HEADER_SETS property, which is a list of all of the file sets with TYPE HEADERS associated with that target:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8    FILE_SET public_headers
9    TYPE HEADERS
10    BASE_DIRS "include/"
11    FILES "include/greeter/Greeter.h"
12  PRIVATE
13    FILE_SET private_headers
14    TYPE HEADERS
15    BASE_DIRS "src/" 
16    FILES "src/InternalDetails.h"
17)
18
19get_target_property( 
20  header_sets GreeterLib HEADER_SETS 
21) 
22message(STATUS "header_sets: ${header_sets}") 
23
24# Install rules...

1cmake ..

1...
2-- header_sets: public_headers;private_headers
3...

To get all of the header files associated with a target, we can loop over these HEADER_SETS:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5
6target_sources(GreeterLib
7  PUBLIC
8    FILE_SET public_headers
9    TYPE HEADERS
10    BASE_DIRS "include/"
11    FILES "include/greeter/Greeter.h"
12  PRIVATE
13    FILE_SET private_headers
14    TYPE HEADERS
15    BASE_DIRS "src/"
16    FILES "src/InternalDetails.h"
17)
18
19get_target_property(
20  header_sets GreeterLib HEADER_SETS
21)
22
23foreach(set IN LISTS header_sets)
24  get_target_property(
25    header_files GreeterLib HEADER_SET_${set}
26  )
27  message(STATUS "set: ${set}, files: ${header_files}")
28endforeach()
29
30# Install rules...

1cmake ..

1-- set: public_headers, files: /project-root/greeter/include/greeter/Greeter.h
2-- set: private_headers, files: /project-root/greeter/src/InternalDetails.h

Practical Example: Updating the format Target

Over in our root CMakeLists.txt file, our format target is currently expecting all header files to be provided within the default HEADER_SET - the file set called HEADERS. Header files in any other file set, such as public_headers and private_headers, will not be formatted.

Updating our target to support this new technique of looping over each target's HEADER_SETS might look something like this:

1cmake_minimum_required(VERSION 3.23)
2project(Greeter)
3add_subdirectory(app)
4add_subdirectory(greeter)
5
6find_program(CLANG_FORMAT_EXE clang-format)
7set(FORMAT_TARGETS GreeterLib GreeterApp)
8set(ALL_SOURCES)
9
10foreach(target IN LISTS FORMAT_TARGETS)
11  get_target_property(target_sources ${target} SOURCES)
12  get_target_property(target_headers ${target} HEADER_SET)
13  get_target_property(header_sets ${target} HEADER_SETS)
14  get_target_property(target_source_dir ${target} SOURCE_DIR)
15
16  set(current_target_files ${target_sources} ${target_headers})
17  set(current_target_files ${target_sources})
18  foreach(header_set IN LISTS header_sets)
19    get_target_property(
20      header_set_files ${target} HEADER_SET_${header_set}
21    )
22    list(APPEND current_target_files ${header_set_files})
23  endforeach()
24
25  foreach(file IN LISTS current_target_files)
26    if(IS_ABSOLUTE ${file} AND EXISTS ${file})
27      list(APPEND ALL_SOURCES ${file})
28    elseif(EXISTS ${target_source_dir}/${file})
29      list(APPEND ALL_SOURCES ${target_source_dir}/${file})
30    endif()
31  endforeach()
32endforeach()
33
34if(CLANG_FORMAT_EXE)
35  add_custom_target(format
36    COMMENT "Formatting files with clang-format..."
37    COMMAND ${CLANG_FORMAT_EXE} -i ${ALL_SOURCES}
38  )
39  message(STATUS "Added 'format' target")
40else()
41  message(WARNING
42    "clang-format not found - format target unavailable")
43endif()

Reducing CMakeLists.txt Bloat

Our root CMakeLists.txt file is starting to look very noisy, and almost all of its code is related to setting up this format target.

Remember, we can (and should) introduce functions and .cmake files to keep things organized.

Moving our formatting logic to a new add_clang_format() function defined in a different file might look something like this:

Currently, we're providing a target's source files (.cpp) as arguments to the add_library() or add_executable() commands.

We can also move that list to the target_sources() command, if we prefer. Source files are almost always listed as PRIVATE:

1cmake_minimum_required(VERSION 3.23)
2project(GreeterLib VERSION 1.0.0)
3
4add_library(GreeterLib src/Greeter.cpp)
5add_library(GreeterLib)
6
7target_sources(GreeterLib
8  PRIVATE
9    src/Greeter.cpp
10  PUBLIC
11    FILE_SET public_headers
12    TYPE HEADERS
13    BASE_DIRS "include/"
14    FILES "include/greeter/Greeter.h"
15  PRIVATE
16    FILE_SET private_headers
17    TYPE HEADERS
18    BASE_DIRS "src/"
19    FILES "src/InternalDetails.h"
20)
21
22# Install rules...

File sets are a modern, structured way to manage all the files associated with a target.

• File Sets are Explicit: The file set pattern requires us to be explicit about which headers are associated with a target, rather than just providing a directory where the headers are. This involves slightly more maintenance effort, but has several benefits.
• The target_sources() Command: This is the primary command for adding files to a target and organizing them into PUBLIC or PRIVATE file sets.
• Automated Include Directories: A PUBLIC or INTERFACE file set with BASE_DIRS specified automatically configures the include paths for consumers, replacing target_include_directories().
• Tooling Integration: You can retrieve the list of files in a set with get_target_property(), making it easy to pass a complete file list to tools like clang-format.
• Precise Installation: Use install(FILE_SET ...) to install only the public headers of a target, ensuring a clean and minimal distribution.