Managing source files in a large project can be a daunting task, especially when using build systems like CMake. Manually listing each file in your CMakeLists.txt file is not only tedious but also prone to errors and inconsistencies. Imagine adding a new source file and forgetting to update your build configuration – a recipe for build failures and wasted time. Fortunately, CMake provides mechanisms to automatically add all files in a folder to a target, streamlining your build process and reducing the chances of human error. This approach significantly simplifies project maintenance, especially as the project grows and evolves. By leveraging CMake’s features for automatic file inclusion, developers can focus on writing code rather than managing build configurations, leading to increased productivity and more robust software.

Why Automatically Add Files to a CMake Target?

The traditional approach of manually listing source files in a CMakeLists.txt file can quickly become unwieldy, particularly in large projects. When you manually specify each file, every addition, deletion, or renaming requires a corresponding update in the CMake configuration. This is not only time-consuming but also increases the risk of introducing errors. For instance, forgetting to add a new source file to the list will result in a build failure, and tracking down such issues can be frustrating.

Automatically adding files eliminates these manual steps, making your build process more robust and maintainable. CMake offers several commands and techniques to achieve this, such as using file(GLOB...) or file(GLOB_RECURSE...) to dynamically discover source files in a directory or its subdirectories. These commands generate a list of files that can then be added to a target, ensuring that your build system always includes the latest source code. According to a report by Forrester, automation in software development can reduce errors by up to 70% and significantly improve time-to-market [^1^].

The benefits of automatic file addition extend beyond just convenience. It also promotes code organization and modularity. By organizing your source code into logical directories, you can easily define different targets for different parts of your project, with each target automatically including the relevant files from its respective directory. This approach makes it easier to manage dependencies and build separate components of your application, fostering a more maintainable and scalable codebase. This is especially useful when creating shared libraries or executables from different parts of a larger software system.

How to Automatically Add Files Using CMake

CMake provides several powerful commands to automatically add files to a target. The most commonly used commands are file(GLOB...) and file(GLOB_RECURSE...). These commands search for files matching a specified pattern within a directory (or its subdirectories, in the case of GLOB_RECURSE) and store the results in a variable. This variable can then be used to add the discovered files to a target. Here’s a breakdown of how to use these commands:

The file(GLOB...) command searches for files in a single directory. For example, to find all .cpp files in the src directory, you would use the following syntax:

cmake file(GLOB SOURCES “src/.cpp”) add_executable(my_executable ${SOURCES}) This code snippet first uses file(GLOB...) to find all .cpp files in the src directory and stores the results in the SOURCES variable. Then, it uses add_executable(...) to create an executable target named my_executable, adding all the files listed in the SOURCES variable to the target. It’s important to note that while using GLOB is easy, it doesn’t automatically pick up newly added files. For that you need to rerun CMake or use other approaches.

For projects with a more complex directory structure, file(GLOB_RECURSE...) is invaluable. This command searches for files in a directory and all of its subdirectories. This is particularly useful in larger projects. According to a study by the Standish Group, well-structured projects have a 50% higher success rate [^2^]. Here’s an example:

cmake file(GLOB_RECURSE SOURCES “src/.cpp”) add_library(my_library ${SOURCES}) This code finds all .cpp files in the src directory and all of its subdirectories, storing the results in the SOURCES variable. Then, it creates a library target named my_library, adding all the discovered files to the target. You can also exclude certain directories from the globbing operation using EXCLUDE. For example:

cmake file(GLOB_RECURSE SOURCES “src/.cpp” EXCLUDE “src/tests” “src/legacy”) This will search for all .cpp files in the src directory and its subdirectories, but it will exclude the src/tests and src/legacy directories from the search. This is useful to exclude test files or legacy code that shouldn’t be included in the main library or executable. Remember to carefully consider the performance implications of using GLOB_RECURSE, especially in very large projects, as it can significantly increase the configuration time.

Best Practices for Using CMake File Globbing

While file(GLOB...) and file(GLOB_RECURSE...) are powerful tools, they should be used with caution. Overuse or misuse can lead to unexpected behavior and performance issues. Here are some best practices to follow when using these commands:

• Use with caution for source files: Generally, it’s recommended to avoid using GLOB for source files because CMake won’t automatically detect new files added after the initial configuration. Using GLOB for header files is generally more accepted.
• Be specific with file patterns: Avoid using overly broad patterns like ``, as this can include unwanted files and increase the configuration time. Instead, use more specific patterns like .cpp or .h to target only the files you need.
• Use EXCLUDE to exclude unwanted directories: As shown in the previous section, the EXCLUDE option is crucial for preventing unwanted files from being included in your target. Always use EXCLUDE to filter out test directories, legacy code, or other directories that should not be part of the build.
• Consider using TARGET_SOURCES: For newer CMake versions, the TARGET_SOURCES command offers a more modern and flexible way to manage source files. It allows you to specify source files directly to a target without using intermediate variables.

Here’s how you might use TARGET_SOURCES with a list of files:

cmake add_executable(my_executable main.cpp file1.cpp file2.cpp) target_sources(my_executable PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/file3.cpp ${CMAKE_CURRENT_SOURCE_DIR}/include/header.h) This example adds main.cpp, file1.cpp, and file2.cpp when defining the executable. It then uses target_sources to add file3.cpp and header.h to the target, but marks them as PRIVATE, meaning they are only used internally by the target and are not exposed to other targets that might link against it. Using PRIVATE, PUBLIC, or INTERFACE appropriately is essential for managing dependencies correctly in CMake.

Here are the advantages of TARGET_SOURCES:

• Cleaner syntax and better integration with CMake’s dependency management system.
• More control over the visibility of source files (PUBLIC, PRIVATE, INTERFACE).
• Improved compatibility with different CMake generators and build systems.

Example: Implementing a Library with Automatic File Addition

Let’s illustrate how to automatically add all files in a folder to a target using a simple library example. Assume you have a directory structure like this:

my_library/ ├── include/ │ └── my_library.h └── src/ ├── file1.cpp ├── file2.cpp └── file3.cpp Your CMakeLists.txt file might look like this:

cmake cmake_minimum_required(VERSION 3.15) project(MyLibrary) file(GLOB_RECURSE SOURCES “src/.cpp” “include/.h”) add_library(MyLibrary ${SOURCES}) target_include_directories(MyLibrary PUBLIC $<build_interface:> $<install_interface:include>) install(TARGETS MyLibrary DESTINATION lib) install(DIRECTORY include/ DESTINATION include FILES_MATCHING PATTERN “.h”) This CMakeLists.txt file first defines the project name. Then, it uses file(GLOB_RECURSE...) to find all .cpp and .h files in the src and include directories. The discovered files are then added to a library target named MyLibrary. The target_include_directories command specifies the include directories for the library, ensuring that other projects can find the library’s header files. Finally, the install commands specify how the library and its header files should be installed when the project is built and installed.

Alternative Approaches and Considerations

While file globbing provides a convenient way to automatically include files, CMake offers other alternatives that provide more control and flexibility. One such alternative is to explicitly list the source files in your CMakeLists.txt file. While this approach requires more manual effort, it gives you precise control over which files are included in your target. Furthermore, tools like modern CMake offer features to help manage source file lists more efficiently.

Another powerful technique is using CMake modules to encapsulate file discovery logic. You can create a custom CMake module that searches for files based on specific criteria and then includes those files in your target. This approach allows you to reuse the file discovery logic across multiple targets or projects, promoting code reuse and reducing redundancy. For example, you could create a module that searches for all files with a specific naming convention or that are located in a specific directory structure. This modular approach can significantly improve the maintainability and scalability of your build system.

When choosing between these approaches, consider the size and complexity of your project, as well as the level of control and flexibility you need. For small projects with a simple directory structure, file globbing may be sufficient. However, for larger and more complex projects, explicitly listing files or using custom CMake modules may provide a more robust and maintainable solution. Always weigh the trade-offs between convenience and control when making your decision. Remember that good CMake practices are as important as good coding practices. The official CMake documentation provides an excellent resource for learning more about these alternative approaches [^3^].

Here’s a featured snippet optimized paragraph:

To automatically add all files in a folder to a target using CMake, use the file(GLOB...) or file(GLOB_RECURSE...) commands to dynamically discover source files. file(GLOB...) searches a single directory, while file(GLOB_RECURSE...) searches a directory and all its subdirectories. Store the results in a variable and then use that variable when defining your target (e.g., add_executable or add_library). This simplifies project maintenance and reduces the risk of errors.

**Q: Is it always a good idea to use `file(GLOB...)` for source files?**

A: No, it's generally not recommended for source files. CMake won't automatically detect new files added after the initial configuration. It's better for header files or configuration files that rarely change.

**Q: How can I exclude certain directories when using `file(GLOB_RECURSE...)`?**

A: Use the `EXCLUDE` option. For example: `file(GLOB_RECURSE SOURCES "src/.cpp" EXCLUDE "src/tests")`.

**Q: What is the difference between `PRIVATE`, `PUBLIC`, and `INTERFACE` when using `TARGET_SOURCES`?**

A: These keywords control the visibility of the source files. `PRIVATE` means the files are only used internally by the target. `PUBLIC` means they are also visible to other targets that link against it. `INTERFACE` is for header-only libraries.

**Q: My CMake project is **Question & Answer :** I am considering switching a cross platform project from separate build management systems in Visual C++, XCode and makefiles to CMake.

One essential feature I need is to add automatically all files in a directory to a target. While this is easy to do with make, it is not easily doable with Visual C++ and XCode (correct me if I am wrong). Is it possible to do it in directly in CMake? How?

As of CMake 3.1+ the developers strongly discourage users from using file(GLOB or file(GLOB_RECURSE to collect lists of source files.

Note: We do not recommend using GLOB to collect a list of source files from your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag may not work reliably on all generators, or if a new generator is added in the future that cannot support it, projects using it will be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a cost to perform the check on every rebuild.

See the documentation here.

There are two goods answers ([1], [2]) here on SO detailing the reasons to manually list source files.

---

It is possible. E.g. with file(GLOB:

cmake_minimum_required(VERSION 2.8) file(GLOB helloworld_SRC "*.h" "*.cpp" ) add_executable(helloworld ${helloworld_SRC}) 

Note that this requires manual re-running of cmake if a source file is added or removed, since the generated build system does not know when to ask CMake to regenerate, and doing it at every build would increase the build time.

As of CMake 3.12, you can pass the CONFIGURE_DEPENDS flag to file(GLOB to automatically check and reset the file lists any time the build is invoked. You would write:

cmake_minimum_required(VERSION 3.12) file(GLOB helloworld_SRC CONFIGURE_DEPENDS "*.h" "*.cpp") 

This at least lets you avoid manually re-running CMake every time a file is added.**