运行和输出¶
食谱(recipes)输出文本¶
使用 self.output
属性从食谱中输出文本。请不要使用 Python 的 print()
函数。self.output
属性具有以下方法来表示打印消息的级别
trace(msg)
debug(msg)
verbose(msg)
status(msg)
info(msg)
highlight(msg)
success(msg)
warning(msg, warn_tag=None)
error(msg)
这些输出函数仅在启动 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")
这些函数从不具体到最具体的常用顺序是
- error(msg):
表示发生了阻止系统或应用程序继续正常运行的严重问题。通常,这表示正常执行流中的故障,例如服务崩溃或关键异常。
- warning(msg, warn_tag=None):
突出显示一个潜在问题,它虽然不会停止系统,但将来或在某些条件下可能会导致问题。警告表示应审查的异常情况,但不一定会立即中止操作。
- success(msg):
显示操作已成功完成。此类消息有助于确认关键过程或任务已正确完成,这对于良好的应用程序监控至关重要。
- highlight(msg):
标记或强调需要突出的重要事件或过程,但并不一定表示成功或错误。这些消息会引起用户或管理员对可能相关的关键点的注意。
- info(msg):
提供有关系统或正在进行的操作的一般信息。信息消息是基本的,用于告知常见事件,如进程的启动或完成,而不暗示特定的问题或成就。
- status(msg):
报告系统或正在进行的操作的当前状态。状态消息提供关于某事如何工作的更新,通常是实时更新,以提供过程进度或情况的清晰视图。
以下三种方法默认不显示,通常保留用于需要更高详细程度的场景。您可以使用参数 -v
、-vv
和 -vvv
分别显示它们。
- verbose(msg):
显示附加的详细信息,这些信息虽然不关键,但对于更好地理解系统如何工作可能很有用。它适用于在不通过过多细节使日志过载的情况下获得更多上下文。当需要比简单信息更清晰的说明时,这很有用。
- debug(msg):
具有高度详细性,主要用于代码调试。这些消息为开发人员提供有用信息,例如变量值或执行流详情,以追踪错误或分析程序行为。
- trace(msg):
这是最极端的详细程度级别。跟踪消息记录系统执行的每一个小步骤,包括函数进入和退出、变量更改以及其他非常具体的事件。当需要完全了解系统中发生的一切时使用它,但由于它可能生成大量信息,因此应谨慎使用。
运行命令¶
run(self, command, stdout=None, cwd=None, ignore_errors=False, env="", quiet=False, shell=True, scope="build", stderr=None)
self.run()
是一个辅助函数,用于运行系统命令,同时注入激活相应环境的调用,并在发生错误时抛出异常,以确保命令错误不会被忽视。它还会使用 命令包装器插件 的结果来包装命令。
command
应指定为传递给系统 shell 的字符串。当参数
quiet
设置为 true 时,self.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)