运行与输出¶

从 Recipe 输出文本¶

使用 self.output 属性从 Recipe 中输出文本。不要使用 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 在打印错误或与给定模式匹配的已标记警告时引发异常。这有助于确保 Recipe 没有打印意外的警告或错误。此外，您还可以使用 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 值可以用来匹配任何没有标签的警告。

要标记警告，请在 Recipe 中使用 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)

运行命令¶

Recipe 和辅助函数可以使用 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)