16.6.3 Defining tool switches

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:

• If the "alias" attribute is not specified, then the "switch" attribute indicates that all switches starting with that prefix should be grouped. For instance, if you pass "-gnatw" as the value for the "switch" attribute, then a command line with "-gnatwa -gnatw.b" will in fact result in "-gnatwa.b".
• If the "alias" attribute is specified, then the "switch" attribute is considered as a shorter way of writting "alias". For instance, if "switch" is "-gnatyy" and "alias" is "-gnaty3abcefhiklmnprst", then the user can simply type "-gnatyy" to mean the whole set of options.

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.