Next: Executing external tools, Previous: Defining default command line, Up: Adding support for new tools [Index]
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)
The switches in the project properties editor are organized into boxes, each surrounded by a frame, optionally with a title. This attribute specifies the number of rows of such frames.
columns (default value is 1)
This attribute specifies the number of columns of frames in the project properties page.
separator (default value is "")
This attribute specifies the default character that should go between a switch
and its value, to distinguishes cases like "-a 1", "-a1" and "-a=1". This can
be overridden separately for each switch. Note that if you want the separator
to be a space, you must use the value " "
rather than " "
,
since XML parser must normalize the latter to the empty string when reading
the XML file.
use_scrolled_window (Default value is false)
This optional attribute specifies if the boxes of the project editor are placed into scrolled window. This is particularily useful if the number of displayed switches if important.
show_command_line (Default value is true)
If this attribute is set to "false", the command line will not be displayed in the project properties editor. This can be used for instance if you only want users to edit it through the buttons and other widgets, and not directly.
switch_char (Default value is "-")
This is the leading character of command line arguments that indicate they are considered as switches. Arguments not starting with this character will be kept as is, and cannot have graphical widgets associated with them
sections (Default value is empty)
This is a space separated list of switches delimiting a section (such as "-bargs -cargs -largs"). A section of switches is a set of switches that need to be grouped together and preceded by a specific switch. Sections are always placed at the end of the command line, after regular switches.
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)
This indicates the row of the frame that should contain the switch. See the
description of lines
above.
column (default value is 1)
This indicates the column of the frame that should contain the switch. See the
description of columns
above.
label (mandatory)
This is the label which is displayed in the graphical interface
switch (mandatory)
This is the text that should be put on the command line if that switch is
selected. Depending on its type, a variant of the text might be put instead,
see the description of combo
and spin
below.
This switch shouldn’t contain any space.
switch-off (default value is empty)
This attribute is used for <check>
tags, and indicates the switch
used for deactivating the concerned feature. This is useful for features that
are on by default on certain occasions, but can be individually deactivated.
section (default value is empty)
This is the switch section delimiter (such as "-cargs"). See the ’sections’ attribute of the tag ’switches’ for more information.
tip (default value is empty)
This is the tooltip which describes that switch more extensively. It is
displayed in a small popup window if the user leaves the mouse on top of
the widget. Note that tags accepting the tip attribute also accept a single
child <tip>
whose value will contain the text to be displayed. The
advantage of the latter is that the text formatting is then kept.
before (default value is "false")
This attribute is used to indicate that a switch needs to be always inserted at the begining of the command line.
min (default value is 1)
This attribute is used for <spin>
tags, and indicates the minimum
value authorized for that switch.
max (default value is 1)
This attribute is used for <spin>
tags, and indicates the maximum
value authorized for that switch.
default (default value is 1)
This attribute is used for <check>
and <spin>
tags. See the
description below.
noswitch (default is empty)
This attribute is only valid for <combo>
tags, and described below.
nodigit (default is empty)
This attribute is only valid for <combo>
tags, and described below.
value (mandatory)
This attribute is only valid for <combo-entry>
tags.
separator (default is the value given to <switches>
This attribute specifies the separator to use between the switch and its value.
See the description of this attribute for <switches>
.
Here are the valid children for <switches>
:
<title>
This tag, which accepts the 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)
This indicates how many rows the frame should span. If this is set to 0, then the frame is hidden from the user. See for instance the Ada or C switches editor.
column-span (default value is 1)
This indicates how many columns the frame should span. If this is set to 0, then the frame is hidden from the user. See for instance the Ada or C switches editor.
<check>
This tag accepts the line
, column
, label
, switch
,
switch-off
, section
, default
, before
and tip
attributes.
This tag doesn’t have any value. An optional <tip>
child can be present.
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. The switch can be also
activated by default (default
attribute is "on" or "true"). In this
case, deactivating the switch will add switch-off
to the command line.
<spin>
This tag accepts the line
, column
, label
, switch
,
section
, tip
, min
, max
, separator
and
default
attributes.
This tag doesn’t have any value. An optional <tip>
child can be present.
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>
This tag accepts the 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
, section
, before
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.
This tag doesn’t have any value. An optional <tip>
child can also be
present.
<field>
This tag accepts the line
, column
, label
, switch
,
section
, separator
, before
and tip
attributes.
This tag doesn’t have any value. An optional <tip>
child can be present.
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)
If this attribute is specified and set to "true", then an extra "Browse" button is displayed, so that the user can easily select a directory.
as-file (optional)
This attribute is similar to 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>
This tag accepts the line
, column
, label
, switch
,
section
, before
, tip
, noswitch
, separator
and nodigit
attributes.
The tag <combo>
accepts any number of combo-entry
children tags,
each of which accepts the label
and value
attribute. An optional
<tip>
child can also be present.
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.
<popup>
This tag accepts the 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>
This tag is used to describe a relationship between two switches. It is used for instance when the "Debug Information" switch is selected for "Make", which forces it for the Ada compiler as well.
It has its own set of attributes:
master-page master-switch master-section
These two attributes define the switch that possibly forces a specific
setting on the slave switch. In our example, they would have the values
"Make" and "-g".
The switch referenced by these attributes must be of type <check>
or <field>
. If it is part of a section, then ’master-section’ needs
to be defined. 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 slave-section
These two attributes define the switch which is acted upon by the master
switch. In our example, they would have the values "Ada" and "-g".
The switch referenced by these attributes must be of type <check>
.
master-status slave-status
These two switches indicate which state of the master switch forces which state of the slave-status. In our example, they would have the values "on" and "on", so that when the make debug information is activated, the compiler debug information is also activated. However, if the make debug information is not activated, no specific setup is forced for the compiler debug information. if master-status is "off" and the master switch is a field, then the status of the slave will be changed when no value is set in the field.
<default-value-dependency>
This tag is used to describe a relationship between two switches. It is slightly different from the <dependency> tag in that the relationship concerns only the default activation states. It is used for instance when the "-gnatwa" switch is selected for the "Ada" Compiler, which imply that the default values for "-gnatwc", "-gnatwd", etc. become activated by default. They can however still be deactivated with respectively "-gnatwC" and "-gnatwD".
It has its own set of attributes:
master-switch
This is the switch that triggers the dependency. If master-switch
is
present in the command line, then the switch’s default status of
slave-switch
is modified accordingly.
slave-switch
This is the switch whose default value depends on master-switch
. This
needs to be a switch already defined in a <switch>
tag. It can match
its ’switch’ or ’switch-off’ attributes. In the latter case, the
slave-switch default value is deactivated if master-switch is present.
<expansion>
This tag is used to describe how switches can be grouped together on the command line to keep it shorter. It is also used to define aliases between switches.
It is easier to explain it through an example. Specifying the GNAT switch "-gnatyy" is equivalent to specifying "-gnaty3abcefhiklmnprst". 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.
There are two possible uses for this tag:
The same "switch" attribute can be used in two expansion nodes if you want to combine the behavior.
For historical reasons, this tag accepts <entry>
children, but these
are no longer used.
Next: Executing external tools, Previous: Defining default command line, Up: Adding support for new tools [Index]