Controlling Executable Names in CMake with CMAKE_EXECUTABLE_SUFFIX

Purpose

• This suffix varies depending on the operating system:
  • Windows: Typically .exe
  • macOS/Linux: Usually empty (no suffix)
  • Other platforms: May have different conventions
• In CMake, CMAKE_EXECUTABLE_SUFFIX determines the suffix appended to executable filenames generated during the build process.

Behavior

• However, you can override this default value for specific compiler languages using variables like CMAKE_EXECUTABLE_SUFFIX_<LANG> (where <LANG> is the compiler language, e.g., C, CXX).
• CMake automatically sets CMAKE_EXECUTABLE_SUFFIX based on the detected platform.

Example

# CMake automatically sets CMAKE_EXECUTABLE_SUFFIX based on the platform

# To override for a specific language (e.g., C):
set(CMAKE_EXECUTABLE_SUFFIX_C ".out")  # Executables compiled with the C compiler will end in ".out"

Key Points

• Changing these variables affects how CMake generates executable filenames during the build.
• Use CMAKE_EXECUTABLE_SUFFIX_<LANG> for language-specific customization.
• Use CMAKE_EXECUTABLE_SUFFIX for general executable naming across languages.

• If you encounter issues with executable naming, refer to CMake's documentation for more advanced configuration options.
• While overriding CMAKE_EXECUTABLE_SUFFIX might be necessary in rare cases (e.g., cross-platform compatibility with custom toolchains), it's generally recommended to rely on CMake's defaults for consistency and platform-specific behavior.

---

Example 1: Using Default Suffix

This example shows how CMake automatically sets the executable suffix based on the platform:

# No need to explicitly set CMAKE_EXECUTABLE_SUFFIX

add_executable(my_program main.cpp)

# On Windows: my_program.exe
# On macOS/Linux: my_program

Example 2: Overriding Suffix for All Languages

This example overrides the default suffix for all executables to .out:

set(CMAKE_EXECUTABLE_SUFFIX ".out")

add_executable(my_cpp_program main.cpp)
add_executable(my_c_program main.c)

# Both executables will be named my_cpp_program.out and my_c_program.out

Example 3: Customizing Suffix by Language

This example sets a custom suffix for C executables and keeps the default for C++:

set(CMAKE_EXECUTABLE_SUFFIX_C ".out")

add_executable(my_cpp_program main.cpp)
add_executable(my_c_program main.c)

# my_cpp_program (default suffix)
# my_c_program.out (custom suffix for C)

---

Rely on CMake Defaults

The most straightforward approach is to trust CMake's platform-specific defaults for executable suffixes. This ensures compatibility and avoids potential issues with cross-platform builds.

Install Targets with Custom Names

If you need to install executables with specific names regardless of their generated filenames, use CMake's install commands with custom target names:

add_executable(my_program main.cpp)

# Install with a custom name:
install(TARGETS my_program DESTINATION bin RENAME my_program_custom)

Here, my_program_custom will be the final name of the installed executable.

Custom Toolchain File (Advanced)

For complex scenarios with custom toolchains or non-standard naming conventions, you can create a custom toolchain file. This involves modifying the linker flags to specify the desired suffix. However, this approach requires a deeper understanding of CMake toolchains and is generally recommended only for advanced users.

Variable Substitution (Limited Use)

In rare cases, you might consider using variable substitution within the OUTPUT_FILE property of your add_executable command. However, this is less portable and can lead to issues with CMake's internal logic. It's generally not recommended unless absolutely necessary.

• Avoid variable substitution within OUTPUT_FILE unless absolutely essential.
• For complex toolchain needs, consider custom toolchain files (advanced).
• For specific installation names for executables, use install with RENAME.
• For standard cross-platform builds, use CMake defaults.