运行和输出¶

食谱中的输出文本¶

使用 self.output 属性从食谱中输出文本。不要使用 Python 的 print() 函数。

error(self, msg: str, error_type: str = None)¶

表示发生了严重问题，阻止系统或应用程序继续正常运行。

通常，这表示执行流程中出现故障，例如服务崩溃或关键异常。请注意，如果用户已设置 core:warnings_as_errors 配置，当打印输出时会引发异常，以确保错误不会被忽视。

warning(self, msg: str, warn_tag: str = None)¶

突出显示潜在问题，这些问题虽然不会停止系统运行，但可能在未来或特定条件下引起问题。

警告表示应审查的异常情况，但不必导致操作立即停止。请注意，如果标签与 core:warnings_as_errors 配置中的模式匹配，并且未被跳过，则该警告将被升级为错误，并在打印输出时引发异常，以确保错误不会被忽视。

success(self, msg: str)¶

表示操作已成功完成。

此类型的消息有助于确认关键进程或任务已正确完成，这对于良好的应用程序监控至关重要。

highlight(self, msg: str)¶

标记或强调需要突出显示但并不一定表示成功或失败的重要事件或过程。

这些消息将用户或管理员可能关心的关键点吸引过来。

info(self, msg: str, fg: str = None, bg: str = None)¶

提供关于系统或正在进行的常规操作的信息。

信息消息是基础的，用于告知常见事件，例如进程的开始或完成，而无需暗示特定的问题或成就。

status(self, msg: str, fg: str = None, bg: str = None)¶

提供关于系统或正在进行的常规操作的信息。

信息消息是基础的，用于告知常见事件，例如进程的开始或完成，而无需暗示特定的问题或成就。

以下三个方法默认不显示，通常保留给需要更高详细程度的场景。您可以使用参数 -v、-vv 和 -vvv 分别显示它们。

verbose(self, msg: str, fg: str = None, bg: str = None)¶

显示额外和详细的信息，这些信息虽然不关键，但有助于更好地理解系统是如何工作的。

除非用户将日志级别设置为详细（例如，使用命令行中的 -v 选项），否则不会打印此消息。

它适合于获得更多上下文信息，而不会因过多的细节而使日志不堪重负。在比简单信息需要更多清晰度时非常有用。

debug(self, msg: str, fg: str = '\x1b[35m', bg: str = None)¶

具有高度详细程度，主要用于调试代码。

除非用户将日志级别设置为调试（例如，使用命令行中的 -vv 选项），否则不会打印此消息。

这些消息为开发人员提供了有用的信息，例如变量值或执行流程详细信息，以便跟踪错误或分析程序的行为。

trace(self, msg: str)¶

这是最极端的详细程度。

Trace 消息记录系统采取的每一个细微步骤，包括函数入口和退出、变量更改以及其他非常具体的事件。

除非用户将日志级别设置为 trace（例如，使用命令行中的 -vvv 选项），否则不会打印此消息。

当需要完全了解系统中发生的一切时使用，但由于可能生成大量信息，应谨慎使用。

这些输出函数只有在启动 Conan 时的详细程度与消息相同或更高时才会输出，因此使用 -vwarning 运行将输出对 warning() 和 error() 的调用，但不会输出 info()（此外，highlight() 和 success() 方法具有 -vnotice 详细程度级别）。

请注意，这些方法会再次返回输出对象，因此您可以根据需要链式调用输出。

使用 core:warnings_as_errors 配置，您可以让 Conan 在打印错误或匹配任何给定模式的已标记警告时引发异常。这对于确保食谱不会打印意外的警告或错误非常有用。此外，您还可以使用 core:skip_warnings 配置来跳过哪些警告会触发异常。

# Raise an exception if any warning or error is printed
core:warnings_as_errors=['*']
# But skip the deprecation warnings
core:skip_warnings=['deprecated']

这两个配置都接受一个模式列表，用于匹配警告标签。可以使用特殊的 unknown 值来匹配任何没有标签的警告。

要标记警告，请在食谱中使用 warning() 方法的 warn_tag 参数。

self.output.warning("Extra warning", warn_tag="custom_tag")

注意

自定义命令和工具可以自由地实例化自己的 ConanOutput 对象。

一些方法具有可选的 fg 和 bg 参数，这些是文本前景色和背景色的代码，在 conan.api.output.Color 类中可用。

self.output.info("This is a message", fg=Color.BLUE, bg=Color.YELLOW)

运行命令¶

食谱和助手可以使用 self.run() 方法在激活适当环境的调用注入的同时运行系统命令，并在发生错误时引发异常，以确保命令错误不会被忽视。它还会用命令包装器插件的结果包装命令。

run(self, command: str, stdout=None, cwd=None, ignore_errors=False, env='', quiet=False, shell=True, scope='build', stderr=None)¶

在当前包上下文中运行命令。

参数:

command – 要运行的命令。
stdout – 用于写入命令输出的输出流。如果为 None，则默认为标准输出流。
stderr – 用于写入命令错误输出的错误输出流。如果为 None，则默认为标准错误流。
cwd – 运行命令的当前工作目录。
ignore_errors – 如果为 True，则命令返回非零退出码时不会引发错误。
env – 要使用的环境文件。如果为空，则默认为 "conanbuild"（当 scope 为 build 时）或 "conanrun"（当 scope 为 run 时）。如果显式设置为 None，则不会应用任何环境文件，这对于不需要任何环境的命令很有用。
quiet – 如果为 True，则抑制命令的输出。
shell – 如果为 True，则在 shell 中运行命令。这会传递给底层的 Popen 函数。
scope – 命令的作用域，可以是 "build" 或 "run"。

使用 stdout 和 stderr 参数将命令的输出重定向到类文件对象而不是控制台。

# Redirect stdout to a file
with open("ninja_stdout.log", "w") as stdout:
    # Redirect stderr to a StringIO object to be able to read it later
    stderr = StringIO()
    self.run("ninja ...", stdout=stdout, stderr=stderr)