/usr/share/doc/gnat-gps/html/Defining-tool-switches.html

<html lang="en">
<head>
<title>Defining tool switches - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Adding-support-for-new-tools.html#Adding-support-for-new-tools" title="Adding support for new tools">
<link rel="prev" href="Defining-default-command-line.html#Defining-default-command-line" title="Defining default command line">
<link rel="next" href="Executing-external-tools.html#Executing-external-tools" title="Executing external tools">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="Defining-tool-switches"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Executing-external-tools.html#Executing-external-tools">Executing external tools</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Defining-default-command-line.html#Defining-default-command-line">Defining default command line</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Adding-support-for-new-tools.html#Adding-support-for-new-tools">Adding support for new tools</a>
<hr>
</div>

<h4 class="subsection">16.6.3 Defining tool switches</h4>

<p><a name="index-g_t_003cswitches_003e-860"></a><!--  -->

<p class="noindent">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.

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

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

   <p>The switches are declared through the <code>&lt;switches&gt;</code> tag in the
customization file, which must be a child of a <code>&lt;tool&gt;</code> tag as described
above.

   <p>This <code>&lt;switches&gt;</code> tag accepts the following attributes:

     <dl>
<dt><code>lines (default value is 1)</code><dd>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.

     <br><dt><code>columns (default value is 1)</code><dd>This attribute specifies the number of columns of frames in the project
properties page.

     <br><dt><code>separator (default value is "")</code><dd>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 <code>"&amp;#32;"</code> rather than <code>" "</code>,
since XML parser must normalize the latter to the empty string when reading
the XML file.

     <br><dt><code>use_scrolled_window (Default value is false)</code><dd>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.

     <br><dt><code>show_command_line (Default value is true)</code><dd>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.

     <br><dt><code>switch_char (Default value is "-")</code><dd>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

     <br><dt><code>sections (Default value is empty)</code><dd>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.

   </dl>

   <p>This <code>&lt;switches&gt;</code> 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:

     <dl>
<dt><code>line (default value is 1)</code><dd>This indicates the row of the frame that should contain the switch. See the
description of <code>lines</code> above.

     <br><dt><code>column (default value is 1)</code><dd>This indicates the column of the frame that should contain the switch. See the
description of <code>columns</code> above.

     <br><dt><code>label (mandatory)</code><dd>This is the label which is displayed in the graphical interface

     <br><dt><code>switch (mandatory)</code><dd>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 <code>combo</code> and <code>spin</code> below. 
This switch shouldn't contain any space.

     <br><dt><code>switch-off (default value is empty)</code><dd>This attribute is used for <code>&lt;check&gt;</code> 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.

     <br><dt><code>section (default value is empty)</code><dd>This is the switch section delimiter (such as "-cargs"). See the 'sections'
attribute of the tag 'switches' for more information.

     <br><dt><code>tip (default value is empty)</code><dd>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 <code>&lt;tip&gt;</code> whose value will contain the text to be displayed. The
advantage of the latter is that the text formatting is then kept.

     <br><dt><code>before (default value is "false")</code><dd>This attribute is used to indicate that a switch needs to be always inserted
at the begining of the command line.

     <br><dt><code>min (default value is 1)</code><dd>This attribute is used for <code>&lt;spin&gt;</code> tags, and indicates the minimum
value authorized for that switch.

     <br><dt><code>max (default value is 1)</code><dd>This attribute is used for <code>&lt;spin&gt;</code> tags, and indicates the maximum
value authorized for that switch.

     <br><dt><code>default (default value is 1)</code><dd>This attribute is used for <code>&lt;check&gt;</code> and <code>&lt;spin&gt;</code> tags. See the
description below.

     <br><dt><code>noswitch (default is empty)</code><dd>This attribute is only valid for <code>&lt;combo&gt;</code> tags, and described below.

     <br><dt><code>nodigit (default is empty)</code><dd>This attribute is only valid for <code>&lt;combo&gt;</code> tags, and described below.

     <br><dt><code>value (mandatory)</code><dd>This attribute is only valid for <code>&lt;combo-entry&gt;</code> tags.

     <br><dt><code>separator (default is the value given to &lt;switches&gt;</code><dd>This attribute specifies the separator to use between the switch and its value. 
See the description of this attribute for <code>&lt;switches&gt;</code>.

   </dl>

   <p>Here are the valid children for <code>&lt;switches&gt;</code>:

     <dl>
<dt><code>&lt;title&gt;</code><dd><a name="index-g_t_003ctitle_003e-861"></a>This tag, which accepts the <code>line</code> and <code>column</code> 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.

     <p>Extra attributes for <code>&lt;title&gt;</code> are:

          <dl>
    <dt><code>line-span (default value is 1)</code><dd>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.

          <br><dt><code>column-span (default value is 1)</code><dd>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. 
    </dl>

     <br><dt><code>&lt;check&gt;</code><dd><a name="index-g_t_003ccheck_003e-862"></a>This tag accepts the <code>line</code>, <code>column</code>, <code>label</code>, <code>switch</code>,
<code>switch-off</code>, <code>section</code>, <code>default</code>, <code>before</code> and <code>tip</code>
attributes.

     <p>This tag doesn't have any value. An optional <code>&lt;tip&gt;</code> child can be present.

     <p>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 (<code>default</code> attribute is "on" or "true"). In this
case, deactivating the switch will add <code>switch-off</code> to the command line.

     <br><dt><code>&lt;spin&gt;</code><dd><a name="index-g_t_003cspin_003e-863"></a>This tag accepts the <code>line</code>, <code>column</code>, <code>label</code>, <code>switch</code>,
<code>section</code>, <code>tip</code>, <code>min</code>, <code>max</code>, <code>separator</code> and
<code>default</code> attributes.

     <p>This tag doesn't have any value. An optional <code>&lt;tip&gt;</code> child can be present.

     <p>This switch will add the contents of the <code>switch</code> 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 <code>default</code> attribute,
then nothing is added to the command line.

     <br><dt><code>&lt;radio&gt;</code><dd><a name="index-g_t_003cradio_003e-864"></a><a name="index-g_t_003cradio_002dentry_003e-865"></a>This tag accepts the <code>line</code> and <code>column</code> 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.

     <p>The children must have the tag <code>radio-entry</code>. This tag accepts the
attributes <code>label</code>, <code>switch</code>, <code>section</code>, <code>before</code> and
<code>tip</code>. 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.

     <p>This tag doesn't have any value. An optional <code>&lt;tip&gt;</code> child can also be
present.

     <br><dt><code>&lt;field&gt;</code><dd><a name="index-g_t_003cfield_003e-866"></a>This tag accepts the <code>line</code>, <code>column</code>, <code>label</code>, <code>switch</code>,
<code>section</code>, <code>separator</code>, <code>before</code> and <code>tip</code> attributes.

     <p>This tag doesn't have any value. An optional <code>&lt;tip&gt;</code> child can be present.

     <p>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 <code>switch</code> 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.

     <p>This tag accepts two extra attributes:

          <dl>
   <dt><code>as-directory  (optional)</code><dd>   <a name="index-as_002ddirectory-867"></a>   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.

          <br><dt><code>as-file (optional)</code><dd>   <a name="index-as_002dfile-868"></a>   This attribute is similar to <code>as-directory</code>, 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. 
   </dl>

     <br><dt><code>&lt;combo&gt;</code><dd><a name="index-g_t_003ccombo_003e-869"></a><a name="index-g_t_003ccombo_002dentry_003e-870"></a>This tag accepts the <code>line</code>, <code>column</code>, <code>label</code>, <code>switch</code>,
<code>section</code>, <code>before</code>, <code>tip</code>, <code>noswitch</code>, <code>separator</code>
and <code>nodigit</code> attributes.

     <p>The tag <code>&lt;combo&gt;</code> accepts any number of <code>combo-entry</code> children tags,
each of which accepts the <code>label</code> and <code>value</code> attribute. An optional
<code>&lt;tip&gt;</code> child can also be present.

     <p>The text inserted in the command line is the text from the <code>switch</code>
attribute, concatenated with the text of the <code>value</code> attribute for the
currently selected entry. If the value of the current entry is the same
as that of the <code>nodigit</code> attribute, then only the text of the
<code>switch</code> attribute is put on the command line. This is in fact necessary
to interpret the gcc switch "-O" as "-O1".

     <p>If the value of the current entry is that of the <code>noswitch</code> attribute,
then nothing is put in the command line.

     <br><dt><code>&lt;popup&gt;</code><dd><a name="index-g_t_003cpopup_003e-871"></a>This tag accepts the <code>line</code>, <code>column</code>, <code>label</code>, <code>lines</code>
and <code>columns</code> 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 <code>lines</code> and <code>columns</code> attributes.

     <p>This tag accepts any number of children, which are the same as the
<code>&lt;switches&gt;</code> attribute itself.

     <br><dt><code>&lt;dependency&gt;</code><dd><a name="index-g_t_003cdependency_003e-872"></a>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.

     <p>It has its own set of attributes:

          <dl>
   <dt><code>master-page master-switch master-section</code><dd>   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 <code>&lt;check&gt;</code>
   or <code>&lt;field&gt;</code>. 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.

          <br><dt><code>slave-page slave-switch slave-section</code><dd>   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 <code>&lt;check&gt;</code>.

          <br><dt><code>master-status slave-status</code><dd>   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. 
   </dl>

     <br><dt><code>&lt;default-value-dependency&gt;</code><dd><a name="index-g_t_003cdefault_002dvalue_002ddependency_003e-873"></a>This tag is used to describe a relationship between two switches. It is
slightly different from the &lt;dependency&gt; 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".

     <p>It has its own set of attributes:
          <dl>
   <dt><code>master-switch</code><dd>   This is the switch that triggers the dependency. If <code>master-switch</code> is
   present in the command line, then the switch's default status of
   <code>slave-switch</code> is modified accordingly.

          <br><dt><code>slave-switch</code><dd>   This is the switch whose default value depends on <code>master-switch</code>. This
   needs to be a switch already defined in a <code>&lt;switch&gt;</code> 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. 
   </dl>

     <br><dt><code>&lt;expansion&gt;</code><dd><a name="index-g_t_003cexpansion_003e-874"></a><a name="index-g_t_003centry_003e-875"></a>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.

     <p>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", <small class="dots">...</small>; With this information, GPS will try to keep the
command line length as short as possible, to keep it readable.

     <p>Both these aspects are defined in a unique <code>&lt;expansion&gt;</code> tag, which
accepts two attributes: <code>switch</code> is mandatory, and <code>alias</code> is
optional. Alias contains the text "-gnatyabcefhiklmnprst" in our example.

     <p>There are two possible uses for this tag:
          <ul>
<li>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".

          <li>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. 
</ul>

     <p>The same "switch" attribute can be used in two expansion nodes if you want
to combine the behavior.

     <p>For historical reasons, this tag accepts <code>&lt;entry&gt;</code> children, but these
are no longer used.

   </dl>

<!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / Defining-tool-switches.html
