1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
/****************************************************************************
**
** Copyright (c) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/
/*!
\contentspage{index.html}{Qt Creator}
\page external-tool-spec.html
\nextpage coding-style.html
\title External Tool Specification Files
An external tool specification file describes a tool that can be run from
the \gui { 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.
\section1 File Name
\c {<yourtoolname>.xml}
\section1 Location
User specific tools are located in \c {$HOME/.config/QtProject/qtcreator/externaltools}
on Mac and Linux, and in \c {%APPDATA%\QtProject\qtcreator\externaltools} on Windows.
System wide tools are located in \c {<Qt Creator install>/share/qtcreator/externaltools}
on Windows and Linux, and in \c {Qt Creator.app/Contents/Resources/externaltools} on Mac.
\section1 File Format
External tool specifications are XML files with the following structure.
\section2 Main Tag
The root tag is \c externaltool. It has the mandatory attribute \c id.
\table
\header
\o Tag
\o Meaning
\row
\o externaltool
\o Root element in the XML file that specifies an external tool.
\endtable
\table
\header
\o Attribute
\o Meaning
\row
\o id
\o A string that identifies the external tool.
Two tools cannot have the same id. Required.
\endtable
\section2 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
\c description, \c displayname, and \c category tags that contain language
codes.
\table
\header
\o Tag
\o Meaning
\row
\o description
\o Short, one-line description of what the tool is for. Required.
\row
\o displayname
\o Name to show in the menu item for the tool. Required.
\row
\o category
\o Name of the category to show the tool in.
This is the name of the sub menu of the \c { Tools > External }
menu where the tool is placed. For example, specify the value
\c "Text" to display the tool in the \c { Tools > External > Text }
menu. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\row
\o xml:lang
\o Language code (such as, \c "en" or \c "de") of the language that is used for
the description, display name, or category. Optional.
\endtable
\section2 Executable Specification Tag
You must add an \c executable tag under the root tag, that specifies the
executable to run, optional arguments, and how to handle the output.
\table
\header
\o Tag
\o Meaning
\row
\o executable
\o Encloses subtags that specify what to run and which parameters to use. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\row
\o output
\o Specifies how to handle the tool's standard output stream.
Defaults to \c ShowInPane. Optional.
\row
\o error
\o Specifies how to handle the tool's standard error stream.
Defaults to \c ShowInPane. Optional.
\row
\o modifiesdocument
\o 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: \c "yes" or \c "no" (defaults to \c "no").
Optional.
\endtable
The \c executable tag allows the following subtags. You must specify at least
one \c path. All subtags can contain special \l{Qt Creator Variables}.
\table
\header
\o Subtag
\o Meaning
\row
\o path
\o 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.
\row
\o arguments
\o 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.
\row
\o workingdirectory
\o The working directory for the executable. Optional.
\row
\o input
\o A potentially multiline string that is passed to the tool via standard input stream.
\endtable
\section1 Example
\code
<?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>
\endcode
*/
|
