Working with the File System

The file() command is one of the most flexible commands in CMake. It's a single command that provides a huge collection of subcommands for different file-related tasks. The general syntax is:

1file(<SUBCOMMAND> ...arguments...)

We can broadly categorize these subcommands into three groups:

• Reading: Getting content from files on disk.
• Writing: Creating new files or modifying existing ones.
• Filesystem Operations: Creating directories, copying files, and finding files that match a pattern.

Let's explore each of these categories.

Sometimes, you want to store project information outside of your CMakeLists.txt file. For example, you might have a simple text file containing your project's version number. The file() command lets you read this data directly into a CMake variable.

file(READ)

This subcommand reads the entire content of a file into a single variable.

Let's create a version.txt file in the root of our Greeter project:

11.2.3

Now, we can modify our root CMakeLists.txt to read this version instead of hardcoding it. This pattern makes it easy to manage configuration data in separate, simple files that non-programmers can edit.

1cmake_minimum_required(VERSION 3.16)
2
3# Read the version.txt file
4# Store it in avariable called GREETER_VERSION_FROM_FILE
5file(READ version.txt GREETER_VERSION_FROM_FILE) 
6
7# Strip any excess white space from GREETER_VERSION_FROM_FILE,
8# Then store the result in a variable called GREETER_VERSION
9string(STRIP ${GREETER_VERSION_FROM_FILE} GREETER_VERSION) 
10
11message(STATUS "Configuring Version ${GREETER_VERSION}")
12
13project(
14  Greeter
15  VERSION ${GREETER_VERSION} 
16  HOMEPAGE_URL "https://www.studyplan.dev"
17  DESCRIPTION "A program that says hello to people"
18)
19
20# ...

1-- Configuring Version 1.2.3

Our initial file() command reads the content of version.txt and stores it in the GREETER_VERSION_FROM_FILE variable. This variable will likely contain additional white space - possibly a new line, such as "1.2.3\n".

string(STRIP ...) is a handy utility command that removes leading and trailing whitespace. We use it to clean up the variable, so GREETER_VERSION becomes just "1.2.3".

file(STRINGS)

While file(READ) grabs the whole file, file(STRINGS) is more specific: it reads a file and splits it into a CMake list, with each line of the file becoming an element in the list.

This is perfect for when you have a manifest file listing items, such as a list of source files. Let's imagine we have a file called sources.txt in our app directory:

1src/main.cpp
2src/tools.cpp

We can now read this into a list variable in app/CMakeLists.txt:

1cmake_minimum_required(VERSION 3.16)
2
3file(STRINGS sources.txt SOURCES) 
4foreach(file IN LISTS SOURCES)
5  message(STATUS "Using file ${file}")
6endforeach()
7
8project(MyProject)
9add_executable(MyTarget SOURCES)

1-- Using file src/main.cpp
2-- Using file src/tools.cpp

The SOURCES variable will now be the list "src/main.cpp;src/goodbye.cpp", which is then correctly expanded when passed to add_executable(). This approach can make it easier to manage long lists of files without cluttering your main CMakeLists.txt.

Just as we can read from files, we can also write to them. This is often used for generating files at configure time, such as a build information file or a configuration header.

file(WRITE) and file(APPEND)

These commands are straightforward: WRITE creates a new file (or overwrites an existing one), and APPEND adds content to the end of a file.

Let's create a simple command that generates a build_info.txt file containing the timestamp of when the project was configured. We'll use the string(TIMESTAMP) command to get the current time.

1cmake_minimum_required(VERSION 3.16)
2
3project(MyProject VERSION "1.2.3")
4
5string(TIMESTAMP BUILD_TIME "%Y-%m-%d %H:%M:%S UTC") 
6set(BUILD_INFO "Project: ${PROJECT_NAME}\n") 
7set(BUILD_INFO "${BUILD_INFO}Version: ${PROJECT_VERSION}\n") 
8set(BUILD_INFO "${BUILD_INFO}Configured at: ${BUILD_TIME}\n") 
9
10file(WRITE ${CMAKE_BINARY_DIR}/build_info.txt "${BUILD_INFO}") 
11message(STATUS "Wrote build info to ${CMAKE_BINARY_DIR}")

In this example, we're using the CMake-provided CMAKE_BINARY_DIR variable. CMake's "binary directory" is what most developers call the "build directory" - that is, the directory from which we used our cmake command.

