cmake - tutorial - file glob src

Is it better to specify source files with GLOB or each file individually in CMake? (3)

CMake offers several ways to specify the source files for a target. One is to use globbing (documentation), for example:

FILE (GLOB dir/*)

Another one is to specify each file individually.

Which way is to prefer? Globbing seems easy, but I heard it has some downsides.

Full disclosure: I originally preferred the globbing approach for its simplicity, but over the years I have come to recognise that explicitly listing the files is less error-prone for large, multi-developer projects.

Original answer:

The advantages to globbing are:

  • It's easy to add new files as they are only listed in one place: on disk. Not globbing creates duplication.

  • Your CMakeLists.txt file will be shorter. This is a big plus if you have lots of files. Not globbing causes you to lose the CMake logic amongst huge lists of files.

The advantages of using hardcoded file lists are:

  • CMake will track the dependencies of a new file on disk correctly - if we use glob then files not globbed first time round when you ran CMake will not get picked up

  • You ensure that only files you want are added. Globbing may pick up stray files that you do not want.

In order to work around the first issue, you can simply "touch" the CMakeLists.txt that does the glob, either by using the touch command or by writing the file with no changes. This will force cmake to re-run and pick up the new file.

To fix the second problem you can organize your code carefully into directories, which is what you probably do anyway. In the worst case, you can use the list(REMOVE_ITEM) command to clean up the globbed list of files:

file(GLOB to_remove file_to_remove.cpp)
list(REMOVE_ITEM list ${to_remove})

The only real situation where this can bite you is if you are using something like git-bisect to try older versions of your code in the same build directory. In that case, you may have to clean and compile more than necessary to ensure you get the right files in the list. This is such a corner case, and one where you already are on your toes, that it isn't really an issue.

Specify each file individually!

I use a conventional CMakeLists.txt and a python script to update it. I run the python script manually after adding files.

See my answer here: https://.com/a/48318388/3929196

You can safely glob (and probably should) at the cost of an additional file to hold the dependencies.

Add functions like these somewhere:

# Compare the new contents with the existing file, if it exists and is the 
# same we don't want to trigger a make by changing its timestamp.
function(update_file path content)
    set(old_content "")
    if(EXISTS "${path}")
        file(READ "${path}" old_content)
    if(NOT old_content STREQUAL content)
        file(WRITE "${path}" "${content}")

# Creates a file called CMakeDeps.cmake next to your CMakeLists.txt with
# the list of dependencies in it - this file should be treated as part of 
# CMakeLists.txt (source controlled, etc.).
function(update_deps_file deps)
    set(deps_file "CMakeDeps.cmake")
    # Normalize the list so it's the same on every machine
    list(REMOVE_DUPLICATES deps)
    foreach(dep IN LISTS deps)
        file(RELATIVE_PATH rel_dep ${CMAKE_CURRENT_SOURCE_DIR} ${dep})
        list(APPEND rel_deps ${rel_dep})
    list(SORT rel_deps)
    # Update the deps file
    set(content "# generated by make process\nset(sources ${rel_deps})\n")
    update_file(${deps_file} "${content}")
    # Include the file so it's tracked as a generation dependency we don't
    # need the content.

And then go globbing:

file(GLOB_RECURSE sources LIST_DIRECTORIES false *.h *.cpp)
add_executable(test ${sources})

You're still carting around the explicit dependencies (and triggering all the automated builds!) like before, only it's in two files instead of one.

The only change in procedure is after you've created a new file. If you don't glob the workflow is to modify CMakeLists.txt from inside Visual Studio and rebuild, if you do glob you run cmake explicitly - or just touch CMakeLists.txt.