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.

TagMeaning
externaltoolRoot element in the XML file that specifies an external tool.
AttributeMeaning
idA 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.

TagMeaning
descriptionShort, one-line description of what the tool is for. Required.
displaynameName to show in the menu item for the tool. Required.
categoryName 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.
AttributeMeaning
xml:langLanguage 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.

TagMeaning
executableEncloses subtags that specify what to run and which parameters to use. Required.
AttributeMeaning
outputSpecifies how to handle the tool's standard output stream. Defaults to ShowInPane. Optional.
errorSpecifies how to handle the tool's standard error stream. Defaults to ShowInPane. Optional.
modifiesdocumentSpecifies 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.

SubtagMeaning
pathFile 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.
argumentsCommand 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.
workingdirectoryThe working directory for the executable. Optional.
inputA 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>