16.5.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.

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.

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.

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 <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 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>

This tag accepts the 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>

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 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>

This tag accepts the 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)

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 tags accepts the 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>

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

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 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

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.

<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 "-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:

• For each switch on the command line, it is expanded either through the standard GNAT handling (thus "-gnatwuv" is made equivalent to "-gnatwu -gnatwv"), or through the definition in the custom file (if an XML node has a 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"
  

• Then the switches on the command line are grouped together as much as possible. For all switch on the command line, if it starts with one of the values given to the 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".
  

• Finally, the resuling switches are compared with the 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.