外部工具规范文件

外部工具规范文件描述了一个可以从工具 > 外部菜单中运行的工具。它指定了工具的名称、要运行的可执行文件、可选参数以及如何处理工具的输出。

文件名

<yourtoolname>.xml

位置

特定于用户的高级工具位于 Mac 和 Linux 上的 $HOME/.config/QtProject/qtcreator/externaltools，Windows 上为 %APPDATA%\QtProject\qtcreator\externaltools。

系统范围的工具位于 Windows 和 Linux 上的 <Qt Creator install>/share/qtcreator/externaltools，Mac 上为 Qt Creator.app/Contents/Resources/externaltools。

文件格式

外部工具规范是具有以下结构的 XML 文件。

主标签

根标签是 externaltool。它有一个必须的属性 id。

标签	含义
externaltool	XML 文件中的根元素，用于指定外部工具。

属性	含义
id	一个字符串，用于识别外部工具。两个工具不能有相同的 id。必需。

描述标签

您必须指定工具的描述、显示名称和类别。您可以通过添加包含语言代码的多个 description、displayname 和 category 标签来将这些值翻译成不同的语言。

标签	含义
description	关于工具用途的简短一句话描述。必需。
displayname	用于菜单项的工具名称。必需。
category	用于显示工具的类别名称。这是放置工具的 `工具 > 外部` 菜单的子菜单名称。例如，指定值 `"文本"` 使工具显示在 `工具 > 外部 > 文本` 菜单中。必需。

属性	含义
xml:lang	用于描述、显示名称或类别的语言代码（例如，`"en"` 或 `"de"`）。可选。

可执行规范标签

您必须在根标签下添加一个 executable 标签，指定要运行的可执行文件、可选参数以及如何处理输出。

标签	含义
executable	包含子标签，指定要运行的内容和要使用的参数。必需。

属性	含义
output	指定如何处理工具的标准输出流。默认为 `ShowInPane`。可选。
error	指定如何处理工具的标准错误流。默认为 `ShowInPane`。可选。
modifiesdocument	指定 Qt Creator 是否应该期望当前文档的更改。如果设置此标志，Qt Creator 将在运行工具之前提示用户保存对当前文档的更改，并在工具完成后默默地重新加载当前文档。可能的值是：`"yes"` 或 `"no"`（默认为 `"no"`）。可选。

可执行标签允许以下子标签。您必须指定至少一个路径。所有子标签都可以包含特殊的Qt Creator变量。

子标签	含义
path	要运行的程序的文件路径，包括文件名。如果您只指定程序名而不指定路径，Qt Creator会检查系统的PATH环境变量以查找程序的路径。您可以多次指定路径。Qt Creator将按照给定顺序尝试解析引用，并运行找到的第一个程序。必选。
arguments	程序的命令行参数。按照与您在运行该工具的平台的命令行中指定的相同格式（关于引号和参数拆分等）指定字符串。可选。
workingdirectory	程序的当前工作目录。可选。
input	传递给工具的潜在多行字符串，通过标准输入流。

实例

<?xml version="1.0" encoding="UTF-8"?>
<externaltool id="sort">
    <description>Sorts the selected text</description>
    <description xml:lang="de">Sortiert den ausgewaehlten Text</description>
    <displayname>Sort Selection</displayname>
    <displayname xml:lang="de">Auswahl Sortieren</displayname>
    <category>Text</category>
    <category xml:lang="de">Text</category>
    <executable output="replaceselection" error="ignore">
        <path>sort</path>
        <input>%{CurrentDocument:Selection}</input>
        <workingdirectory>%{CurrentDocument:Path}</workingdirectory>
    </executable>
</externaltool>

Qt Creator 代码规范