External Tool Specification Files
An external tool specification file describes a tool that can be run from the Tools > External menu. It specifies the name of the tool, the executable to run, optional arguments, and how to handle the output from the tool.
File Name
<yourtoolname>.xml
Location
User specific tools are located in $HOME/.config/QtProject/qtcreator/externaltools
on Mac and Linux, and in %APPDATA%\QtProject\qtcreator\externaltools
on Windows.
System wide tools are located in <Qt Creator install>/share/qtcreator/externaltools
on Windows and Linux, and in Qt Creator.app/Contents/Resources/externaltools
on Mac.
File Format
External tool specifications are XML files with the following structure.
Main Tag
The root tag is externaltool
. It has the mandatory attribute id
.
Tag | Meaning |
---|---|
externaltool | Root element in the XML file that specifies an external tool. |
Attribute | Meaning |
---|---|
id | A string that identifies the external tool. Two tools cannot have the same id. Required. |
Description Tags
You must specify a description, display name, and category for the tool. You can translate their values into different languages by adding multiple description
, displayname
, and category
tags that contain language codes.
Tag | Meaning |
---|---|
description | Short, one-line description of what the tool is for. Required. |
displayname | Name to show in the menu item for the tool. Required. |
category | Name of the category to show the tool in. This is the name of the sub menu of the Tools > External menu where the tool is placed. For example, specify the value "Text" to display the tool in the Tools > External > Text menu. Required. |
Attribute | Meaning |
---|---|
xml:lang | Language code (such as, "en" or "de" ) of the language that is used for the description, display name, or category. Optional. |
Executable Specification Tag
You must add an executable
tag under the root tag, that specifies the executable to run, optional arguments, and how to handle the output.
Tag | Meaning |
---|---|
executable | Encloses subtags that specify what to run and which parameters to use. Required. |
Attribute | Meaning |
---|---|
output | Specifies how to handle the tool's standard output stream. Defaults to ShowInPane . Optional. |
error | Specifies how to handle the tool's standard error stream. Defaults to ShowInPane . Optional. |
modifiesdocument | Specifies whether Qt Creator should expect changes to the current document. If this flag is set, Qt Creator prompts users to save changes to the current document before running the tool, and silently reloads the current document after the tool has finished. Possible values are: "yes" or "no" (defaults to "no" ). Optional. |
The executable
tag allows the following subtags. You must specify at least one path
. All subtags can contain special Qt Creator variables.
Subtag | Meaning |
---|---|
path | File path to the executable to run, including filename. If you specify the executable name without a path, Qt creator checks the system PATH environment variable for a path to the executable. You can specify the path multiple times. Qt Creator tries to resolve the references in the given order and runs the first executable that it finds. Required. |
arguments | Command-line arguments for the executable. Specify the string in the same format (with respect to quoting and argument splitting, for example) as you would specify it on the command line of the platform the tool runs on. Optional. |
workingdirectory | The working directory for the executable. Optional. |
input | A potentially multiline string that is passed to the tool via standard input stream. |
Example
<?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>
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.