CMake Directory Variables

CMake creates software build systems for a wide variety of platforms based on a single, unified control file–it’s a makefile maker. You create the CMake control file once and based on this file, CMake will create almost any build environment for you: GNU Make for Linux, Eclipse project, Visual Studio solution for Windows, and the list goes on.

I found the relationship between certain groups of related CMake variables troublesome.  I wrote my understanding of these variables to help myself remember, and I will share it with you.  If you have an better (or more correct) explanation, please leave a comment.

With CMake, you generally do out of source builds.  This means that when you build, you create a separate directory (folder), and build there, not in the same directory that contains the source code.  Thus in CMake there are two sets of variables that refer to directories: one for the source code, and another for the binary code.

While a simple CMake project will have only a single CMakeLists.txt control file, larger projects will contain a hierarchy of CMakeLists.txt files, each in its own directory.  These sub-control files are executed using the add_subdirectory command.  As its name suggests, add_subdirectory also creates a directory in the build tree.

*_SOURCE_DIR Variables

These variables contain the paths to various source code directories.  Note how every one of them refers to a directory that contains a CMakeLists.txt file.

  • CMAKE_SOURCE_DIR: The path to the top level of the source tree.  This is the directory that contains the top-level CMakeLists.txt file.  That is, this is the source directory you specify to the cmake command.
  • CMAKE_CURRENT_SOURCE_DIR: The path to the directory containing the CMakeLists.txt file that is currently being processed.
  • PROJECT_SOURCE_DIR: Top level source directory for the current project.  Not every CMakeLists.txt file defines a project–this is the directory that contains the most recent CMakeLists.txt file that defined a project.
  • projectName_SOURCE_DIR: Source directory for the named project.  This is the directory that contains the CMakeLists.txt file that contains the project(projectName) definition.  Every CMakeLists.txt file need not define a project, but one reason to define a project is to create this variable so you can refer to its source files later, in other CMakeLists.txt files.

*_BINARY_DIR Variables

The build tree will contain a directory hierarchy corresponding to the hierarchy of directories in the source tree containing CMakeLists.txt files.  Each of the following variables refers to a directory in the build tree corresponding to a source tree directory that contains a CMakeLists.txt file.

  • CMAKE_BINARY_DIR: The path to the top level of the build tree.  This is the directory in which you ran the cmake command.
  • CMAKE_CURRENT_BINARY_DIR: The path to the binary directory currently being processed.  When an add_subdirectory command is encountered in a CMakeLists.txt file, a corresponding directory is created in the build directory.  This variable contains that subdirectory.
  • PROJECT_BINARY_DIR: Top level binary directory for the current project.  Not every CMakeLists.txt file defines a project–this is the directory in the build tree that corresponds to the most recent CMakeLists.txt file that defined a project.
  • projectName_BINARY_DIR: Binary directory for the named project.  This is the directory in the build tree that corresponds to the CMakeLists.txt file that contains a project(projectName) definition.  Every CMakeLists.txt file need not define a project, but one reason to define a project is to create this variable so you can refer to its binary files later, in other CMakeLists.txt files.

I invite you to add any part of this article to the CMake documentation.

This article was originally published by John McGehee, Voom, Inc. under the CC BY 3.0 license.  Changes have been made.