Commit 8c550932 authored by con's avatar con
Browse files

Add description of the external tool specification files.

parent 69d2cc59
......@@ -43,6 +43,7 @@ equals(QMAKE_DIR_SEP, /) { # unix, mingw+msys
HELP_FILES = $$PWD/qtcreator-dev.qdocconf
HELP_DEP_FILES = $$PWD/qtcreator-api.qdoc \
$$PWD/coding-style.qdoc \
$$PWD/external-tool-spec.qdoc \
$$PWD/qtcreator-dev.qdoc \
$$PWD/qtcreator-dev.qdocconf
......
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/
/*!
\page external-tool-spec.html
\title External Tool Specification Files
\section1 Description
File that describes a tool that can be run from the \gui { Tools > External } menu.
It specifies the name, the binary to run, what parameters the binary should get
and what should happen with the tool's output.
\section1 File Name
\c {<yourtoolname>.xml}
\section1 Location
User specific tools are located in \c {$HOME/.config/Nokia/qtcreator/externaltools}
on Mac and Linux, and in \c {%APPDATA%\Nokia\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 a mandatory attribute \c id.
\table
\header
\o Tag
\o Meaning
\row
\o externaltool
\o Root element in a external tool's xml file.
\endtable
\table
\header
\o Attribute
\o Meaning
\row
\o id
\o This is a string that is used as an identifier for the external tool.
There can be no two tools with the same id. Required.
\endtable
\section2 Description Tags
It is mandatory that you give your tool a description, display name and category.
All three can optionally be translated into different languages by adding multiple
\c description, \c displayname and \c category tags with different language attributes.
\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 under the \c { Tools > External } menu which
will contain this tool. E.g. a value of \c "Text" for the category will
put the tool's menu item in the \c { Tools > External > Text } menu. Required.
\endtable
\table
\header
\o Attribute
\o Meaning
\row
\o xml:lang
\o Language code (e.g. \c "en" or \c "de") of the lanugage that is used for
the description, display name, or category. Optional.
\endtable
\section2 Executable Specification Tag
It is mandatory to add a \c executable tag under the root tag, that specifies what to run,
the parameters given to the process, and what to do with 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 what to do with the tool's standard output stream.
See \l{Output Behavior Flags} below. Defaults to \c ShowInPane. Optional.
\row
\o error
\o Specifies what to do with the tool's standard error stream.
See \l{Output Behavior Flags} below. Defaults to \c ShowInPane. Optional.
\row
\o modifiesdocument
\o Spefifies if Qt Creator should expect a change of the current document.
If this flag is set, Qt Creator asks for saving the current document
before running the tool (if the current document was modified),
and silently reloads the current document after the tool has finished.
\c "yes" or \c "no" (defaults to \c "no"). Optional.
\endtable
The \c executable tag allows the following subtags, it is only required to 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 the executable's file name.
If only the executable name is given without a path, it is looked for in the
system's PATH environment variable. Can be specified multiple times,
Qt Creator then tries to resolve them in the given order and runs the first
one that is found. Required.
\row
\o arguments
\o Command line arguments for the executable. This string is in the form
(with respect to e.g. quoting and argument splitting) how it would
be specified on the command line of the platform the tool runs on. Optional.
\row
\o workingdirectory
\o The working directory that should be set 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 ausgewählten 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
*/
......@@ -243,6 +243,7 @@
\o \l{External Tool Specification Files}
\o \l{Custom Wizard Specification Files}
\o \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Highlight Definition Files}
\o \l{Qt Creator Variables}
\o \l{User Interface Text Guidelines}
\o \l{Qt Creator Coding Rules}
\o \l{Qt Creator API Reference}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment