/usr/share/doc/gnat-gps/html/Defining-project-attributes.html

<html lang="en">
<head>
<title>Defining project attributes - 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="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" title="Customizing through XML and Python files">
<link rel="prev" href="Defining-text-aliases.html#Defining-text-aliases" title="Defining text aliases">
<link rel="next" href="Adding-casing-exceptions.html#Adding-casing-exceptions" title="Adding casing exceptions">
<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-project-attributes"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Adding-casing-exceptions.html#Adding-casing-exceptions">Adding casing exceptions</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Defining-text-aliases.html#Defining-text-aliases">Defining text aliases</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files">Customizing through XML and Python files</a>
<hr>
</div>

<h4 class="subsection">16.5.15 Defining project attributes</h4>

<p><a name="index-project-attributes-828"></a><a name="index-g_t_003cproject_005fattribute_003e-829"></a><!--  -->

<p class="noindent">The project files are required by GPS, and are used to store various
pieces of information related to the current set of source files. This
includes how to find the source files, how the files should be compiled,
or manipulated through various tools, <small class="dots">...</small>.

   <p>However, the default set of attributes that are usable in a project file
is limited to the attributes needed by the tool packaged with GPS or GNAT.

   <p>If you are delivering your own tools, you might want to store similar
information in the project files themselves, since these are a very
convenient place to associate some specific settings with a given set of
source files.

   <p>GPS lets manipulate the contents of projects through XML customization
files and script commands. You can therefore add you own typed attributes
into the projects, so that they are saved automatically when the user
saves the project, and reloaded automatically the next time GPS is started.

<h5 class="subsubsection">16.5.15.1 Declaring the new attributes</h5>

<p>New project attributes can be declared in two ways: either using the advanced
XML tags below, or using the <code>&lt;tool&gt;</code> tag (see <a href="Defining-tool-switches.html#Defining-tool-switches">Defining tool switches</a>).

   <p>The customization files support the <code>&lt;project_attribute&gt;</code> tag,
which is used to declare all the new attributes that GPS should expect
in a project.  Attributes that have not been declared explictly will
not be accessible through the GPS scripting languagues, and will
generate warnings in the Messages window.

   <p>Project attributes are typed: they can either have a single value, or
have a set of such values (a list). The values can in turn be a
free-form string, a file name, a directory name, or a value extracted
from a list of preset values.

   <p>Attributes that have been declared in these customization files will
also be graphically editable through the project properties dialog, or
the project wizard. Therefore, you should specify when an attribute is
defined how it should be presented to the GPS user.

   <p>The <code>&lt;project_attribute&gt;</code> tag accepts the following attributes:

     <ul>
<li><code>package</code> (a string, default value: "")

     <p>This is the package in the project file in which the attribute is
stored. Common practice suggests that one such package should be used
for each tool. These packages provide namespaces, so that attributes
with the same name, but for different tools, do not conflict with each
other.

     <li><code>name</code> (a string, mandatory)

     <p>This is the name of the attribute. This should be a string with no
space, and that represents a valid Ada identifier (typically, it
should start with a letter and be followed by a set of letters, digits
or underscore characters). This is an internal name that is used when
saving the attribute in a project file.

     <li><code>editor_page</code> (a string, default value: "General")

     <p>This is the name of the page in the Project Properties editor dialog
in which the attribute is presented. If no such page already exists, a
new one will be created as needed. If the page already exists, the
attribute will be appended at its bottom.

     <li><code>editor_section</code> (a string, default value: "")

     <p>This is the name of the section, inside editor page, in which the
attribute is displayed. These sections are surrounded by frames, the
title of which is given by the <code>editor_section</code> attribute. 
If this attribute is not specified, the attribute is put in an
untitled section.

     <li><code>label</code> (a string, default value: the name of the attribute)

     <p>If this attribute is set to a value other than the empty string
<code>""</code>, a textual label is displayed to the left of the attribute
in the graphical editor. This should be used to identify the
attribute. However, it can be left to the empty string if the
attribute is in a named section of its own, since the title of the
section might be a good enough indication.

     <li><code>description</code> (a string, default value: "")

     <p>This is the help message that describes the role of the attribute. It
is displayed in a tooltip if the user leaves the mouse on top of the
attribute for a while.

     <li><code>list</code> (a boolean, default value: "false")

     <p>If this is set to <code>"true"</code>, the project attribute will in fact
contains a list of values, as opposed to a single value. This is used
for instance for the list of source directories in standard projects.

     <li><code>ordered</code> (a boolean, default value: "false")

     <p>This is only relevant if the project attribute contains a list of
values. This indicates whether the order of the values is relevant. 
In most cases, it will not matter. However, for instance, the order of
source directories matters, since this also indicates where the source
files will be searched, stopping at the first match.

     <li><code>omit_if_default</code> (a boolean, default value: "true")

     <p>This indicates whether the project attribute should be set explicitly
in the project if the user has left it to its default value. This can
be used to keep the project files a simple as possible, if all the
tools that will use this project attribute know about the default
value. If this isn't the case, set <code>omit_if_default</code> to "false"
to force the generation of the project attribute.

     <li><code>base_name_only</code> (a boolean, default value: "false")

     <p>If the attribute contains a file name or a directory name, this
indicates whether the full path should be stored, or only the base
name. In most cases, the full path should be used. However, since GPS
automatically looks for source files in the list of directories, for
instance, the list of source files should only contain base
names. This also increases the portability of project files.

     <li><code>case_sensitive_index</code> (a boolean, default value: "false")

     <p>This XML attribute is only relevant for project attributes that are
indexed on another one (see below for more information on indexed
attributes). It indicates whether two indexes that differ only by
their casing should be considered the same. For instance, if the index
is the name of one of the languages supported by GPS, the index is
case insensitive since "Ada" is the same as "C". However, if the index
is the name of a file on Windows, the index is case-insensitive.

     <li><code>hide_in</code> (a string, default value: "")

     <p>This XML attribute defines the various context in which this attribute
should not be editable graphically. Currently, GPS provides three such
contexts ("wizard", "library_wizard" and "properties", corresponding to the
project creation wizards and the project properties editor). If any of those
context is specified in hide_in, then the widget to edit this
attribute will not be shown. The goal is to keep the graphical
interface simple.

     <li><code>disable_if_not_set</code> (a boolean, default value: "false")

     <p>If this attribute is set to "true", the editor for this attribute will be
greyed out if the attribute is not explicitly set in the project. In most cases,
this is not needed, since the default value of the attribute can be used to leave
the editor active at all time. However, when the value of the attribute is
automatically computed depending on other attributes, the default value cannot be
easily specified in the XML file, and in this case it might be easier to grey out
the editor. An extra check box is displayed next to the attribute so that the user
can choose to activate the editor and add the attribute to the project.

     <li><code>disable</code> (a space-separated list of attribute names, default: "")

     <p>This is a list of attribute whose editor should be greyed out if the current
attribute is specified. This only works if both the current attribute and the
referenced attributes have their <code>disable_if_not_set</code> attribute set to "true". 
This can be used to have mutually exclusive attributes present in the editor

   </ul>

<h5 class="subsubsection">16.5.15.2 Declaring the type of the new attributes</h5>

<p>The type of the project attribute is specified through one or several
child tags of <code>&lt;project_attribute&gt;</code>. The following tags are
recognized.

     
<a name="index-g_t_003cstring_003e-830"></a>
<ul><li><code>&lt;string&gt;</code>

     <p>This tag indicates that the attribute is made of one (or more if it is
a list) strings. This
tag accepts the following XML attributes:

          <ul>
<li><code>default</code> (a string, default value: "")

          <p>This gives the default value to be used for the string (and therefore
the project attribute), in case the user hasn't overridden it.

          <p>If the attribute's type is a file or a directory, the default value will be
normalized (ie an absolute path will be generated from it, based on the
project's location, where <code>"."</code> will represent the project's directory). 
As a special case, if default is surrounded by parenthesis, no normalization
takes place, so that you can later on test whether the user is still using
the default value or not).

          <p>A special case if when <code>default</code> is set to "project source files". In this
case, this is automatically replaced by the known list of source files for the
project. This doesn't work from the project wizard, since the list of source files
hasn't been computed at that stage.

          <li><code>type</code> (one of "", "file", "directory", default "")

          <p>This indicates what the string represents. In the first case, any
value can be used. In the second case, it should represent a file
name, although no check is done to make sure the file actually exists
on the disk. But GPS will be able to do some special marshalling with
the file name. The third case indicates that GPS should expect a
directory.

          <li><code>filter</code> (one of "none", "project", "extending_project")

          <p>This attribute is ignored for all types except <code>"file"</code>. In this case,
it further specifies what kind of files can be used in this attribute. If
the filter is <code>"none"</code>, then any file anywhere on the system is valid. 
If the filter is <code>"project"</code>, then only files from the selected project
can be specified. If the filter is <code>"extended_project"</code>, then only the
files from the project extended by the current project can be specified. The
attribute will not be shown if the current project is not an extending project.

          <li><code>allow_empty</code> (one of "True" or "False, default "True")

          <p>This attribute indicates whether the value for this attribute can be an
empty string. If not, the user must specify a value or an error message will
be displayed in the project properties editor and project wizard.

     </ul>

     <p><a name="index-g_t_003cchoice_003e-831"></a><li><code>&lt;choice&gt;</code>

     <p>This tag can be repeated several times. It indicates one of the valid
values for the attribute, and can be used to provide a static list of
such values. If it is combined with a <code>&lt;string&gt;</code> tag, this
indicates that the attribute can be any string, although a set of
possible values is provided to the user for ease of use. 
This tag accepts one optional attribute, <code>"default"</code>, which is a
boolean. It indicates whether this value is the default to use for the
project attribute.

     <p>If several <code>&lt;choice&gt;</code> tags are used, it is possible that several
of them are part of the default value if the project attribute is a
list, as opposed to a single value.

     <p><a name="index-g_t_003cshell_003e-832"></a><li><code>&lt;shell&gt;</code>

     <p>This tag is a GPS scripting command to execute to get a list of valid
values for the attribute. The command should return a list. As for the
<code>&lt;choice&gt;</code> tag, the <code>&lt;shell&gt;</code> tag can be combined with a
<code>&lt;string&gt;</code> tag to indicate that the list of values returned by
the scripting command is only a set of possible values, but that the
project attribute can in fact take any value.

     <p>The <code>&lt;shell&gt;</code> tag accepts two attributes:

          <ul>
<li><code>lang</code> (a string, default value: "shell")

          <p>The scripting language in which the command is written. Currently, the
only other possible value is "python".

          <li><code>default</code> (a string, default value: "")

          <p>The default value that the project attribute takes if the user hasn't
overridden it. 
</ul>

   </ul>

   <p><a name="index-indexed-project-attributes-833"></a><a name="index-project-attributes_002c-indexed-834"></a><a name="index-g_t_003cindex_003e-835"></a><a name="index-g_t_003cspecialized_005findex_003e-836"></a>
In some cases, the type of the project attribute, or at least its
default value, depends on what the attribute applies to. The project
file support this in the form of indexed project attribute. This is
for instance used to specify what should be the name of the executable
generated when compiling each of the main files in the project (ie the
executable name for <code>gps.adb</code> should be <code>gps.exe</code>, the one
for <code>main.c</code> should be <code>myapp.exe</code>, and so on).

   <p>Such attributes can also be declared through XML files. In such cases,
the <code>&lt;project_attribute&gt;</code> tag should have one <code>&lt;index&gt;</code>
child, and zero or more <code>&lt;specialized_index&gt;</code> children. 
Each of these two tags in turn take one of the already mentioned
<code>&lt;string&gt;</code>, <code>&lt;choice&gt;</code> or <code>&lt;shell&gt;</code> tag.

   <p>The <code>&lt;index&gt;</code> tag indicates what other project attribute is used
to index the current one. In the example given above for the
executable names, the index is the attribute that contains the list of
main files for the project.

   <p>It accepts the following XML attributes:

     <ul>
<li><code>attribute</code> (a string, mandatory)

     <p>The name of the other attribute. This other attribute must be declared
elsewhere in the customization files, and must be a list of values,
not a single value.

     <li><code>package</code> (a string, default value: "")

     <p>The package in which the index project attribute is defined. This is
used to uniquely identify homonym attributes. 
</ul>

   <p>The <code>&lt;specialized_index&gt;</code> is used to override the default type of
the attribute for specific values of the index. For instance, the
project files contains an attribute that specify what the name of the
compiler is for each language. It is indexed on the project attribute
that list the languages used for the source files of the project. Its
default value depends on the language ("gnatmake" for Ada, "gcc" for
C, and so on). This attribute accepts requires one XML attribute:

     <ul>
<li><code>value</code> (a string, mandatory)

     <p>This is the value of the attribute for which the type is overriden. 
</ul>

   <p>Note that almost all the standard project attributes are defined
through an XML file, <samp><span class="file">projects.xml</span></samp>, which is part of the GPS
installation. Check this file to get advanced examples on how to
declare project attributes.

<h5 class="subsubsection">16.5.15.3 Examples</h5>

<p>The following example declares three attributes, with a single string
as their value. This string represents a file or a directory in the
last two cases. You can simply copy this into a <samp><span class="file">.xml</span></samp> file in
your <samp><span class="file">$HOME/.gps/plug-ins</span></samp> directory, as usual.

<pre class="smallexample">     &lt;?xml version="1.0"?&gt;
     &lt;custom&gt;
       &lt;project_attribute
           name="Single1"
           package="Test"
           editor_page="Tests single"
           editor_section="Single"
           description="Any string"&gt;
     
          &lt;string default="Default value" /&gt;
       &lt;/project_attribute&gt;
     
       &lt;project_attribute
           name="File1"
           package="Test"
           editor_page="Tests single"
           editor_section="Single"
           description="Any file" &gt;
     
           &lt;string type="file" default="/my/file" /&gt;
       &lt;/project_attribute&gt;
     
       &lt;project_attribute
           name="Directory1"
           package="Test"
           editor_page="Tests single"
           editor_section="Single"
           description="Any directory" &gt;
     
           &lt;string type="directory" default="/my/directory/" /&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <p>The following example declares an attribute whose value is a
string. However, a list of predefined possible values is also
provided, as an help for interactive edition for the user. If the
<code>&lt;string&gt;</code> tag wasn't given, the attribute's value would have two
be one of the three possible choices.

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;custom&gt;
       &lt;project_attribute
           name="Static2"
           package="Test"
           editor_page="Tests single"
           editor_section="Single"
           description="Choice from static list (or any string)" &gt;
     
           &lt;choice&gt;Choice1&lt;/choice&gt;
           &lt;choice default="true" &gt;Choice2&lt;/choice&gt;
           &lt;choice&gt;Choice3&lt;/choice&gt;
           &lt;string /&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <p>The following example declares an attribute whose value is one of the
languages currently supported by GPS. Since this list of languages is
only know when GPS is executed, a script command is used to query this
list.

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;custom&gt;
      &lt;project_attribute
           name="Dynamic1"
           package="Test"
           editor_page="Tests single"
           editor_section="Single"
           description="Choice from dynamic list" &gt;
     
           &lt;shell default="C" &gt;supported_languages&lt;/shell&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <p>The following example declares an attribute whose value is a set of
file names. The order of files in this list matters to the tools that
are using this project attribute.

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;custom&gt;
      &lt;project_attribute
           name="File_List1"
           package="Test"
           editor_page="Tests list"
           editor_section="Lists"
           list="true"
           ordered="true"
           description="List of any file" &gt;
     
           &lt;string type="file" default="Default file" /&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <p>The following example declares an attribute whose value is a set of
predefined possible values. By default, two such values are selected,
unless the user overrides this default setting.

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;custom&gt;
       &lt;project_attribute
           name="Static_List1"
           package="Test"
           editor_page="Tests list"
           editor_section="Lists"
           list="true"
           description="Any set of values from a static list" &gt;
     
           &lt;choice&gt;Choice1&lt;/choice&gt;
           &lt;choice default="true"&gt;Choice2&lt;/choice&gt;
           &lt;choice default="true"&gt;Choice3&lt;/choice&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <p>The following example declares an attribute whose value is a
string. However, the value is specific to each language (this could
for instance be used for the name of the compiler to use for a given
language). This is an indexed project attribute. It has two default
values, one for Ada, one for C. All other languages have no default
value.

<pre class="smallexample">     &lt;?xml version="1.0" ?&gt;
     &lt;custom&gt;
       &lt;project_attribute
           name="Compiler_Name"
           package="Test"
           editor_page="Tests indexed"
           editor_section="Single"
           &lt;index attribute="languages" package=""&gt;
              &lt;string default="" /&gt;
           &lt;/index&gt;
           &lt;specialized_index value="Ada" &gt;
              &lt;string default="gnatmake" /&gt;
           &lt;/specialized_index&gt;
           &lt;specialized_index value="C" &gt;
              &lt;string default="gcc" /&gt;
           &lt;/specialized_index&gt;
       &lt;/project_attribute&gt;
     &lt;/custom&gt;
</pre>
   <h5 class="subsubsection">16.5.15.4 Accessing the project attributes</h5>

<p>The new attributes that were defined are accessible from the GPS
scripting languages, like all the standard attributes, see <a href="Querying-project-switches.html#Querying-project-switches">Querying project switches</a>.

   <p>You can for instance access the Compiler_Name attribute we created
above with a python command similar to:

<pre class="smallexample">     GPS.Project.root().get_attribute_as_string ("Compiler_Name", "Test", "Ada")
</pre>
   <p>You can also access the list of main files for the project, for
instance, by calling

<pre class="smallexample">     GPS.Project.root().get_attribute_as_list ("main")
</pre>
   <!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / Defining-project-attributes.html
