7.run_other_program

Running other programs

`execute_process`

In CMake, you can run external commands during the configure step using execute_process. This is useful for tasks like interacting with version control (e.g., Git), fetching data, or running setup scripts.

General Best Practices

Avoid hardcoding paths to external programs. Instead, use:
- ${CMAKE_COMMAND}: For running CMake itself.
- find_package() or find_program(): To find tools like Git dynamically.
Use RESULT_VARIABLE to capture the exit code of the command.
Use OUTPUT_VARIABLE to capture the command's output.

Example: Updating Git Submodules

This example checks if Git is available and updates all submodules in the project:

# Find Git
find_package(Git QUIET)

if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
    # Run the command to update submodules
    execute_process(
        COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}  # Set working directory
        RESULT_VARIABLE GIT_SUBMOD_RESULT              # Capture result code
    )
    # Check if the command was successful
    if(NOT GIT_SUBMOD_RESULT EQUAL "0")
        message(FATAL_ERROR "git submodule update --init --recursive failed with result: ${GIT_SUBMOD_RESULT}. Please check out the submodules.")
    endif()
endif()

find_package(Git QUIET): Looks for Git on the system without verbose output.
execute_process:
- Runs the command git submodule update --init --recursive.
- Sets the working directory to the project's source directory.
- Captures the result variable (GIT_SUBMOD_RESULT) to check if the command was successful.
Error Handling: If the command fails, message(FATAL_ERROR) halts the CMake configuration process and outputs an error message with the result code.

Other Uses for `execute_process`:

Checking the current Git commit:

execute_process(
    COMMAND ${GIT_EXECUTABLE} rev-parse --short HEAD
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
    OUTPUT_VARIABLE GIT_COMMIT_HASH
    OUTPUT_STRIP_TRAILING_WHITESPACE
)

This retrieves the current Git commit hash and stores it in GIT_COMMIT_HASH.

Running custom scripts: You can use execute_process to run shell or Python scripts to perform setup tasks at configure time.

Running a Command at Build Time

In CMake, running commands at build time involves more complexity compared to configure time. You need to decide:

When the command should run (e.g., after a specific target is built or every time you build).
If the command produces an output that another target needs (i.e., setting up dependencies between targets).

Example: Generating a Header File with Python

This example demonstrates how to call a Python script to generate a header file during the build process:

find_package(PythonInterp REQUIRED)  # Find the Python interpreter

# Add a custom command to generate the header file
add_custom_command(
    OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/include/Generated.hpp"  # Output file
    COMMAND "${PYTHON_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/GenerateHeader.py" --argument  # Command to run
    DEPENDS some_target  # Optional: Only generate after some_target is built
)

# Add a custom target that depends on the generated file
add_custom_target(generate_header ALL
    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/include/Generated.hpp"
)

# Install the generated header file
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/include/Generated.hpp" DESTINATION include)

add_custom_command:
- OUTPUT: Specifies the file generated by the command (in this case, Generated.hpp).
- COMMAND: Runs the Python script using the found PYTHON_EXECUTABLE.
- DEPENDS: The command runs after the specified target (some_target) is complete.
add_custom_target:
- generate_header: A custom target that depends on the generated header file.
- The ALL keyword ensures that the generate_header target runs when you build the entire project (without specifying any target).
install: Installs the generated header file into the specified location (include).

Controlling When the Command Runs

Always running: If you want the header generation to always happen when you build (e.g., with make), the ALL keyword ensures that the generate_header target runs by default.
As a dependency: You can remove ALL and instead add dependencies to other targets using add_dependencies:
```
add_dependencies(main_target generate_header)  # Ensure 'main_target' depends on 'generate_header'
```
Manual invocation: If you remove ALL and do not add dependencies, users would need to explicitly build the generate_header target with:
```
make generate_header
```

When to Use Build Time Commands

File generation: You often need build-time commands for generating files (e.g., headers, source files) based on external scripts or tools.
Pre/post build steps: Custom build steps that modify the output or do additional processi

Included Common Utilities: `cmake -E`

CMake provides a variety of cross-platform utilities via the cmake -E command, accessible in CMake scripts through ${CMAKE_COMMAND} -E.
These utilities enable you to perform common tasks like copying files, creating directories, or removing files without relying on platform-specific tools.
This makes your CMake build scripts more portable and ensures consistency across different operating systems.

Common Modes for `cmake -E`:

copy: Copies a file or directory.
make_directory: Creates a directory (and parent directories if necessary).
remove: Removes files or directories.
create_symlink: Creates a symbolic link (cross-platform support, added to Windows in CMake 3.13).

Example of Using `cmake -E` in Build Time Commands:

# Using CMake's built-in copy utility
add_custom_command(
    TARGET my_target POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy
            "${CMAKE_CURRENT_SOURCE_DIR}/myfile.txt"
            "${CMAKE_CURRENT_BINARY_DIR}/myfile.txt"
)

# Creating a directory at build time
add_custom_command(
    TARGET my_target POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/output_dir"
)

# Removing a file at build time
add_custom_command(
    TARGET my_target POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E remove "${CMAKE_CURRENT_BINARY_DIR}/oldfile.txt"
)

Key Benefits

Cross-platform: The same command works on all supported operating systems, without needing to worry about platform-specific tools like cp, rm, or mkdir.
Portable and consistent: Ensures consistent behavior across Linux, macOS, and Windows.
Enhanced functionality: With the addition of create_symlink for Windows in CMake 3.13, you can now create symbolic links in a cross-platform manner.

Example of Creating a Symlink

# Create a symbolic link using CMake's create_symlink mode
add_custom_command(
    TARGET my_target POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E create_symlink
            "${CMAKE_CURRENT_SOURCE_DIR}/sourcefile.txt"
            "${CMAKE_CURRENT_BINARY_DIR}/link_to_sourcefile.txt"
)

For more details, check out the CMake command-line tool documentation.