Next: Executing external tools, Previous: Defining default command line, Up: Adding support for new tools
The user has to be able to specify which switches to use with the tool. If the tool is simply called through custom menus, you might want to hard code some or all of the switches. However, in the general case it is better to use the project properties editor, so that project-specific switches can be specified.
This is what GPS does by default for Ada, C and C++. You can find in the GPS installation directory how the switches for these languages are defined in an XML file. These provide extended examples of the use of customization files.
The switches editor in the project properties editor provides a powerful interface to the command line, where the user can edit the command line both as text and through GUI widgets.
The switches are declared through the <switches>
tag in the
customization file, which must be a child of a <tool>
tag as described
above.
This <switches>
tag accepts the following attributes:
lines (default value is 1)
columns (default value is 1)
separator (default value is "")
" "
rather than " "
,
since XML parser must normalize the latter to the empty string when reading
the XML file.
This <switches>
tag can have any number of child tag, among the
following. They can be repeated multiple times if you need several check boxes.
For consistency, most of these child tags accept attributes among the
following:
line (default value is 1)
lines
above.
column (default value is 1)
columns
above.
label (mandatory)
switch (mandatory)
combo
and spin
below.
This switch shouldn't contain any space.
tip (default value is empty)
min (default value is 1)
<spin>
tags, and indicates the minimum
value authorized for that switch.
max (default value is 1)
<spin>
tags, and indicates the maximum
value authorized for that switch.
default (default value is 1)
<spin>
tags. See the description below.
noswitch (default is empty)
<combo>
tags, and described below.
nodigit (default is empty)
<combo>
tags, and described below.
value (mandatory)
<combo-entry>
tags.
separator (default is the value given to <switches>
<switches>
.
Here are the valid children for <switches>
:
<title>
line
and column
attributes, is used
to give a name to a specific frame.
The value of the tag is the title itself. You do not have to specify
a name, and this can be left to an empty value.
Extra attributes for <title>
are:
line-span (default value is 1)
column-span (default value is 1)
<check>
line
, column
, label
, switch
and tip
attributes. It creates a toggle button. When the latter is
active, the text defined in the switch attribute is added as is
to the command line. This tag doesn't have any value or child tags.
<spin>
line
, column
, label
, switch
,
tip
, min
, max
, separator
and default
attributes.
This switch will add the contents of the switch
attribute followed by
the current numeric value of the widget to the command line. This is typically
used to indicate indentation length for instance.
If the current value of the widget is equal to the default
attribute,
then nothing is added to the command line.
<radio>
line
and column
attributes. It groups any
number of children, each of which is associated with its own switch. However,
only one of the children can be selected at any given time.
The children must have the tag radio-entry
. This tag accepts the
attributes label
, switch
and tip
. As a special case,
the switch attribute can have an empty value ("") to indicate this is the
default switch to use in this group of radio buttons.
<field>
line
, column
, label
, switch
,
separator
and tip
attributes. This tag describes a text edition
field, which can
contain any text the user types. This text will be prefixed by the value of
the switch
attribute, and the separator (by default nothing). If no text
is entered in the field
by the user, nothing is put on the command line.
This tag accepts two extra attributes:
as-directory (optional)
as-file (optional)
as-directory
, but opens a dialog to
select a file instead of a directory. If both attributes are set to "true",
the user will select a file.
<combo>
line
, column
, label
, switch
,
tip
, noswitch
, separator
and nodigit
attributes.
The text inserted in the command line is the text from the switch
attribute, concatenated with the text of the value
attribute for the
currently selected entry. If the value of the current entry is the same
as that of the nodigit
attribute, then only the text of the
switch
attribute is put on the command line. This is in fact necessary
to interpret the gcc switch "-O" as "-O1".
If the value of the current entry is that of the noswitch
attribute,
then nothing is put in the command line.
The tag <combo>
accepts any number of combo-entry
children tags,
each of which accepts the label
and value
attribute.
<popup>
line
, column
, label
, lines
and columns
attributes. This displays a simply button that, when
clicked, displays a dialog with some extra switches. This dialog, just as the
switches editor itself, is organizes into lines and columns of frames, the
number of which is provided by the lines
and columns
attributes.
This tag accepts any number of children, which are the same as the
<switches>
attribute itself.
<dependency>
It has its own set of attributes:
master-page master-switch
<check>
or <field>
. If the check button is selected, it forces the
selection of the slave check button. Likewise, if the field is set to
any value, it forces the selection of the slave.
slave-page slave-switch
<check>
.
master-status slave-status
<expansion>
It is easier to explain it through an example. Specifying the GNAT switch "-gnaty" is equivalent to specifying "-gnatyabcefhiklmnprst". This is in fact a style check switch, with a number of default values. But it is also equivalent to decomposing it into several switches, as in "-gnatya", "-gnatyb",... With this information, GPS will try to keep the command line length as short as possible, to keep it readable.
Both these aspects are defined in a unique <expansion>
tag, which
accepts two attributes: switch
is mandatory, and alias
is
optional. Alias contains the text "-gnatyabcefhiklmnprst" in our example.
It also accepts any number of <entry>
children, each has a mandatory
switch
access. The set of all these children define the expanded
equivalent of the switch. In our example, we need one <entry>
child
for "-gnatya", one for "-gnatyb",....
The exact algorithm used by GPS is the following:
switch
attribute that matches exactly, then it is replaced
by all the switches given in the <entry>
children).
If we have <expansion switch="-gnatwa"> <entry switch="-gnatwc" /> <entry switch="-gnatwd" /> </expansion> then any occurrence of "-gnatwa" on the command line is expanded to "-gnatwc -gnatwd"
switch
attribute of an <expansion>
node,
then it is grouped with all other similar switches.
if the XML file contains <expansion switch="-gnatw" /> then the command line "-gnatwc -gnatt -gnatwd" is transformed into "-gnatwcd -gnatt", grouping the switches that start with "-gnatw".
alias
attributes of the <expansion>
nodes, and
replaced appropriately.
if the XML file contains <expansion switch="-gnatwa" alias="-gnatwcd" /> then the command line generated at the second step is further transformed into "-gnatwa -gnatt".
This rather complex mechanism allows one to either use the various buttons and GUI widgets to edit the switches, or to manually edit the command line.