Version 0.x Modules Output Helpers

February 13, 2025 at 1:11 AM Edit on GitHub

Output Helpers

Table of Contents

output()

Outputs a message to stdout or stderr (message mode specific). Behind the scene, the output() function is a wrapper for cmake’s message().

It accepts the following parameters:

  • < message >: string, variable or list message to output.
  • < mode >: (option), cmake message mode, e.g. WARNING, NOTICE, STATUS, …etc. Defaults to NOTICE is mode is not specified.
  • OUTPUT: (optional), output variable. If specified, message is assigned to variable, instead of being printed to stdout or stderr.
  • LABEL: (optional), A label to display before the message.
  • LABEL_FORMAT: (optional), A format string in which the actual label is inserted. Use the %label% token, in which the actual label is inserted.
  • LIST_SEPARATOR: (optional), Separator to used, if a list variable is given as message. Defaults to \n (newline).

Example

output("Building package assets" NOTICE LABEL "info")

The above example will print the following, using cmake’s NOTICE mode.

info: Building package assets

Capture Output

If you specify a variable for the OUTPUT parameter, then your message is assigned to that variable, instead of being printed in the console.

output("Building package assets" NOTICE OUTPUT result)

message("result = ${result}")

result = Building package assets

Note

When you specify the OUTPUT parameter, then the message < mode > argument is ignored. As such, the following will never yield an error:

# FATAL_ERROR message mode used, but OUTPUT specified... this never fails!
output("Should fail..." FATAL_ERROR OUTPUT output)

# Message is printed...
message("${output} but doesn't")

Label & Label Format

When you specify a LABEL, then it will be printed before the actual message. By default, the format for the rendered label is: %label%: , where the %label% token is where the label is injected. You can customise this format, by specifying the LABEL_FORMAT parameter.

output("Building package assets" NOTICE LABEL "✓" LABEL_FORMAT "[ %label% ] ")

[ ✓ ] Building package assets

You can also change the default label format, by setting the RSP_DEFAULT_LABEL_FORMAT property.

set(RSP_DEFAULT_LABEL_FORMAT "( %label% ) - " CACHE STRING "Default label format...")

# ...Later in your cmake script...
output("Building package assets" NOTICE LABEL "ok")

( ok ) - Building package assets

Troubleshooting

If your custom label format does not take effect, then it is most likely because RSP_DEFAULT_LABEL_FORMAT is cached property.

Consider setting RSP_DEFAULT_LABEL_FORMAT before you include the rsp/output module, or force cache the property.

Lists

output() is also able to print lists. By default, each item is printed on a new line.

set(my_list "a;b;c")

output(my_list)

a
b
c

Use the LIST_SEPARATOR parameter to use a custom list item separator:

set(my_list "a;b;c")

output(my_list LIST_SEPARATOR ", ")

a, b, c