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>

Qt Creator Coding Rules

Copyright © The Qt Company Ltd. and other contributors. 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.