external-tool-spec.qdoc 6.73 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27
**
****************************************************************************/

/*!
    \page external-tool-spec.html
28
    \nextpage coding-style.html
29

30
    \title External Tool Specification Files
31

32
    An external tool specification file describes a tool that can be run from
33
    the \uicontrol { Tools > External } menu.
34 35
    It specifies the name of the tool, the executable to run, optional
    arguments, and how to handle the output from the tool.
36 37 38 39 40 41 42

    \section1 File Name

    \c {<yourtoolname>.xml}

    \section1 Location

43 44
    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.
45 46 47 48 49 50 51 52 53 54

    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

55
    The root tag is \c externaltool. It has the mandatory attribute \c id.
56 57 58

    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
59 60
        \li Tag
        \li Meaning
61
    \row
Tobias Hunger's avatar
Tobias Hunger committed
62 63
        \li externaltool
        \li Root element in the XML file that specifies an external tool.
64 65 66
    \endtable
    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
67 68
        \li Attribute
        \li Meaning
69
    \row
Tobias Hunger's avatar
Tobias Hunger committed
70 71 72
        \li id
        \li A string that identifies the external tool.
            Two tools cannot have the same id. Required.
73 74 75 76
    \endtable

    \section2 Description Tags

77 78 79 80
    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.
81 82 83

    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
84 85
        \li Tag
        \li Meaning
86
    \row
Tobias Hunger's avatar
Tobias Hunger committed
87 88
        \li description
        \li Short, one-line description of what the tool is for. Required.
89
    \row
Tobias Hunger's avatar
Tobias Hunger committed
90 91
        \li displayname
        \li Name to show in the menu item for the tool. Required.
92
    \row
Tobias Hunger's avatar
Tobias Hunger committed
93 94 95 96 97 98
        \li category
        \li 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.
99 100 101
    \endtable
    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
102 103
        \li Attribute
        \li Meaning
104
    \row
Tobias Hunger's avatar
Tobias Hunger committed
105 106 107
        \li xml:lang
        \li Language code (such as, \c "en" or \c "de") of the language that is used for
            the description, display name, or category. Optional.
108 109 110 111
    \endtable

    \section2 Executable Specification Tag

112 113
    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.
114 115 116

    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
117 118
        \li Tag
        \li Meaning
119
    \row
Tobias Hunger's avatar
Tobias Hunger committed
120 121
        \li executable
        \li Encloses subtags that specify what to run and which parameters to use. Required.
122 123 124
    \endtable
    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
125 126
        \li Attribute
        \li Meaning
127
    \row
Tobias Hunger's avatar
Tobias Hunger committed
128 129
        \li output
        \li Specifies how to handle the tool's standard output stream.
130
           Defaults to \c ShowInPane. Optional.
131
    \row
Tobias Hunger's avatar
Tobias Hunger committed
132 133 134
        \li error
        \li Specifies how to handle the tool's standard error stream.
            Defaults to \c ShowInPane. Optional.
135
    \row
Tobias Hunger's avatar
Tobias Hunger committed
136 137 138 139 140 141 142
        \li modifiesdocument
        \li 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.
143 144
    \endtable

145
    The \c executable tag allows the following subtags. You must specify at least
146 147 148 149
    one \c path. All subtags can contain special \l{Qt Creator Variables}.

    \table
    \header
Tobias Hunger's avatar
Tobias Hunger committed
150 151
        \li Subtag
        \li Meaning
152
    \row
Tobias Hunger's avatar
Tobias Hunger committed
153 154 155 156 157 158 159
        \li path
        \li 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.
160
    \row
Tobias Hunger's avatar
Tobias Hunger committed
161 162 163 164 165
        \li arguments
        \li 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.
166
    \row
Tobias Hunger's avatar
Tobias Hunger committed
167 168
        \li workingdirectory
        \li The working directory for the executable. Optional.
169
    \row
Tobias Hunger's avatar
Tobias Hunger committed
170 171
        \li input
        \li A potentially multiline string that is passed to the tool via standard input stream.
172 173 174 175 176 177 178 179
    \endtable

    \section1 Example

    \code
<?xml version="1.0" encoding="UTF-8"?>
<externaltool id="sort">
    <description>Sorts the selected text</description>
180
    <description xml:lang="de">Sortiert den ausgewaehlten Text</description>
181 182 183 184 185 186 187 188 189 190 191 192
    <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
*/