So, in this case, when we configure our project, this will create a build_info.txt file in our build directory:

1-- Wrote build info to D:/projects/cmake/build

1Project: MyProject
2Version: 1.2.3
3Configured at: 2025-07-29 23:19:09 UTC

An interesting use of this technique is to create C++ header files within CMake, and to then #include those headers as needed in our source files.

This gives our program access to information that is normally only available within a CMakeLists.txt script. We'll see a practical example of this later in the course.

The file() command also provides tools for manipulating the filesystem itself, such as creating directories and copying files.

Using file(GLOB) and file(GLOB_RECURSE)

This is one of the most tempting, and most dangerous, subcommands in CMake. GLOB allows you to find all files in a directory that match a certain pattern (a "globbing expression") and store them in a list.

For example, to find all .cpp files in the src directory, you could write:

1file(GLOB GREETER_SOURCES "src/*.cpp")
2add_executable(GreeterApp ${GREETER_SOURCES})

This looks incredibly convenient. You never have to manually update your CMakeLists.txt when you add or remove a source file. However, this convenience comes at a high price.

Creating Directories

The file(MAKE_DIRECTORY) subcommand ensures that one or more directories exist, creating them if they don't. It's useful in custom build steps where you need to guarantee an output directory is present before copying files into it.

1# Ensure an assets directory exists in the build folder
2file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/assets)

Copying Files

The file(COPY) subcommand copies files or entire directories from a source to a destination. It's a simple way to move resources needed at runtime into your build directory.

1# Copy a config file into the build directory
2file(COPY "data/config.json" DESTINATION ${CMAKE_BINARY_DIR}/)

A very common use case for file operations is managing non-code assets that your application needs at runtime, such as images, configuration files, or fonts. You typically want to copy these assets from your source tree into your build directory so that they are available alongside your executable.

Let's extend our Greeter project to handle this.

Step 1: Create the Asset Files

First, let's create an assets directory in our project's root and add a couple of files. It doesn't matter what these files are or what they contain, we're just going to use them as placeholders to learn the process:

1assets/
2  ├─ logo.png
3  └─ config.json
4CMakeLists.txt

Step 2: Update CMakeLists.txt to Copy the Files

Now, let's add logic to our root CMakeLists.txt to copy these files into the build directory. We will use a combination of set(), foreach(), and file() commands.

1cmake_minimum_required(VERSION 3.16)
2
3set(ASSET_FILES
4  logo.png
5  config.json
6)
7
8set(ASSET_DEST "${CMAKE_BINARY_DIR}/assets")
9
10# Ensure the destination directory exists
11file(MAKE_DIRECTORY ${ASSET_DEST})
12
13foreach(asset IN LISTS ASSET_FILES)
14  # Build the full path to the current asset file 
15  set(src_path "${CMAKE_CURRENT_SOURCE_DIR}/assets/${asset}")
16   
17  # Copy the source file to the destination directory.
18  file(COPY ${src_path} DESTINATION ${ASSET_DEST})
19   
20  message(STATUS "Copied ${src_path} to asset directory")
21endforeach()

Step 3: Verify the Result

Now, when you run the configure step (cmake .. from your build directory), this script will execute.

1cmake ..

1-- Copied D:/Projects/cmake/assets/logo.png to asset directory
2-- Copied D:/Projects/cmake/assets/config.json to asset directory

Afterward, your build directory will have a new, populated assets folder, ready for your executable to use.

1build/
2├─ assets/
3│  ├─ logo.png
4│  └─ config.json
5├─ ... (other generated files)

The file() command is an important part of any non-trivial CMake script. It's your bridge between the abstract world of build targets and the concrete world of files and directories on disk.

• Reading: Use file(READ) to get a file's full content and file(STRINGS) to read it line-by-line into a list.
• Writing: Use file(WRITE) and file(APPEND) to generate files at configure time.
• Filesystem: Use file(MAKE_DIRECTORY) and file(COPY) for basic filesystem management.
• Avoid file(GLOB): Never use file(GLOB) to collect source files; it makes your build unreliable. Always list sources explicitly.
• Path Management: Understand the key path variables (CMAKE_SOURCE_DIR, CMAKE_CURRENT_SOURCE_DIR, etc.) and use get_filename_component() for all your path manipulation needs.