Useful CMake Commands and Variables

This article contains useful and frequently-used commands and variables when using cmake build system, as well as their corresponding meanings.

Commands §

• find_package(CUDAToolkit REQUIRED): locate NVIDIA CUDA toolkit and associated libraries without enabling CUDA language support globally, details
• include(CheckLanguage) check_language(CUDA): check CUDA language status
• set_source_files_properties(FILES PROPERTIES LANGUAGE CUDA): forcibly set language property for source files, which determines the compiler used to compile themselves

Variables §

• CMAKE_VERBOSE_MAKEFILE:BOOL: demonstrate build commands when executing make
• PROJECT_SOURCE_DIR: directory where the top-most level CMakeLists.txt containing project() command; NOT affect by add_subdirectory()
• CMAKE_MODULE_PATH: semicolon separated directories used to search CMake modules to be loaded by find_package() or include(); need to be set by project. Commonly the CMake module files will be placed in the cmake folder of the project.
• CMAKE_PREFIX_PATH: A path list which specifies the search path for find_path(), find_library() or find_program(). Suffices like /lib, /bin will be appended for the corresponding routine.
• CMAKE_{LANG}_COMPILER: LANG could be C, CXX or CUDA depending on the project language. Besides, there is one more compiler option for CUDA: CMAKE_CUDA_HOST_COMPILER, which determines the one used to compile host part code in CUDA source file.
• CMAKE_EXPORT_COMPILE_COMMANDS: if enabled, compile_commands.json will be generated in the build folder.

CMake Cache §

Officlal docs: https://cmake.org/cmake/help/book/mastering-cmake/chapter/CMake%20Cache.html CMake cache variable are stored in CMakeCache.txt file when you configure the CMake-based project firstly. Later runs will not evaluate them every time, instead, CMake just read their values from the cache file. Besides, every CMake cache variable has a global scope.

If you set the file via command-line -D option, the cache value will be overwritten forcibly.

Properties §

• Source file language: by default, CMake identifies the language as well as the compiler and linker used to compile each compile unit by the source file extension. If the source file ends up with .cc, CMake will use CXX compiler to compile it. There are some exceptions that the target language and the source file extension are mis-matched. We can use CMake command set_source_files_properties(${file_glob} PROPERTIES LANGUAGE CUDA) to change the target language manually.

References & Useful Links §

• CMake find module variable names convention
• find_path
• find_library
• find_package_handle_standard_args
• Tutorial of how to write Findlib.cmake
• CMake target properties
• CMAKE_CUDA_HOST_COMPILER