C C++ CMake CSS Cypress date-fns Django Django REST Framework ESLint Git GNU Make HTML htmx HTTP JavaScript MariaDB NumPy pandas PHP PostgreSQL Python PyTorch Qt SQLite Tailwind CSS

Managing File Cleaning in CMake: Alternatives to ADDITIONAL_MAKE_CLEAN_FILES


Purpose

In CMake, ADDITIONAL_MAKE_CLEAN_FILES is a property used to specify additional files that should be deleted during the make clean command. This helps keep your build directory clean by removing any files that aren't explicitly part of your project but were generated during the build process.

Deprecated Status

It's important to note that ADDITIONAL_MAKE_CLEAN_FILES is considered deprecated since CMake version 3.15. While it might still work in older projects, it's recommended to use the preferred alternative, ADDITIONAL_CLEAN_FILES.

Preferred Alternative (ADDITIONAL_CLEAN_FILES)

  • Syntax:
  • Use the set_property command with the TARGET scope to associate the property with a specific build target.
set_property(TARGET your_target_name APPEND PROPERTY ADDITIONAL_CLEAN_FILES file1.txt file2.map)

This approach offers more flexibility because you can attach the cleaning instruction to individual targets within your project, ensuring that only the relevant files are removed for each target during make clean.

Example

add_executable(myprogram source1.cpp source2.cpp)
set_property(TARGET myprogram APPEND PROPERTY ADDITIONAL_CLEAN_FILES myprogram.map)

In this example, myprogram.map will only be deleted if you run make clean for the myprogram target.

  • Associate cleaning instructions with specific targets for better control.
  • For modern CMake, prefer set_property(TARGET ... ADDITIONAL_CLEAN_FILES ...).
  • Use ADDITIONAL_CLEAN_FILES only if you're working with a CMake version older than 3.15.

cmake_minimum_required(VERSION 3.0)

project(MyProject)

# Generate a temporary build script during configuration
configure_file(build_script.sh CONFIG_DESTINATION ${CMAKE_CURRENT_BINARY_DIR})

# Mark the temporary script for deletion during clean
set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES build_script.sh)

# Create an executable
add_executable(myprogram source1.cpp source2.cpp)

In this example:

  • set_directory_properties marks build_script.sh for deletion using ADDITIONAL_MAKE_CLEAN_FILES. So, when you run make clean, build_script.sh will be removed.
  • configure_file generates a temporary script build_script.sh during the configuration stage.
cmake_minimum_required(VERSION 3.15)

project(MyProject)

# Create an executable
add_executable(myprogram source1.cpp source2.cpp)

# Generate a dependency mapping file during build
set_target_properties(myprogram PROPERTIES COMPILE_FLAGS "-g")  # Enable debugging symbols

# Mark the dependency mapping file for cleaning
set_property(TARGET myprogram APPEND PROPERTY ADDITIONAL_CLEAN_FILES myprogram.map)
  • set_property marks myprogram.map for deletion using ADDITIONAL_CLEAN_FILES, associating it specifically with the myprogram target. So, only myprogram.map will be removed when you run make clean for the myprogram target.
  • set_target_properties enables debugging symbols for myprogram. This will typically generate a dependency mapping file named myprogram.map.
  • add_executable creates the myprogram target.

set_property(TARGET ... ADDITIONAL_CLEAN_FILES ...)

This is the recommended approach. It allows you to associate the cleaning instruction with a specific build target, giving you more control. You can use the APPEND keyword to add multiple files to the cleaning list for a target.

Example

add_executable(myprogram source1.cpp source2.cpp)
set_property(TARGET myprogram APPEND PROPERTY ADDITIONAL_CLEAN_FILES myprogram.map some_other_file.txt)

Custom Clean Commands

You can define custom clean commands to be executed during the make clean process. This approach is useful for complex cleaning tasks that involve multiple steps or external tools.

Example

add_custom_command(TARGET myprogram POST_BUILD
  COMMAND rm -rf ${CMAKE_CURRENT_BINARY_DIR}/temporary_files
)

File Globbing

In some cases, you might want to clean a group of files based on a pattern. While CMake doesn't have built-in globbing for cleaning, you can combine configure_file and custom clean commands to achieve this.

Example

configure_file(patterns.txt CONFIG_DESTINATION ${CMAKE_CURRENT_BINARY_DIR})

add_custom_command(TARGET myprogram POST_BUILD
  COMMAND rm -rf ${CMAKE_CURRENT_BINARY_DIR}/${PATTERN}
  DEPENDS patterns.txt
)
  • The DEPENDS clause ensures that the clean command runs after patterns.txt is generated.
  • The custom clean command uses rm with the PATTERN variable to remove matching files based on the contents of patterns.txt.
  • patterns.txt contains a list of file patterns to be cleaned (e.g., *.log).
  • For cleaning based on file patterns, consider the combination of configure_file and custom clean commands.
  • For complex cleaning tasks requiring additional logic or tools, opt for custom clean commands.
  • For simple cases where you want to clean specific files associated with a target, use set_property(TARGET ... ADDITIONAL_CLEAN_FILES ...).