- Extending Qt Creator Manual
- External Tool Specification Files
- Extending Qt Creator Manual 13.0.0

Qt Creator Coding Rules

# 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>