Print

Log a message by wrapping the CMake message() command to extend its functionalities .It requires CMake 4.0.1 or newer.

Synopsis

Print Formated Message
  print([<mode>] "message with formated text" <argument>...)

Print Path List
  print([<mode>] REL_PATHS [<file-path>...] [INDENT])

Print String List
  print([<mode>] STRINGS [<string>...] [INDENT])

Module Variables

PRINT_BASE_DIR

Specifies the base directory used to compute relative paths in the print(normal) commands. Its default value is CMAKE_SOURCE_DIR.

Usage

print([<mode>] "message with formated text" <argument>...)

Record the specified message text in the log, optionally specifying a message mode. This command is inspired by the message() command from CMake and the C printf() function.

If specified, the optional <mode> keyword must be one of the standard message modes accepted by the message() command, such as STATUS, WARNING, ERROR, etc.

The "message with formated text" may contain one or more custom conversion directives enclosed in @ characters. These directives will be replaced using the provided arguments, in the order they are given. Text without directives is equivalent to a call to message() command.

Each directive takes the form @specifier@, where specifier is one of the following:

@ap@ (for "absolute path")

Converts the corresponding argument into an absolute path to a file or directory. The argument may be a relative or absolute path, and may even refer to a file or directory that does not exist on disk. An error is raised when the argument is empty.

@rp@ (for "relative path")

Converts the corresponding argument into a path relative to the value of the PRINT_BASE_DIR variable. The argument may be a relative or absolute path, and may even refer to a file or directory that does not exist on disk. An error is raised when the argument is empty.

@apl@ (for "absolute path list")

Converts all the corresponding arguments into a list of absolute paths to files or directories. The arguments may be relative or absolute paths, and may even refer to files or directories that does not exist on disk. Each item is printed separated by a comma: item1, item2, .... When the provided list is empty, the directive is replaced with an empty string. This directive should be used last when the message includes several directives.

@rpl@ (for "relative path list")

Converts all the corresponding argument into a list of path relative to the value of the PRINT_BASE_DIR variable. The arguments may be relative or absolute paths, and may even refer to files or directories that does not exist on disk. Each item is separated by a comma: item1, item2, .... The files or the directories must exist on the disk. When the provided list is empty, the directive is replaced with an empty string. This directive should be used last when the message includes several directives.

@sl@ (for "string list")

Converts all the corresponding argument into a list of strings where each item is separated by a comma: item1, item2, ... like with the print(STRINGS) command. When the provided list is empty, the directive is replaced with an empty string. This directive should be used last when the message includes several directives.

For all path arguments, and because of the use of cmake_path(), only syntactic aspects of paths are handled, there is no interaction of any kind with any underlying file system. A path may represent a non- existing path or even one that is not allowed to exist on the current file system or platform.

An error is raised if a directive has no associated argument, or if a message contains an unsupported directive.

Example usage:

# Message with ap and rp directives, without mode
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(my_path "src/main.cpp")
print("Absolute: @ap@, Relative: @rp@" "${my_path}" "${my_path}")
# Output:
#   Absolute: /full/path/to/src/main.cpp, Relative: src/main.cpp

# Message with ap and rp directives, with mode
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(my_path "src/main.cpp")
print(STATUS "Absolute: @ap@, Relative: @rp@" "${my_path}" "${my_path}")
# Output:
#   -- Absolute: /full/path/to/src/main.cpp, Relative: src/main.cpp

# Message with apl directive and empty argument
print(STATUS "Absolute paths: @apl@" "")
# Output:
#   -- Absolute paths:

# Message with apl directive and various paths
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(path_list
  "src/main.cpp"
  "src"
  "${CMAKE_SOURCE_DIR}/src/main.cpp"
  "${CMAKE_SOURCE_DIR}/src"
  "fake/directory/file.cpp"
  "fake/directory"
  "${CMAKE_SOURCE_DIR}/fake/directory/file.cpp"
  "${CMAKE_SOURCE_DIR}/fake/directory")
print(STATUS "Absolute path list: @apl@." ${path_list})
# Output:
#   -- Absolute path list: /full/path/to/src/main.cpp, /full/path/to/src, /full/path/to/src/main.cpp, /full/path/to/src, /full/path/to/fake/directory/file.cpp, /full/path/to/fake/directory, /full/path/to/fake/directory/file.cpp, /full/path/to/fake/directory.

# Message with rpl directive and various paths
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(path_list
  "src/main.cpp"
  "src"
  "${CMAKE_SOURCE_DIR}/src/main.cpp"
  "${CMAKE_SOURCE_DIR}/src"
  "fake/directory/file.cpp"
  "fake/directory"
  "${CMAKE_SOURCE_DIR}/fake/directory/file.cpp"
  "${CMAKE_SOURCE_DIR}/fake/directory")
print(STATUS "Relative path list: @rpl@." ${path_list})
# Output:
#   -- Relative path list: src/main.cpp, src, src/main.cpp, src, fake/directory/file.cpp, fake/directory, fake/directory/file.cpp, fake/directory.

# Message with sl directive
set(string_list
  "apple"
  "banana"
  "orange"
  "pineapple"
  "carrot"
  "strawberry"
  "pineapple"
  "grape"
  "lemon"
  "watermelon"
  "peach")
print(STATUS "String list: @sl@." ${string_list})
# Output:
#   -- String list: apple, banana, orange, pineapple, carrot, strawberry, pineapple, grape, lemon, watermelon.

print([<mode>] REL_PATHS [<file-path>...] [INDENT])

Record in the log each file from the specified <file-path> list after converting them to paths relative to the value of the PRINT_BASE_DIR variable. Each item is printed separated by a comma: item1, item2, .... This command is inspired by the message() command from CMake.

The REL_PATHS values may be relative or absolute paths, and may even refer to files or directories that does not exist on disk. Because of the use of cmake_path(), only syntactic aspects of paths are handled, there is no interaction of any kind with any underlying file system. A path may represent a non- existing path or even one that is not allowed to exist on the current file system or platform.

The optional <mode> argument determines the message type and may be any of the standard message modes supported by the message() command, such as STATUS, WARNING, ERROR, etc.

If the INDENT option is specified, the output message is indented by two spaces. This affects the indentation level of the printed message using the internal CMAKE_MESSAGE_INDENT stack.

Example usage:

# Print empty list
print(STATUS REL_PATHS)
# Output:
#   --

# Print empty list with indentation
print(STATUS REL_PATHS INDENT)
# Output:
#   --

# Print empty list with quote
print(STATUS REL_PATHS "")
# Output:
#   --

# Print list with indentation
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(path_list
  "${CMAKE_SOURCE_DIR}/src/main.cpp"
  "${CMAKE_SOURCE_DIR}/src/source_1.cpp"
  "${CMAKE_SOURCE_DIR}/src/source_2.cpp"
  "${CMAKE_SOURCE_DIR}/src/source_3.cpp"
  "${CMAKE_SOURCE_DIR}/src/source_4.cpp"
  "${CMAKE_SOURCE_DIR}/src/source_5.cpp"
  "${CMAKE_SOURCE_DIR}/src/sub_1/source_sub_1.cpp"
  "${CMAKE_SOURCE_DIR}/src/sub_2/source_sub_2.cpp")
print(STATUS REL_PATHS ${path_list} INDENT)
# Output:
#   --   src/main.cpp, src/source_2.cpp, src/source_3.cpp, src/source_4.cpp, src/source_5.cpp, src/sub_1/source_sub_1.cpp, src/sub_2/source_sub_2.cpp

# Print list with various paths
set(PRINT_BASE_DIR "${CMAKE_SOURCE_DIR}")
set(path_list
  "src/main.cpp"
  "src"
  "${CMAKE_SOURCE_DIR}/src/main.cpp"
  "${CMAKE_SOURCE_DIR}/src"
  "fake/directory/file.cpp"
  "fake/directory"
  "${CMAKE_SOURCE_DIR}/fake/directory/file.cpp"
  "${CMAKE_SOURCE_DIR}/fake/directory")
print(STATUS REL_PATHS ${path_list})
# Output:
#   -- src/main.cpp, src, src/main.cpp, src, fake/directory/file.cpp, fake/directory, fake/directory/file.cpp, fake/directory.

print([<mode>] STRINGS [<string>...] [INDENT])

Record in the log each string from the given <string> list. Each item is printed separated by a comma: item1, item2, .... This command is inspired by the message() command from CMake.

If specified, the optional <mode> keyword must be one of the standard message modes accepted by the message() command, such as STATUS, WARNING, ERROR, etc.

If the INDENT option is specified, the output message is indented by two spaces. This affects the indentation level of the printed message using the internal CMAKE_MESSAGE_INDENT stack.

Example usage:

# Print empty list
print(STATUS STRINGS)
# Output:
#   --

# Print empty list with indentation
print(STATUS STRINGS INDENT)
# Output:
#   --

# Print empty list with quote
print(STATUS STRINGS "")
# Output:
#   --

# Print list of strings with indentation
set(string_list
  "apple" "banana" "orange" "pineapple" "carrot"
  "strawberry" "pineapple" "grape" "lemon" "watermelon" "peach")
print(STATUS STRINGS ${string_list} INDENT)
# Output:
#   --   apple, banana, orange, pineapple, carrot, strawberry, pineapple, grape, lemon, watermelon, peach