<html lang="en">
<head>
<title>GPRbuild User's Guide</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GPRbuild User's Guide">
<meta name="generator" content="makeinfo 4.7">
<link title="Top" rel="top" href="#Top">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<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; }
pre.smallexample,
div.important,
div.note,
div.tip {background-color:rgb(240,240,240);
margin: 0px 40px 0px 40px;
border-width: 1px 2px 2px 1px;
border-top-style: ridge;
border-left-style: ridge;
border-right-style: solid;
border-bottom-style: solid;
border-color: black;}
pre.smallexample {font-size: 14px;
font-family: courier new,courier,fixed;
}
div.important,
div.note,
div.tip {font-size: 14px;
background-repeat: no-repeat;
background-position: center left;
padding: 10px 10px 10px 40px;
}
div.tip {background-image: url(tip.png); }
div.note {background-image: url(note.png); }
div.important {background-image: url(important.png); }
div.side {position: absolute;
font-style: italic;
font-size: small;
text-align: left;
width: 200px;
left: 840px;
z-index: 3;
color: #447bcd;}
div.side a:link,
div.side a:visited { text-decoration: none; color: #447bcd;}
div.contents ul ul { padding-left: 10px;
list-style-type: none;
}
div.contents > ul { padding-left: 5px;
list-style-type: none }
div.contents a:link,
div.contents a:visited,
div.contents a:active { text-decoration: none; color:blue }
div.contents a:hover { text-decoration: underline; color:red}
/* IE7 still does not support the > selectors... workaround */
div.contents ul li { padding-top: 20px; }
div.contents ul li ul li { padding-top: 0px; }
h1.settitle {background:#003580;
font-size: huge;
text-align: center;
padding: 30px 10px 30px 10px;
color: white }
h2.unnumbered,
h2.chapter { background:#098ABA;
padding: 5px 5px 5px 15px }
h3.section { border-bottom: solid black; }
h4.subsection { border-bottom: solid black;}
dt { text-decoration: underline;
font-style: italic }
code {color:black;
font-family: courier new,courier,fixed;
font-size: 14px;}
body {/*font-family: verdana,arial,helvetica,sans-serif;
font-size: 14px; */
margin-left:10px; margin-right:305px;
text-align: justify}
samp {font-family: courier new,courier,fixed;
font-size: 14px}
/* table of contents and tips in the right margin */
div.contents {width:300px; top: 0px; right:0px; font-size:smaller;
position: absolute; }
div.contents ul {padding-left:10px; margin:0}
div.tip {position: absolute;
text-align: left; /* don't align when width is small */
width: 200px; right:0px}
--></style>
</head>
<body>
<h1 class="settitle">GPRbuild User's Guide</h1>
<a name="Top"></a>
<h2 class="unnumbered">GPRBUILD User's Guide</h2>
<p class="noindent">Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being “GNU Free Documentation License”, with the
Front-Cover Texts being
“GPRbuild User's Guide”,
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
“GNU Free Documentation License”.
<!-- projects.texi -->
<!-- This file is shared between the GNAT user's guide and gprbuild. It is not -->
<!-- compilable on its own, you should instead compile the other two manuals. -->
<!-- For that reason, there is no toplevel @menu -->
<!-- -->
<p><a name="GNAT-Project-Manager"></a>
<h2 class="chapter">1 GNAT Project Manager</h2>
<!-- -->
<p class="noindent">
<!-- -->
<a name="Introduction"></a>
<h3 class="section">1.1 Introduction</h3>
<!-- -->
<p class="noindent">This chapter describes GNAT's <em>Project Manager</em>, a facility that allows
you to manage complex builds involving a number of source files, directories,
and options for different system configurations. In particular,
project files allow you to specify:
<ul>
<li>The directory or set of directories containing the source files, and/or the
names of the specific source files themselves
<li>The directory in which the compiler's output
(<span class="file">ALI</span> files, object files, tree files, etc.) is to be placed
<li>The directory in which the executable programs are to be placed
<li>Switch settings for any of the project-enabled tools;
you can apply these settings either globally or to individual compilation units.
<li>The source files containing the main subprogram(s) to be built
<li>The source programming language(s)
<li>Source file naming conventions; you can specify these either globally or for
individual compilation units (see <a href="#Naming-Schemes">Naming Schemes</a>).
<li>Change any of the above settings depending on external values, thus enabling
the reuse of the projects in various <b>scenarios</b> (see <a href="#Scenarios-in-Projects">Scenarios in Projects</a>).
<li>Automatically build libraries as part of the build process
(see <a href="#Library-Projects">Library Projects</a>).
</ul>
<p class="noindent">Project files are written in a syntax close to that of Ada, using familiar
notions such as packages, context clauses, declarations, default values,
assignments, and inheritance (see <a href="#Project-File-Reference">Project File Reference</a>).
<p>Project files can be built hierarchically from other project files, simplifying
complex system integration and project reuse (see <a href="#Organizing-Projects-into-Subsystems">Organizing Projects into Subsystems</a>).
<ul>
<li>One project can import other projects containing needed source files.
More generally, the Project Manager lets you structure large development
efforts into hierarchical subsystems, where build decisions are delegated
to the subsystem level, and thus different compilation environments
(switch settings) used for different subsystems.
<li>You can organize GNAT projects in a hierarchy: a child project
can extend a parent project, inheriting the parent's source files and
optionally overriding any of them with alternative versions
(see <a href="#Project-Extension">Project Extension</a>).
</ul>
<p class="noindent">Several tools support project files, generally in addition to specifying
the information on the command line itself). They share common switches
to control the loading of the project (in particular
<span class="option">-P</span><em>projectfile</em> and
<span class="option">-X</span><em>vbl</em><span class="option">=</span><em>value</em>).
See <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a>.
<p>The Project Manager supports a wide range of development strategies,
for systems of all sizes. Here are some typical practices that are
easily handled:
<ul>
<li>Using a common set of source files and generating object files in different
directories via different switch settings. It can be used for instance, for
generating separate sets of object files for debugging and for production.
<li>Using a mostly-shared set of source files with different versions of
some units or subunits. It can be used for instance, for grouping and hiding
</ul>
<p class="noindent">all OS dependencies in a small number of implementation units.
<p>Project files can be used to achieve some of the effects of a source
versioning system (for example, defining separate projects for
the different sets of sources that comprise different releases) but the
Project Manager is independent of any source configuration management tool
that might be used by the developers.
<p>The various sections below introduce the different concepts related to
projects. Each section starts with examples and use cases, and then goes into
the details of related project file capabilities.
<!-- -->
<p><a name="Building-With-Projects"></a>
<h3 class="section">1.2 Building With Projects</h3>
<!-- -->
<p class="noindent">In its simplest form, a unique project is used to build a single executable.
This section concentrates on such a simple setup. Later sections will extend
this basic model to more complex setups.
<p>The following concepts are the foundation of project files, and will be further
detailed later in this documentation. They are summarized here as a reference.
<dl>
<dt><b>Project file</b>:<dd> A text file using an Ada-like syntax, generally using the <span class="file">.gpr</span>
extension. It defines build-related characteristics of an application.
The characteristics include the list of sources, the location of those
sources, the location for the generated object files, the name of
the main program, and the options for the various tools involved in the
build process.
<br><dt><b>Project attribute</b>:<dd> A specific project characteristic is defined by an attribute clause. Its
value is a string or a sequence of strings. All settings in a project
are defined through a list of predefined attributes with precise
semantics. See <a href="#Attributes">Attributes</a>.
<br><dt><b>Package in a project</b>:<dd> Global attributes are defined at the top level of a project.
Attributes affecting specific tools are grouped in a
package whose name is related to tool's function. The most common
packages are <code>Builder</code>, <code>Compiler</code>, <code>Binder</code>,
and <code>Linker</code>. See <a href="#Packages">Packages</a>.
<br><dt><b>Project variables</b>:<dd> In addition to attributes, a project can use variables to store intermediate
values and avoid duplication in complex expressions. It can be initialized
with a value coming from the environment.
A frequent use of variables is to define scenarios.
See <a href="#External-Values">External Values</a>, See <a href="#Scenarios-in-Projects">Scenarios in Projects</a>, and See <a href="#Variables">Variables</a>.
<br><dt><b>Source files</b> and <b>source directories</b>:<dd> A source file is associated with a language through a naming convention. For
instance, <code>foo.c</code> is typically the name of a C source file;
<code>bar.ads</code> or <code>bar.1.ada</code> are two common naming conventions for a
file containing an Ada spec. A compilation unit is often composed of a main
source file and potentially several auxiliary ones, such as header files in C.
The naming conventions can be user defined See <a href="#Naming-Schemes">Naming Schemes</a>, and will
drive the builder to call the appropriate compiler for the given source file.
Source files are searched for in the source directories associated with the
project through the <b>Source_Dirs</b> attribute. By default, all the files (in
these source directories) following the naming conventions associated with the
declared languages are considered to be part of the project. It is also
possible to limit the list of source files using the <b>Source_Files</b> or
<b>Source_List_File</b> attributes. Note that those last two attributes only
accept basenames with no directory information.
<br><dt><b>Object files</b> and <b>object directory</b>:<dd> An object file is an intermediate file produced by the compiler from a
compilation unit. It is used by post-compilation tools to produce
final executables or libraries. Object files produced in the context of
a given project are stored in a single directory that can be specified by the
<b>Object_Dir</b> attribute. In order to store objects in
two or more object directories, the system must be split into
distinct subsystems with their own project file.
</dl>
<p>The following subsections introduce gradually all the attributes of interest
for simple build needs. Here is the simple setup that will be used in the
following examples.
<p>The Ada source files <span class="file">pack.ads</span>, <span class="file">pack.adb</span>, and <span class="file">proc.adb</span> are in
the <span class="file">common/</span> directory. The file <span class="file">proc.adb</span> contains an Ada main
subprogram <code>Proc</code> that <code>with</code>s package <code>Pack</code>. We want to compile
these source files with the switch <span class="option">-O2</span>, and put the resulting files in
the directory <span class="file">obj/</span>.
<pre class="smallexample"> common/
pack.ads
pack.adb
proc.adb
common/release/
proc.ali, proc.o pack.ali, pack.o
</pre>
<p class="noindent">Our project is to be called <em>Build</em>. The name of the
file is the name of the project (case-insensitive) with the
<span class="file">.gpr</span> extension, therefore the project file name is <span class="file">build.gpr</span>. This
is not mandatory, but a warning is issued when this convention is not followed.
<p>This is a very simple example, and as stated above, a single project
file is enough for it. We will thus create a new file, that for now
should contain the following code:
<pre class="smallexample"> <b>project</b> Build <b>is</b>
<b>end</b> Build;
</pre>
<!-- -->
<p><a name="Source-Files-and-Directories"></a>
<h4 class="subsection">1.2.1 Source Files and Directories</h4>
<!-- -->
<p class="noindent">When you create a new project, the first thing to describe is how to find the
corresponding source files. This is the only settings that are needed by all
the tools that will use this project (builder, compiler, binder and linker for
the compilation, IDEs to edit the source files,<small class="dots">...</small>).
<p><a name="index-Source-directories-1"></a>First step is to declare the source directories, which are the directories
to be searched to find source files. In the case of the example,
the <span class="file">common</span> directory is the only source directory.
<p><a name="index-_0040code_007bSource_005fDirs_007d-2"></a>There are several ways of defining source directories:
<ul>
<li>When the attribute <b>Source_Dirs</b> is not used, a project contains a
single source directory which is the one where the project file itself
resides. In our example, if <span class="file">build.gpr</span> is placed in the <span class="file">common</span>
directory, the project has the needed implicit source directory.
<li>The attribute <b>Source_Dirs</b> can be set to a list of path names, one
for each of the source directories. Such paths can either be absolute
names (for instance <span class="file">"/usr/local/common/"</span> on UNIX), or relative to the
directory in which the project file resides (for instance "." if
<span class="file">build.gpr</span> is inside <span class="file">common/</span>, or "common" if it is one level up).
Each of the source directories must exist and be readable.
<p><a name="index-portability-3"></a> The syntax for directories is platform specific. For portability, however,
the project manager will always properly translate UNIX-like path names to
the native format of specific platform. For instance, when the same project
file is to be used both on Unix and Windows, "/" should be used as the
directory separator rather than "\".
<li>The attribute <b>Source_Dirs</b> can automatically include subdirectories
using a special syntax inspired by some UNIX shells. If any of the path in
the list ends with <em>"/**"</em>, then that path and all its subdirectories
(recursively) are included in the list of source directories. For instance,
<span class="file">./**</span> represent the complete directory tree rooted at ".".
<a name="index-Source-directories_002c-recursive-4"></a>
<a name="index-_0040code_007bExcluded_005fSource_005fDirs_007d-5"></a> When using that construct, it can sometimes be convenient to also use the
attribute <b>Excluded_Source_Dirs</b>, which is also a list of paths. Each entry
specifies a directory whose immediate content, not including subdirs, is to
be excluded. It is also possible to exclude a complete directory subtree
using the "/**" notation.
</ul>
<p class="noindent">When applied to the simple example, and because we generally prefer to have
the project file at the toplevel directory rather than mixed with the sources,
we will create the following file
<pre class="smallexample"> build.gpr
<b>project</b> Build <b>is</b>
<b>for</b> Source_Dirs <b>use</b> ("common"); -- <<<<
<b>end</b> Build;
</pre>
<p class="noindent">Once source directories have been specified, one may need to indicate
source files of interest. By default, all source files present in the source
directories are considered by the project manager. When this is not desired,
it is possible to specify the list of sources to consider explicitly.
In such a case, only source file base names are indicated and not
their absolute or relative path names. The project manager is in charge of
locating the specified source files in the specified source directories.
<ul>
<li>By default, the project manager search for all source files of all
specified languages in all the source directories.
<p>Since the project manager was initially developed for Ada environments, the
default language is usually Ada and the above project file is complete: it
defines without ambiguity the sources composing the project: that is to say,
all the sources in subdirectory "common" for the default language (Ada) using
the default naming convention.
<p><a name="index-_0040code_007bLanguages_007d-6"></a> However, when compiling a multi-language application, or a pure C
application, the project manager must be told which languages are of
interest, which is done by setting the <b>Languages</b> attribute to a list of
strings, each of which is the name of a language. Tools like
<span class="command">gnatmake</span> only know about Ada, while other tools like
<span class="command">gprbuild</span> know about many more languages such as C, C++, Fortran,
assembly and others can be added dynamically.
<p><a name="index-Naming-scheme-7"></a> Even when using only Ada, the default naming might not be suitable. Indeed,
how does the project manager recognizes an "Ada file" from any other
file? Project files can describe the naming scheme used for source files,
and override the default (see <a href="#Naming-Schemes">Naming Schemes</a>). The default is the
standard GNAT extension (<span class="file">.adb</span> for bodies and <span class="file">.ads</span> for
specs), which is what is used in our example, explaining why no naming scheme
is explicitly specified.
See <a href="#Naming-Schemes">Naming Schemes</a>.
<li><code>Source Files</code>
<a name="index-_0040code_007bSource_005fFiles_007d-8"></a> In some cases, source directories might contain files that should not be
included in a project. One can specify the explicit list of file names to
be considered through the <b>Source_Files</b> attribute.
When this attribute is defined, instead of looking at every file in the
source directories, the project manager takes only those names into
consideration reports errors if they cannot be found in the source
directories or does not correspond to the naming scheme.
<li>For various reasons, it is sometimes useful to have a project with no
sources (most of the time because the attributes defined in the project
file will be reused in other projects, as explained in see <a href="#Organizing-Projects-into-Subsystems">Organizing Projects into Subsystems</a>. To do this, the attribute
<em>Source_Files</em> is set to the empty list, i.e. <code>()</code>. Alternatively,
<em>Source_Dirs</em> can be set to the empty list, with the same
result.
<li><code>Source_List_File</code>
<a name="index-_0040code_007bSource_005fList_005fFile_007d-9"></a> If there is a great number of files, it might be more convenient to use
the attribute <b>Source_List_File</b>, which specifies the full path of a file.
This file must contain a list of source file names (one per line, no
directory information) that are searched as if they had been defined
through <em>Source_Files</em>. Such a file can easily be created through
external tools.
<p>A warning is issued if both attributes <code>Source_Files</code> and
<code>Source_List_File</code> are given explicit values. In this case, the
attribute <code>Source_Files</code> prevails.
<li><code>Excluded_Source_Files</code>
<a name="index-_0040code_007bExcluded_005fSource_005fFiles_007d-10"></a><a name="index-_0040code_007bLocally_005fRemoved_005fFiles_007d-11"></a><a name="index-_0040code_007bExcluded_005fSource_005fList_005fFile_007d-12"></a> Specifying an explicit list of files is not always convenient.It might be
more convenient to use the default search rules with specific exceptions.
This can be done thanks to the attribute <b>Excluded_Source_Files</b>
(or its synonym <b>Locally_Removed_Files</b>).
Its value is the list of file names that should not be taken into account.
This attribute is often used when extending a project, See <a href="#Project-Extension">Project Extension</a>. A similar attribute <b>Excluded_Source_List_File</b> plays the same
role but takes the name of file containing file names similarly to
<code>Source_List_File</code>.
</ul>
<p class="noindent">In most simple cases, such as the above example, the default source file search
behavior provides the expected result, and we do not need to add anything after
setting <code>Source_Dirs</code>. The project manager automatically finds
<span class="file">pack.ads</span>, <span class="file">pack.adb</span> and <span class="file">proc.adb</span> as source files of the
project.
<p>Note that it is considered an error for a project file to have no sources
attached to it unless explicitly declared as mentionend above.
<p>If the order of the source directories is known statically, that is if
<code>"/**"</code> is not used in the string list <code>Source_Dirs</code>, then there may
be several files with the same source file name sitting in different
directories of the project. In this case, only the file in the first directory
is considered as a source of the project and the others are hidden. If
<code>"/**"</code> is not used in the string list <code>Source_Dirs</code>, it is an error
to have several files with the same source file name in the same directory
<code>"/**"</code> subtree, since there would be an ambiguity as to which one should
be used. However, two files with the same source file name may in two single
directories or directory subtrees. In this case, the one in the first directory
or directory subtree is a source of the project.
<!-- -->
<p><a name="Object-and-Exec-Directory"></a>
<h4 class="subsection">1.2.2 Object and Exec Directory</h4>
<!-- -->
<p class="noindent">The next step when writing a project is to indicate where the compiler should
put the object files. In fact, the compiler and other tools might create
several different kind of files (for GNAT, there is the object file and the ALI
file for instance). One of the important concepts in projects is that most
tools may consider source directories as read-only and do not attempt to create
new or temporary files there. Instead, all files are created in the object
directory. It is of course not true for project-aware IDEs, whose purpose it is
to create the source files.
<p><a name="index-_0040code_007bObject_005fDir_007d-13"></a>The object directory is specified through the <b>Object_Dir</b> attribute.
Its value is the path to the object directory, either absolute or
relative to the directory containing the project file. This
directory must already exist and be readable and writable, although
some tools have a switch to create the directory if needed (See
the switch <code>-p</code> for <span class="command">gnatmake</span> and <span class="command">gprbuild</span>).
<p>If the attribute <code>Object_Dir</code> is not specified, it defaults to
the project directory, that is the directory containing the project file.
<p>For our example, we can specify the object dir in this way:
<pre class="smallexample"> <b>project</b> Build <b>is</b>
<b>for</b> Source_Dirs <b>use</b> ("common");
<b>for</b> Object_Dir <b>use</b> "obj"; -- <<<<
<b>end</b> Build;
</pre>
<p class="noindent">As mentioned earlier, there is a single object directory per project. As a
result, if you have an existing system where the object files are spread in
several directories, you can either move all of them into the same directory if
you want to build it with a single project file, or study the section on
subsystems (see <a href="#Organizing-Projects-into-Subsystems">Organizing Projects into Subsystems</a>) to see how each
separate object directory can be associated with one of the subsystem
constituting the application.
<p>When the <span class="command">linker</span> is called, it usually creates an executable. By
default, this executable is placed in the object directory of the project. It
might be convenient to store it in its own directory.
<p><a name="index-_0040code_007bExec_005fDir_007d-14"></a>This can be done through the <code>Exec_Dir</code> attribute, which, like
<em>Object_Dir</em> contains a single absolute or relative path and must point to
an existing and writable directory, unless you ask the tool to create it on
your behalf. When not specified, It defaults to the object directory and
therefore to the project file's directory if neither <em>Object_Dir</em> nor
<em>Exec_Dir</em> was specified.
<p>In the case of the example, let's place the executable in the root
of the hierarchy, ie the same directory as <span class="file">build.gpr</span>. Hence
the project file is now
<pre class="smallexample"> <b>project</b> Build <b>is</b>
<b>for</b> Source_Dirs <b>use</b> ("common");
<b>for</b> Object_Dir <b>use</b> "obj";
<b>for</b> Exec_Dir <b>use</b> "."; -- <<<<
<b>end</b> Build;
</pre>
<!-- -->
<p><a name="Main-Subprograms"></a>
<h4 class="subsection">1.2.3 Main Subprograms</h4>
<!-- -->
<p class="noindent">In the previous section, executables were mentioned. The project manager needs
to be taught what they are. In a project file, an executable is indicated by
pointing to source file of the main subprogram. In C this is the file that
contains the <code>main</code> function, and in Ada the file that contains the main
unit.
<p>There can be any number of such main files within a given project, and thus
several executables can be built in the context of a single project file. Of
course, one given executable might not (and in fact will not) need all the
source files referenced by the project. As opposed to other build environments
such as <span class="command">makefile</span>, one does not need to specify the list of
dependencies of each executable, the project-aware builders knows enough of the
semantics of the languages to build ands link only the necessary elements.
<p><a name="index-_0040code_007bMain_007d-15"></a>The list of main files is specified via the <b>Main</b> attribute. It contains
a list of file names (no directories). If a project defines this
attribute, it is not necessary to identify main files on the
command line when invoking a builder, and editors like
<span class="command">GPS</span> will be able to create extra menus to spawn or debug the
corresponding executables.
<pre class="smallexample"> <b>project</b> Build <b>is</b>
<b>for</b> Source_Dirs <b>use</b> ("common");
<b>for</b> Object_Dir <b>use</b> "obj";
<b>for</b> Exec_Dir <b>use</b> ".";
<b>for</b> Main <b>use</b> ("proc.adb"); -- <<<<
<b>end</b> Build;
</pre>
<p class="noindent">If this attribute is defined in the project, then spawning the builder
with a command such as
<pre class="smallexample"> gnatmake -Pbuild
</pre>
<p class="noindent">automatically builds all the executables corresponding to the files
listed in the <em>Main</em> attribute. It is possible to specify one
or more executables on the command line to build a subset of them.
<!-- -->
<p><a name="Tools-Options-in-Project-Files"></a>
<h4 class="subsection">1.2.4 Tools Options in Project Files</h4>
<!-- -->
<p class="noindent">We now have a project file that fully describes our environment, and can be
used to build the application with a simple <span class="command">gnatmake</span> command as seen
in the previous section. In fact, the empty project we showed immediately at
the beginning (with no attribute at all) could already fullfill that need if it
was put in the <span class="file">common</span> directory.
<p>Of course, we always want more control. This section will show you how to
specify the compilation switches that the various tools involved in the
building of the executable should use.
<p><a name="index-command-line-length-16"></a>Since source names and locations are described into the project file, it is not
necessary to use switches on the command line for this purpose (switches such
as -I for gcc). This removes a major source of command line length overflow.
Clearly, the builders will have to communicate this information one way or
another to the underlying compilers and tools they call but they usually use
response files for this and thus should not be subject to command line
overflows.
<p>Several tools are participating to the creation of an executable: the compiler
produces object files from the source files; the binder (in the Ada case)
creates an source file that takes care, among other things, of elaboration
issues and global variables initialization; and the linker gathers everything
into a single executable that users can execute. All these tools are known by
the project manager and will be called with user defined switches from the
project files. However, we need to introduce a new project file concept to
express which switches to be used for any of the tools involved in the build.
<p><a name="index-project-file-packages-17"></a>A project file is subdivided into zero or more <b>packages</b>, each of which
contains the attributes specific to one tool (or one set of tools). Project
files use an Ada-like syntax for packages. Package names permitted in project
files are restricted to a predefined set (see <a href="#Packages">Packages</a>), and the contents
of packages are limited to a small set of constructs and attributes
(see <a href="#Attributes">Attributes</a>).
<p>Our example project file can be extended with the following empty packages. At
this stage, they could all be omitted since they are empty, but they show which
packages would be involved in the build process.
<pre class="smallexample"> <b>project</b> Build <b>is</b>
<b>for</b> Source_Dirs <b>use</b> ("common");
<b>for</b> Object_Dir <b>use</b> "obj";
<b>for</b> Exec_Dir <b>use</b> ".";
<b>for</b> Main <b>use</b> ("proc.adb");
<b>end</b> Build;
<b>package</b> Builder <b>is</b> --<<< for gnatmake and gprbuild
<b>end</b> Builder;
<b>package</b> Compiler <b>is</b> --<<< for the compiler
<b>end</b> Compiler;
<b>package</b> Binder <b>is</b> --<<< for the binder
<b>end</b> Binder;
<b>package</b> Linker <b>is</b> --<<< for the linker
<b>end</b> Linker;
</pre>
<p class="noindent">Let's first examine the compiler switches. As stated in the initial description
of the example, we want to compile all files with <span class="option">-O2</span>. This is a
compiler switch, although it is usual, on the command line, to pass it to the
builder which then passes it to the compiler. It is recommended to use directly
the right package, which will make the setup easier to understand for other
people.
<p>Several attributes can be used to specify the switches:
<dl>
<dt><b>Default_Switches</b>:<dd><a name="index-_0040code_007bDefault_005fSwitches_007d-18"></a> This is the first mention in this manual of an <b>indexed attribute</b>. When
this attribute is defined, one must supply an <em>index</em> in the form of a
literal string.
In the case of <em>Default_Switches</em>, the index is the name of the
language to which the switches apply (since a different compiler will
likely be used for each language, and each compiler has its own set of
switches). The value of the attribute is a list of switches.
<p>In this example, we want to compile all Ada source files with the
<span class="option">-O2</span> switch, and the resulting project file is as follows
(only the <code>Compiler</code> package is shown):
<pre class="smallexample"> <b>package</b> Compiler <b>is</b>
<b>for</b> Default_Switches ("Ada") <b>use</b> ("-O2");
<b>end</b> Compiler;
</pre>
<br><dt><b>Switches</b>:<dd><a name="index-_0040code_007bSwitches_007d-19"></a> in some cases, we might want to use specific switches
for one or more files. For instance, compiling <span class="file">proc.adb</span> might not be
possible at high level of optimization because of a compiler issue.
In such a case, the <em>Switches</em>
attribute (indexed on the file name) can be used and will override the
switches defined by <em>Default_Switches</em>. Our project file would
become:
<pre class="smallexample"> <b>package</b> Compiler <b>is</b>
<b>for</b> Default_Switches ("Ada") <b>use</b> ("-O2");
<b>for</b> Switches ("proc.adb") <b>use</b> ("-O0");
<b>end</b> Compiler;
</pre>
<p class="noindent"><code>Switches</code> can also be given a language name as index instead of a file
name in which case it has the same semantics as <em>Default_Switches</em>.
<br><dt><b>Local_Configuration_Pragmas</b>:<dd><a name="index-_0040code_007bLocal_005fConfiguration_005fPragmas_007d-20"></a> this attribute may specify the path
of a file containing configuration pragmas for use by the Ada compiler,
such as <code>pragma Restrictions (No_Tasking)</code>. These pragmas will be
used for all the sources of the project.
</dl>
<p>The switches for the other tools are defined in a similar manner through the
<b>Default_Switches</b> and <b>Switches</b> attributes, respectively in the
<em>Builder</em> package (for <span class="command">gnatmake</span> and <span class="command">gprbuild</span>),
the <em>Binder</em> package (binding Ada executables) and the <em>Linker</em>
package (for linking executables).
<!-- -->
<p><a name="Compiling-with-Project-Files"></a>
<h4 class="subsection">1.2.5 Compiling with Project Files</h4>
<!-- -->
<p class="noindent">Now that our project files are written, let's build our executable.
Here is the command we would use from the command line:
<pre class="smallexample"> gnatmake -Pbuild
</pre>
<p class="noindent">This will automatically build the executables specified through the
<em>Main</em> attribute: for each, it will compile or recompile the
sources for which the object file does not exist or is not up-to-date; it
will then run the binder; and finally run the linker to create the
executable itself.
<p><span class="command">gnatmake</span> only knows how to handle Ada files. By using
<span class="command">gprbuild</span> as a builder, you could automatically manage C files the
same way: create the file <span class="file">utils.c</span> in the <span class="file">common</span> directory,
set the attribute <em>Languages</em> to <code>"(Ada, C)"</code>, and run
<pre class="smallexample"> gprbuild -Pbuild
</pre>
<p class="noindent">Gprbuild knows how to recompile the C files and will
recompile them only if one of their dependencies has changed. No direct
indication on how to build the various elements is given in the
project file, which describes the project properties rather than a
set of actions to be executed. Here is the invocation of
<span class="command">gprbuild</span> when building a multi-language program:
<pre class="smallexample"> $ gprbuild -Pbuild
gcc -c proc.adb
gcc -c pack.adb
gcc -c utils.c
gprbind proc
...
gcc proc.o -o proc
</pre>
<p class="noindent">Notice the three steps described earlier:
<ul>
<li>The first three gcc commands correspond to the compilation phase.
<li>The gprbind command corresponds to the post-compilation phase.
<li>The last gcc command corresponds to the final link.
</ul>
<p class="noindent"><a name="index-_0040option_007b_002dv_007d-option-_0028for-GPRbuild_0029-21"></a>The default output of GPRbuild's execution is kept reasonably simple and easy
to understand. In particular, some of the less frequently used commands are not
shown, and some parameters are abbreviated. So it is not possible to rerun the
effect ofthe gprbuild command by cut-and-pasting its output. GPRbuild's option
<code>-v</code> provides a much more verbose output which includes, among other
information, more complete compilation, post-compilation and link commands.
<!-- -->
<p><a name="Executable-File-Names"></a>
<h4 class="subsection">1.2.6 Executable File Names</h4>
<!-- -->
<p class="noindent"><a name="index-_0040code_007bExecutable_007d-22"></a>By default, the executable name corresponding to a main file is
computed from the main source file name. Through the attribute
<b>Builder.Executable</b>, it is possible to change this default.
<p>For instance, instead of building <span class="command">proc</span> (or <span class="command">proc.exe</span>
on Windows), we could configure our project file to build "proc1"
(resp proc1.exe) with the following addition:
<pre class="smallexample"> project Build is
... -- same as before
package Builder is
for Executable ("proc.adb") use "proc1";
end Builder
end Build;
</pre>
<p class="noindent"><a name="index-_0040code_007bExecutable_005fSuffix_007d-23"></a>Attribute <b>Executable_Suffix</b>, when specified, may change the suffix
of the executable files, when no attribute <code>Executable</code> applies:
its value replace the platform-specific executable suffix.
The default executable suffix is empty on UNIX and ".exe" on Windows.
<p>It is also possible to change the name of the produced executable by using the
command line switch <span class="option">-o</span>. When several mains are defined in the project,
it is not possible to use the <span class="option">-o</span> switch and the only way to change the
names of the executable is provided by Attributes <code>Executable</code> and
<code>Executable_Suffix</code>.
<!-- -->
<p><a name="Avoid-Duplication-With-Variables"></a>
<h4 class="subsection">1.2.7 Avoid Duplication With Variables</h4>
<!-- -->
<p class="noindent">To illustrate some other project capabilities, here is a slightly more complex
project using similar sources and a main program in C:
<pre class="smallexample"> project C_Main is
for Languages use ("Ada", "C");
for Source_Dirs use ("common");
for Object_Dir use "obj";
for Main use ("main.c");
package Compiler is
C_Switches := ("-pedantic");
for Default_Switches ("C") use C_Switches;
for Default_Switches ("Ada") use ("-gnaty");
for Switches ("main.c") use C_Switches & ("-g");
end Compiler;
end C_Main;
</pre>
<p class="noindent">This project has many similarities with the previous one.
As expected, its <code>Main</code> attribute now refers to a C source.
The attribute <em>Exec_Dir</em> is now omitted, thus the resulting
executable will be put in the directory <span class="file">obj</span>.
<p>The most noticeable difference is the use of a variable in the
<em>Compiler</em> package to store settings used in several attributes.
This avoids text duplication, and eases maintenance (a single place to
modify if we want to add new switches for C files). We will revisit
the use of variables in the context of scenarios (see <a href="#Scenarios-in-Projects">Scenarios in Projects</a>).
<p>In this example, we see how the file <span class="file">main.c</span> can be compiled with
the switches used for all the other C files, plus <span class="option">-g</span>.
In this specific situation the use of a variable could have been
replaced by a reference to the <code>Default_Switches</code> attribute:
<pre class="smallexample"> for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
</pre>
<p class="noindent">Note the tick (<em>'</em>) used to refer to attributes defined in a package.
<p>Here is the output of the GPRbuild command using this project:
<pre class="smallexample"> $gprbuild -Pc_main
gcc -c -pedantic -g main.c
gcc -c -gnaty proc.adb
gcc -c -gnaty pack.adb
gcc -c -pedantic utils.c
gprbind main.bexch
...
gcc main.o -o main
</pre>
<p class="noindent">The default switches for Ada sources,
the default switches for C sources (in the compilation of <span class="file">lib.c</span>),
and the specific switches for <span class="file">main.c</span> have all been taken into
account.
<!-- -->
<p><a name="Naming-Schemes"></a>
<h4 class="subsection">1.2.8 Naming Schemes</h4>
<!-- -->
<p class="noindent">Sometimes an Ada software system is ported from one compilation environment to
another (say GNAT), and the file are not named using the default GNAT
conventions. Instead of changing all the file names, which for a variety of
reasons might not be possible, you can define the relevant file naming scheme
in the <b>Naming</b> package of your project file.
<p>The naming scheme has two distinct goals for the project manager: it
allows finding of source files when searching in the source
directories, and given a source file name it makes it possible to guess
the associated language, and thus the compiler to use.
<p>Note that the use by the Ada compiler of pragmas Source_File_Name is not
supported when using project files. You must use the features described in this
paragraph. You can however specify other configuration pragmas
(see <a href="#Specifying-Configuration-Pragmas">Specifying Configuration Pragmas</a>).
<p>The following attributes can be defined in package <code>Naming</code>:
<dl>
<dt><b>Casing</b>:<dd><a name="index-_0040code_007bCasing_007d-24"></a> Its value must be one of <code>"lowercase"</code> (the default if
unspecified), <code>"uppercase"</code> or <code>"mixedcase"</code>. It describes the
casing of file names with regards to the Ada unit name. Given an Ada unit
My_Unit, the file name will respectively be <span class="file">my_unit.adb</span> (lowercase),
<span class="file">MY_UNIT.ADB</span> (uppercase) or <span class="file">My_Unit.adb</span> (mixedcase).
On Windows, file names are case insensitive, so this attribute is
irrelevant.
<br><dt><b>Dot_Replacement</b>:<dd><a name="index-_0040code_007bDot_005fReplacement_007d-25"></a> This attribute specifies the string that should replace the "." in unit
names. Its default value is <code>"-"</code> so that a unit
<code>Parent.Child</code> is expected to be found in the file
<span class="file">parent-child.adb</span>. The replacement string must satisfy the following
requirements to avoid ambiguities in the naming scheme:
<ul>
<li>It must not be empty
<li>It cannot start or end with an alphanumeric character
<li>It cannot be a single underscore
<li>It cannot start with an underscore followed by an alphanumeric
<li>It cannot contain a dot <code>'.'</code> except if the entire string
is <code>"."</code>
</ul>
<br><dt><b>Spec_Suffix</b> and <b>Specification_Suffix</b>:<dd><a name="index-_0040code_007bSpec_005fSuffix_007d-26"></a><a name="index-_0040code_007bSpecification_005fSuffix_007d-27"></a> For Ada, these attributes give the suffix used in file names that contain
specifications. For other languages, they give the extension for files
that contain declaration (header files in C for instance). The attribute
is indexed on the language.
The two attributes are equivalent, but the latter is obsolescent.
If <code>Spec_Suffix ("Ada")</code> is not specified, then the default is
<code>".ads"</code>.
The value must satisfy the following requirements:
<ul>
<li>It must not be empty
<li>It cannot start with an alphanumeric character
<li>It cannot start with an underscore followed by an alphanumeric character
<li>It must include at least one dot
</ul>
<br><dt><b>Body_Suffix</b> and <b>Implementation_Suffix</b>:<dd><a name="index-_0040code_007bBody_005fSuffix_007d-28"></a><a name="index-_0040code_007bImplementation_005fSuffix_007d-29"></a> These attributes give the extension used for file names that contain
code (bodies in Ada). They are indexed on the language. The second
version is obsolescent and fully replaced by the first attribute.
<p>These attributes must satisfy the same requirements as <code>Spec_Suffix</code>.
In addition, they must be different from any of the values in
<code>Spec_Suffix</code>.
If <code>Body_Suffix ("Ada")</code> is not specified, then the default is
<code>".adb"</code>.
<p>If <code>Body_Suffix ("Ada")</code> and <code>Spec_Suffix ("Ada")</code> end with the
same string, then a file name that ends with the longest of these two
suffixes will be a body if the longest suffix is <code>Body_Suffix ("Ada")</code>
or a spec if the longest suffix is <code>Spec_Suffix ("Ada")</code>.
<p>If the suffix does not start with a '.', a file with a name exactly equal
to the suffix will also be part of the project (for instance if you define
the suffix as <code>Makefile</code>, a file called <span class="file">Makefile</span> will be part
of the project. This capability is usually not interesting when building.
However, it might become useful when a project is also used to
find the list of source files in an editor, like the GNAT Programming System
(GPS).
<br><dt><b>Separate_Suffix</b>:<dd><a name="index-_0040code_007bSeparate_005fSuffix_007d-30"></a> This attribute is specific to Ada. It denotes the suffix used in file names
that contain separate bodies. If it is not specified, then it defaults to
same value as <code>Body_Suffix ("Ada")</code>. The same rules apply as for the
<code>Body_Suffix</code> attribute. The only accepted index is "Ada".
<br><dt><b>Spec</b> or <b>Specification</b>:<dd><a name="index-_0040code_007bSpec_007d-31"></a><a name="index-_0040code_007bSpecification_007d-32"></a> This attribute <code>Spec</code> can be used to define the source file name for a
given Ada compilation unit's spec. The index is the literal name of the Ada
unit (case insensitive). The value is the literal base name of the file that
contains this unit's spec (case sensitive or insensitive depending on the
operating system). This attribute allows the definition of exceptions to the
general naming scheme, in case some files do not follow the usual
convention.
<p>When a source file contains several units, the relative position of the unit
can be indicated. The first unit in the file is at position 1
<pre class="smallexample"> for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
for Spec ("top") use "foo.a" at 1;
for Spec ("foo") use "foo.a" at 2;
</pre>
<br><dt><b>Body</b> or <b>Implementation</b>:<dd><a name="index-_0040code_007bBody_007d-33"></a><a name="index-_0040code_007bImplementation_007d-34"></a> These attribute play the same role as <em>Spec</em> for Ada bodies.
<br><dt><b>Specification_Exceptions</b> and <b>Implementation_Exceptions</b>:<dd><a name="index-_0040code_007bSpecification_005fExceptions_007d-35"></a><a name="index-_0040code_007bImplementation_005fExceptions_007d-36"></a> These attributes define exceptions to the naming scheme for languages
other than Ada. They are indexed on the language name, and contain
a list of file names respectively for headers and source code.
</dl>
<p>For example, the following package models the Apex file naming rules:
<pre class="smallexample"> package Naming is
for Casing use "lowercase";
for Dot_Replacement use ".";
for Spec_Suffix ("Ada") use ".1.ada";
for Body_Suffix ("Ada") use ".2.ada";
end Naming;
</pre>
<!-- -->
<p><a name="Organizing-Projects-into-Subsystems"></a>
<h3 class="section">1.3 Organizing Projects into Subsystems</h3>
<!-- -->
<p class="noindent">A <b>subsystem</b> is a coherent part of the complete system to be built. It is
represented by a set of sources and one single object directory. A system can
be composed of a single subsystem when it is simple as we have seen in the
first section. Complex systems are usually composed of several interdependent
subsystems. A subsystem is dependent on another subsystem if knowledge of the
other one is required to build it, and in particular if visibility on some of
the sources of this other subsystem is required. Each subsystem is usually
represented by its own project file.
<p>In this section, the previous example is being extended. Let's assume some
sources of our <code>Build</code> project depend on other sources.
For instance, when building a graphical interface, it is usual to depend upon
a graphical library toolkit such as GtkAda. Furthermore, we also need
sources from a logging module we had previously written.
<!-- -->
<p><a name="Project-Dependencies"></a>
<h4 class="subsection">1.3.1 Project Dependencies</h4>
<!-- -->
<p class="noindent">GtkAda comes with its own project file (appropriately called
<span class="file">gtkada.gpr</span>), and we will assume we have already built a project
called <span class="file">logging.gpr</span> for the logging module. With the information provided
so far in <span class="file">build.gpr</span>, building the application would fail with an error
indicating that the gtkada and logging units that are relied upon by the sources
of this project cannot be found.
<p>This is easily solved by adding the following <b>with</b> clauses at the beginning
of our project:
<pre class="smallexample"> with "gtkada.gpr";
with "a/b/logging.gpr";
project Build is
... -- as before
end Build;
</pre>
<p class="noindent"><a name="index-_0040code_007bExternally_005fBuilt_007d-37"></a>When such a project is compiled, <span class="command">gnatmake</span> will automatically
check the other projects and recompile their sources when needed. It will also
recompile the sources from <code>Build</code> when needed, and finally create the
executable. In some cases, the implementation units needed to recompile a
project are not available, or come from some third-party and you do not want to
recompile it yourself. In this case, the attribute <b>Externally_Built</b> to
"true" can be set, indicating to the builder that this project can be assumed
to be up-to-date, and should not be considered for recompilation. In Ada, if
the sources of this externally built project were compiled with another version
of the compiler or with incompatible options, the binder will issue an error.
<p>The project's <code>with</code> clause has several effects. It provides source
visibility between projects during the compilation process. It also guarantees
that the necessary object files from <code>Logging</code> and <code>GtkAda</code> are
available when linking <code>Build</code>.
<p>As can be seen in this example, the syntax for importing projects is similar
to the syntax for importing compilation units in Ada. However, project files
use literal strings instead of names, and the <code>with</code> clause identifies
project files rather than packages.
<p>Each literal string after <code>with</code> is the path
(absolute or relative) to a project file. The <code>.gpr</code> extension is
optional, although we recommend adding it. If no extension is specified,
and no project file with the <span class="file">.gpr</span> extension is found, then
the file is searched for exactly as written in the <code>with</code> clause,
that is with no extension.
<p><a name="index-project-path-38"></a>When a relative path or a base name is used, the
project files are searched relative to each of the directories in the
<b>project path</b>. This path includes all the directories found with the
following algorithm, in that order, as soon as a matching file is found,
the search stops:
<ul>
<li>First, the file is searched relative to the directory that contains the
current project file.
<li><a name="index-_0040code_007bADA_005fPROJECT_005fPATH_007d-39"></a><a name="index-_0040code_007bGPR_005fPROJECT_005fPATH_007d-40"></a> Then it is searched relative to all the directories specified in the
environment variables <b>GPR_PROJECT_PATH</b> and
<b>ADA_PROJECT_PATH</b> (in that order) if they exist. The former is
recommended, the latter is kept for backward compatibility.
<li>Finally, it is searched relative to the default project directories.
Such directories depends on the tool used. For <span class="command">gnatmake</span>, there is
one default project directory: <span class="file"><prefix>/lib/gnat/</span>. In our example,
<span class="file">gtkada.gpr</span> is found in the predefined directory if it was installed at
the same root as GNAT.
</ul>
<p class="noindent">Some tools also support extending the project path from the command line,
generally through the <span class="option">-aP</span>. You can see the value of the project
path by using the <span class="command">gnatls -v</span> command.
<p>Any symbolic link will be fully resolved in the directory of the
importing project file before the imported project file is examined.
<p>Any source file in the imported project can be used by the sources of the
importing project, transitively.
Thus if <code>A</code> imports <code>B</code>, which imports <code>C</code>, the sources of
<code>A</code> may depend on the sources of <code>C</code>, even if <code>A</code> does not
import <code>C</code> explicitly. However, this is not recommended, because if
and when <code>B</code> ceases to import <code>C</code>, some sources in <code>A</code> will
no longer compile. <span class="command">gprbuild</span> has a switch <span class="option">--no-indirect-imports</span>
that will report such indirect dependencies.
<p>One very important aspect of a project hierarchy is that
<b>a given source can only belong to one project</b> (otherwise the project manager
would not know which settings apply to it and when to recompile it). It means
that different project files do not usually share source directories or
when they do, they need to specify precisely which project owns which sources
using attribute <code>Source_Files</code> or equivalent. By contrast, 2 projects
can each own a source with the same base file name as long as they live in
different directories. The latter is not true for Ada Sources because of the
correlation betwen source files and Ada units.
<!-- -->
<p><a name="Cyclic-Project-Dependencies"></a>
<h4 class="subsection">1.3.2 Cyclic Project Dependencies</h4>
<!-- -->
<p class="noindent">Cyclic dependencies are mostly forbidden:
if <code>A</code> imports <code>B</code> (directly or indirectly) then <code>B</code>
is not allowed to import <code>A</code>. However, there are cases when cyclic
dependencies would be beneficial. For these cases, another form of import
between projects exists: the <b>limited with</b>. A project <code>A</code> that
imports a project <code>B</code> with a straight <code>with</code> may also be imported,
directly or indirectly, by <code>B</code> through a <code>limited with</code>.
<p>The difference between straight <code>with</code> and <code>limited with</code> is that
the name of a project imported with a <code>limited with</code> cannot be used in the
project importing it. In particular, its packages cannot be renamed and
its variables cannot be referred to.
<pre class="smallexample"> with "b.gpr";
with "c.gpr";
project A is
For Exec_Dir use B'Exec_Dir; -- ok
end A;
limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
project B is
For Exec_Dir use A'Exec_Dir; -- not ok
end B;
with "d.gpr";
project C is
end C;
limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
project D is
For Exec_Dir use A'Exec_Dir; -- not ok
end D;
</pre>
<!-- -->
<p><a name="Sharing-Between-Projects"></a>
<h4 class="subsection">1.3.3 Sharing Between Projects</h4>
<!-- -->
<p class="noindent">When building an application, it is common to have similar needs in severa of
the projects corresponding to the subsystems under construction. For instance,
they will all have the same compilation switches.
<p>As seen before (see <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a>), setting compilation
switches for all sources of a subsystem is simple: it is just a matter of
adding a <code>Compiler.Default_Switches</code> attribute to each project files with
the same value. Of course, that means duplication of data, and both places need
to be changed in order to recompile the whole application with different
switches. It can become a real problem if there are many subsystems and thus
many project files to edit.
<p>There are two main approaches to avoiding this duplication:
<ul>
<li>Since <span class="file">build.gpr</span> imports <span class="file">logging.gpr</span>, we could change it
to reference the attribute in Logging, either through a package renaming,
or by referencing the attribute. The following example shows both cases:
<pre class="smallexample"> project Logging is
package Compiler is
for Switches ("Ada") use ("-O2");
end Compiler;
package Binder is
for Switches ("Ada") use ("-E");
end Binder;
end Logging;
with "logging.gpr";
project Build is
package Compiler renames Logging.Compiler;
package Binder is
for Switches ("Ada") use Logging.Binder'Switches ("Ada");
end Binder;
end Build;
</pre>
<p class="noindent">The solution used for <code>Compiler</code> gets the same value for all
attributes of the package, but you cannot modify anything from the
package (adding extra switches or some exceptions). The second
version is more flexible, but more verbose.
<p>If you need to refer to the value of a variable in an imported
project, rather than an attribute, the syntax is similar but uses
a "." rather than an apostrophe. For instance:
<pre class="smallexample"> with "imported";
project Main is
Var1 := Imported.Var;
end Main;
</pre>
<li>The second approach is to define the switches in a third project.
That project is setup without any sources (so that, as opposed to
the first example, none of the project plays a special role), and
will only be used to define the attributes. Such a project is
typically called <span class="file">shared.gpr</span>.
<pre class="smallexample"> abstract project Shared is
for Source_Files use (); -- no project
package Compiler is
for Switches ("Ada") use ("-O2");
end Compiler;
end Shared;
with "shared.gpr";
project Logging is
package Compiler renames Shared.Compiler;
end Logging;
with "shared.gpr";
project Build is
package Compiler renames Shared.Compiler;
end Build;
</pre>
<p class="noindent">As for the first example, we could have chosen to set the attributes
one by one rather than to rename a package. The reason we explicitly
indicate that <code>Shared</code> has no sources is so that it can be created
in any directory and we are sure it shares no sources with <code>Build</code>
or <code>Logging</code>, which of course would be invalid.
<p><a name="index-project-qualifier-41"></a> Note the additional use of the <b>abstract</b> qualifier in <span class="file">shared.gpr</span>.
This qualifier is optional, but helps convey the message that we do not
intend this project to have sources (see <a href="#Qualified-Projects">Qualified Projects</a> for
more qualifiers).
</ul>
<!-- -->
<p><a name="Global-Attributes"></a>
<h4 class="subsection">1.3.4 Global Attributes</h4>
<!-- -->
<p class="noindent">We have already seen many examples of attributes used to specify a special
option of one of the tools involved in the build process. Most of those
attributes are project specific. That it to say, they only affect the invocation
of tools on the sources of the project where they are defined.
<p>There are a few additional attributes that apply to all projects in a
hierarchy as long as they are defined on the "main" project.
The main project is the project explicitly mentioned on the command-line.
The project hierarchy is the "with"-closure of the main project.
<p>Here is a list of commonly used global attributes:
<dl>
<dt><b>Builder.Global_Configuration_Pragmas</b>:<dd><a name="index-_0040code_007bGlobal_005fConfiguration_005fPragmas_007d-42"></a> This attribute points to a file that contains configuration pragmas
to use when building executables. These pragmas apply for all
executables build from this project hierarchy. As we have seen before,
additional pragmas can be specified on a per-project basis by setting the
<code>Compiler.Local_Configuration_Pragmas</code> attribute.
<br><dt><b>Builder.Global_Compilation_Switches</b>:<dd><a name="index-_0040code_007bGlobal_005fCompilation_005fSwitches_007d-43"></a> This attribute is a list of compiler switches to use when compiling any
source file in the project hierarchy. These switches are used in addition
to the ones defined in the <code>Compiler</code> package, which only apply to
the sources of the corresponding project. This attribute is indexed on
the name of the language.
</dl>
<p>Using such global capabilities is convenient. It can also lead to unexpected
behavior. Especially when several subsystems are shared among different main
projects and the different global attributes are not
compatible. Note that using aggregate projects can be a safer and more powerful
replacement to global attributes.
<!-- -->
<p><a name="Scenarios-in-Projects"></a>
<h3 class="section">1.4 Scenarios in Projects</h3>
<!-- -->
<p class="noindent">Various aspects of the projects can be modified based on <b>scenarios</b>. These
are user-defined modes that change the behavior of a project. Typical
examples are the setup of platform-specific compiler options, or the use of
a debug and a release mode (the former would activate the generation of debug
information, when the second will focus on improving code optimization).
<p>Let's enhance our example to support a debug and a release modes.The issue is to
let the user choose what kind of system he is building:
use <span class="option">-g</span> as compiler switches in debug mode and <span class="option">-O2</span>
in release mode. We will also setup the projects so that we do not share the
same object directory in both modes, otherwise switching from one to the other
might trigger more recompilations than needed or mix objects from the 2 modes.
<p>One naive approach is to create two different project files, say
<span class="file">build_debug.gpr</span> and <span class="file">build_release.gpr</span>, that set the appropriate
attributes as explained in previous sections. This solution does not scale well,
because in presence of multiple projects depending on each other,
you will also have to duplicate the complete hierarchy and adapt the project
files to point to the right copies.
<p><a name="index-scenarios-44"></a>Instead, project files support the notion of scenarios controlled
by external values. Such values can come from several sources (in decreasing
order of priority):
<dl>
<dt><b>Command line</b>:<dd><a name="index-_0040option_007b_002dX_007d-45"></a> When launching <span class="command">gnatmake</span> or <span class="command">gprbuild</span>, the user can pass
extra <span class="option">-X</span> switches to define the external value. In
our case, the command line might look like
<pre class="smallexample"> gnatmake -Pbuild.gpr -Xmode=debug
or gnatmake -Pbuild.gpr -Xmode=release
</pre>
<br><dt><b>Environment variables</b>:<dd> When the external value does not come from the command line, it can come from
the value of environment variables of the appropriate name.
In our case, if an environment variable called "mode"
exist, its value will be taken into account.
<br><dt><b>External function second parameter</b><dd>
</dl>
<p><a name="index-_0040code_007bexternal_007d-46"></a>We now need to get that value in the project. The general form is to use
the predefined function <b>external</b> which returns the current value of
the external. For instance, we could setup the object directory to point to
either <span class="file">obj/debug</span> or <span class="file">obj/release</span> by changing our project to
<pre class="smallexample"> project Build is
for Object_Dir use "obj/" & external ("mode", "debug");
... -- as before
end Build;
</pre>
<p class="noindent">The second parameter to <code>external</code> is optional, and is the default
value to use if "mode" is not set from the command line or the environment.
<p>In order to set the switches according to the different scenarios, other
constructs have to be introduced such as typed variables and case statements.
<p><a name="index-typed-variable-47"></a><a name="index-case-statement-48"></a>A <b>typed variable</b> is a variable that
can take only a limited number of values, similar to an enumeration in Ada.
Such a variable can then be used in a <b>case statement</b> and create conditional
sections in the project. The following example shows how this can be done:
<pre class="smallexample"> project Build is
type Mode_Type is ("debug", "release"); -- all possible values
Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
package Compiler is
case Mode is
when "debug" =>
for Switches ("Ada") use ("-g");
when "release" =>
for Switches ("Ada") use ("-O2");
end case;
end Compiler;
end Build;
</pre>
<p class="noindent">The project has suddenly grown in size, but has become much more flexible.
<code>Mode_Type</code> defines the only valid values for the <code>mode</code> variable. If
any other value is read from the environment, an error is reported and the
project is considered as invalid.
<p>The <code>Mode</code> variable is initialized with an external value
defaulting to <code>"debug"</code>. This default could be omitted and that would
force the user to define the value. Finally, we can use a case statement to set the
switches depending on the scenario the user has chosen.
<p>Most aspects of the projects can depend on scenarios. The notable exception
are project dependencies (<code>with</code> clauses), which may not depend on a scenario.
<p>Scenarios work the same way with <b>project hierarchies</b>: you can either
duplicate a variable similar to <code>Mode</code> in each of the project (as long
as the first argument to <code>external</code> is always the same and the type is
the same), or simply set the variable in the <span class="file">shared.gpr</span> project
(see <a href="#Sharing-Between-Projects">Sharing Between Projects</a>).
<!-- -->
<p><a name="Library-Projects"></a>
<h3 class="section">1.5 Library Projects</h3>
<!-- -->
<p class="noindent">So far, we have seen examples of projects that create executables. However,
it is also possible to create libraries instead. A <b>library</b> is a specific
type of subsystem where, for convenience, objects are grouped together
using system-specific means such as archives or windows DLLs.
<p>Library projects provide a system- and language-independent way of building both <b>static</b>
and <b>dynamic</b> libraries. They also support the concept of <b>standalone
libraries</b> (SAL) which offers two significant properties: the elaboration
(e.g. initialization) of the library is either automatic or very simple;
a change in the
implementation part of the library implies minimal post-compilation actions on
the complete system and potentially no action at all for the rest of the
system in the case of dynamic SALs.
<p>The GNAT Project Manager takes complete care of the library build, rebuild and
installation tasks, including recompilation of the source files for which
objects do not exist or are not up to date, assembly of the library archive, and
installation of the library (i.e., copying associated source, object and
<span class="file">ALI</span> files to the specified location).
<!-- -->
<p><a name="Building-Libraries"></a>
<h4 class="subsection">1.5.1 Building Libraries</h4>
<!-- -->
<p class="noindent">Let's enhance our example and transform the <code>logging</code> subsystem into a
library.In orer to do so, a few changes need to be made to <span class="file">logging.gpr</span>.
A number of specific attributes needs to be defined: at least <code>Library_Name</code>
and <code>Library_Dir</code>; in addition, a number of other attributes can be used
to specify specific aspects of the library. For readablility, it is also
recommended (although not mandatory), to use the qualifier <code>library</code> in
front of the <code>project</code> keyword.
<dl>
<dt><b>Library_Name</b>:<dd><a name="index-_0040code_007bLibrary_005fName_007d-49"></a> This attribute is the name of the library to be built. There is no
restriction on the name of a library imposed by the project manager;
however, there may be system specific restrictions on the name.
In general, it is recommended to stick to alphanumeric characters
(and possibly underscores) to help portability.
<br><dt><b>Library_Dir</b>:<dd><a name="index-_0040code_007bLibrary_005fDir_007d-50"></a> This attribute is the path (absolute or relative) of the directory where
the library is to be installed. In the process of building a library,
the sources are compiled, the object files end up in the explicit or
implicit <code>Object_Dir</code> directory. When all sources of a library
are compiled, some of the compilation artifacts, including the library itself,
are copied to the library_dir directory. This directory must exists and be
writable. It must also be different from the object directory so that cleanup
activities in the Library_Dir do not affect recompilation needs.
</dl>
<p>Here is the new version of <span class="file">logging.gpr</span> that makes it a library:
<pre class="smallexample"> library project Logging is -- "library" is optional
for Library_Name use "logging"; -- will create "liblogging.a" on Unix
for Object_Dir use "obj";
for Library_Dir use "lib"; -- different from object_dir
end Logging;
</pre>
<p class="noindent">Once the above two attributes are defined, the library project is valid and
is enough for building a library with default characteristics.
Other library-related attributes can be used to change the defaults:
<dl>
<dt><b>Library_Kind</b>:<dd><a name="index-_0040code_007bLibrary_005fKind_007d-51"></a> The value of this attribute must be either <code>"static"</code>, <code>"dynamic"</code> or
<code>"relocatable"</code> (the latter is a synonym for dynamic). It indicates
which kind of library should be build (the default is to build a
static library, that is an archive of object files that can potentially
be linked into a static executable). When the library is set to be dynamic,
a separate image is created that will be loaded independnently, usually
at the start of the main program execution. Support for dynamic libraries is
very platform specific, for instance on Windows it takes the form of a DLL
while on GNU/Linux, it is a dynamic elf image whose suffix is usually
<span class="file">.so</span>. Library project files, on the other hand, can be written in
a platform independant way so that the same project file can be used to build
a library on different Oses.
<p>If you need to build both a static and a dynamic library, it is recommended
use two different object directories, since in some cases some extra code
needs to be generated for the latter. For such cases, one can
either define two different project files, or a single one which uses scenarios
to indicate at the various kinds of library to be build and their
corresponding object_dir.
<p><a name="index-_0040code_007bLibrary_005fALI_005fDir_007d-52"></a><br><dt><b>Library_ALI_Dir</b>:<dd> This attribute may be specified to indicate the directory where the ALI
files of the library are installed. By default, they are copied into the
<code>Library_Dir</code> directory, but as for the executables where we have a
separate <code>Exec_Dir</code> attribute, you might want to put them in a separate
directory since there can be hundreds of them. The same restrictions as for
the <code>Library_Dir</code> attribute apply.
<p><a name="index-_0040code_007bLibrary_005fVersion_007d-53"></a><br><dt><b>Library_Version</b>:<dd> This attribute is platform dependent, and has no effect on VMS and Windows.
On Unix, it is used only for dynamic libraries as the internal
name of the library (the <code>"soname"</code>). If the library file name (built
from the <code>Library_Name</code>) is different from the <code>Library_Version</code>,
then the library file will be a symbolic link to the actual file whose name
will be <code>Library_Version</code>. This follows the usual installation schemes
for dynamic libraries on many Unix systems.
<pre class="smallexample"> project Logging is
Version := "1";
for Library_Dir use "lib";
for Library_Name use "logging";
for Library_Kind use "dynamic";
for Library_Version use "liblogging.so." & Version;
end Logging;
</pre>
<p class="noindent">After the compilation, the directory <span class="file">lib</span> will contain both a
<span class="file">libdummy.so.1</span> library and a symbolic link to it called
<span class="file">libdummy.so</span>.
<p><a name="index-_0040code_007bLibrary_005fGCC_007d-54"></a><br><dt><b>Library_GCC</b>:<dd> This attribute is the name of the tool to use instead of "gcc" to link shared
libraries. A common use of this attribute is to define a wrapper script that
accomplishes specific actions before calling gcc (which itself is calling the
linker to build the library image).
<br><dt><b>Library_Options</b>:<dd><a name="index-_0040code_007bLibrary_005fOptions_007d-55"></a> This attribute may be used to specified additional switches (last switches)
when linking a shared library.
<br><dt><b>Leading_Library_Options</b>:<dd><a name="index-_0040code_007bLeading_005fLibrary_005fOptions_007d-56"></a> This attribute, that is taken into account only by <span class="command">gprbuild</span>, may be
used to specified leading options (first switches) when linking a shared
library.
<p><a name="index-_0040code_007bLinker_005fOptions_007d-57"></a><br><dt><b>Linker.Linker_Options</b>:<dd> This attribute specifies additional switches to be given to the linker when
linking an executable. It is ignored when defined in the main project and
taken into account in all other projects that are imported directly or
indirectly. These switches complement the <code>Linker.Switches</code>
defined in the main project. This is useful when a particular subsystem
depends on an external library: adding this dependency as a
<code>Linker_Options</code> in the project of the subsystem is more convenient than
adding it to all the <code>Linker.Switches</code> of the main projects that depend
upon this subsystem.
</dl>
<!-- -->
<p><a name="Using-Library-Projects"></a>
<h4 class="subsection">1.5.2 Using Library Projects</h4>
<!-- -->
<p class="noindent">When the builder detects that a project file is a library project file, it
recompiles all sources of the project that need recompilation and rebuild the
library if any of the sources have been recompiled. It then groups all object
files into a single file, which is a shared or a static library. This library
can later on be linked with multiple executables. Note that the use
of shard libraries reduces the size of the final executable and can also reduce
the memory footprint at execution time when the library is shared among several
executables.
<p>It is also possible to build <b>multi-language libraries</b>. When using
<span class="command">gprbuild</span> as a builder, multi-language library projects allow naturally
the creation of multi-language libraries . <span class="command">gnatmake</span>, does n ot try to
compile non Ada sources. However, when the project is multi-language, it will
automatically link all object files found in the object directory, whether or
not they were compiled from an Ada source file. This specific behavior does not
apply to Ada-only projects which only take into account the objects
corresponding to the sources of the project.
<p>A non-library project can import a library project. When the builder is invoked
on the former, the library of the latter is only rebuilt when absolutely
necessary. For instance, if a unit of the
library is not up-to-date but non of the executables need this unit, then the
unit is not recompiled and the library is not reassembled.
For instance, let's assume in our example that logging has the following
sources: <span class="file">log1.ads</span>, <span class="file">log1.adb</span>, <span class="file">log2.ads</span> and
<span class="file">log2.adb</span>. If <span class="file">log1.adb</span> has been modified, then the library
<span class="file">liblogging</span> will be rebuilt when compiling all the sources of
<code>Build</code> only if <span class="file">proc.ads</span>, <span class="file">pack.ads</span> or <span class="file">pack.adb</span>
include a <code>"with Log1"</code>.
<p>To ensure that all the sources in the <code>Logging</code> library are
up to date, and that all the sources of <code>Build</code> are also up to date,
the following two commands needs to be used:
<pre class="smallexample"> gnatmake -Plogging.gpr
gnatmake -Pbuild.gpr
</pre>
<p class="noindent">All <span class="file">ALI</span> files will also be copied from the object directory to the
library directory. To build executables, <span class="command">gnatmake</span> will use the
library rather than the individual object files.
<p>Library projects can also be useful to describe a library that need to be used
but, for some reason, cannot be rebuilt. For instance, it is the case when some
of the library sources are not available. Such library projects need simply to
use the <code>Externally_Built</code> attribute as in the example below:
<pre class="smallexample"> library project Extern_Lib is
for Languages use ("Ada", "C");
for Source_Dirs use ("lib_src");
for Library_Dir use "lib2";
for Library_Kind use "dynamic";
for Library_Name use "l2";
for Externally_Built use "true"; -- <<<<
end Extern_Lib;
</pre>
<p class="noindent">In the case of externally built libraries, the <code>Object_Dir</code>
attribute does not need to be specified because it will never be
used.
<p>The main effect of using such an externally built library project is mostly to
affect the linker command in order to reference the desired library. It can
also be achieved by using <code>Linker.Linker_Options</code> or <code>Linker.Switches</code>
in the project corresponding to the subsystem needing this external library.
This latter method is more straightforward in simple cases but when several
subsystems depend upon the same external library, finding the proper place
for the <code>Linker.Linker_Options</code> might not be easy and if it is
not placed properly, the final link command is likely to present ordering issues.
In such a situation, it is better to use the externally built library project
so that all other subsystems depending on it can declare this dependency thanks
to a project <code>with</code> clause, which in turn will trigger the builder to find
the proper order of libraries in the final link command.
<!-- -->
<p><a name="Stand_002dalone-Library-Projects"></a>
<h4 class="subsection">1.5.3 Stand-alone Library Projects</h4>
<!-- -->
<p class="noindent"><a name="index-standalone-libraries-58"></a>A <b>stand-alone library</b> is a library that contains the necessary code to
elaborate the Ada units that are included in the library. A stand-alone
library is a convenient way to add an Ada subsystem to a more global system
whose main is not in Ada since it makes the elaboration of the Ada part mostly
transparent. However, stand-alone libraries are also useful when the main is in
Ada: they provide a means for minimizing relinking & redeployement of complex
systems when localized changes are made.
<p>The most proeminent characteristic of a stand-alone library is that it offers a
distinction between interface units and implementation units. Only the former
are visible to units outside the library. A stand-alone library project is thus
characterised by a third attribute, <b>Library_Interface</b>, in addition to the
two attributes that make a project a Library Project (<code>Library_Name</code> and
<code>Library_Dir</code>).
<dl>
<dt><b>Library_Interface</b>:<dd><a name="index-_0040code_007bLibrary_005fInterface_007d-59"></a> This attribute defines an explicit subset of the units of the project.
Projects importing this library project may only "with" units whose sources
are listed in the <code>Library_Interface</code>. Other sources are considered
implementation units.
<pre class="smallexample"> for Library_Dir use "lib";
for Library_Name use "loggin";
for Library_Interface use ("lib1", "lib2"); -- unit names
</pre>
</dl>
<p>In order to include the elaboration code in the stand-alone library, the binder
is invoked on the closure of the library units creating a package whose name
depends on the library name (b~logging.ads/b in the example).
This binder-generated package includes <b>initialization</b> and <b>finalization</b>
procedures whose names depend on the library name (<code>logginginit</code> and
<code>loggingfinal</code> in the example). The object corresponding to this package is
included in the library.
<dl>
<dt><b>Library_Auto_Init</b>:<dd><a name="index-_0040code_007bLibrary_005fAuto_005fInit_007d-60"></a> A dynamic stand-alone Library is automatically initialized
if automatic initialization of Stand-alone Libraries is supported on the
platform and if attribute <b>Library_Auto_Init</b> is not specified or
is specified with the value "true". A static Stand-alone Library is never
automatically initialized. Specifying "false" for this attribute
prevent automatic initialization.
<p>When a non-automatically initialized stand-alone library is used in an
executable, its initialization procedure must be called before any service of
the library is used. When the main subprogram is in Ada, it may mean that the
initialization procedure has to be called during elaboration of another
package.
<br><dt><b>Library_Dir</b>:<dd><a name="index-_0040code_007bLibrary_005fDir_007d-61"></a> For a stand-alone library, only the <span class="file">ALI</span> files of the interface units
(those that are listed in attribute <code>Library_Interface</code>) are copied to
the library directory. As a consequence, only the interface units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
<br><dt><b>Binder.Default_Switches</b>:<dd> When a stand-alone library is bound, the switches that are specified in
the attribute <b>Binder.Default_Switches ("Ada")</b> are
used in the call to <span class="command">gnatbind</span>.
<br><dt><b>Library_Src_Dir</b>:<dd><a name="index-_0040code_007bLibrary_005fSrc_005fDir_007d-62"></a> This attribute defines the location (absolute or relative to the project
directory) where the sources of the interface units are copied at
installation time.
These sources includes the specs of the interface units along with the closure
of sources necessary to compile them successfully. That may include bodies and
subunits, when pragmas <code>Inline</code> are used, or when there is a generic
units in the spec. This directory cannot point to the object directory or
one of the source directories, but it can point to the library directory,
which is the default value for this attribute.
<br><dt><b>Library_Symbol_Policy</b>:<dd><a name="index-_0040code_007bLibrary_005fSymbol_005fPolicy_007d-63"></a> This attribute controls the export of symbols and, on some platforms (like
VMS) that have the notions of major and minor IDs built in the library
files, it controls the setting of these IDs. It is not supported on all
platforms (where it will just have no effect). It may have one of the
following values:
<ul>
<li><code>"autonomous"</code> or <code>"default"</code>: exported symbols are not controlled
<li><code>"compliant"</code>: if attribute <b>Library_Reference_Symbol_File</b>
is not defined, then it is equivalent to policy "autonomous". If there
are exported symbols in the reference symbol file that are not in the
object files of the interfaces, the major ID of the library is increased.
If there are symbols in the object files of the interfaces that are not
in the reference symbol file, these symbols are put at the end of the list
in the newly created symbol file and the minor ID is increased.
<li><code>"controlled"</code>: the attribute <b>Library_Reference_Symbol_File</b> must be
defined. The library will fail to build if the exported symbols in the
object files of the interfaces do not match exactly the symbol in the
symbol file.
<li><code>"restricted"</code>: The attribute <b>Library_Symbol_File</b> must be defined.
The library will fail to build if there are symbols in the symbol file that
are not in the exported symbols of the object files of the interfaces.
Additional symbols in the object files are not added to the symbol file.
<li><code>"direct"</code>: The attribute <b>Library_Symbol_File</b> must be defined and
must designate an existing file in the object directory. This symbol file
is passed directly to the underlying linker without any symbol processing.
</ul>
<br><dt><b>Library_Reference_Symbol_File</b><dd><a name="index-_0040code_007bLibrary_005fReference_005fSymbol_005fFile_007d-64"></a> This attribute may define the path name of a reference symbol file that is
read when the symbol policy is either "compliant" or "controlled", on
platforms that support symbol control, such as VMS, when building a
stand-alone library. The path may be an absolute path or a path relative
to the project directory.
<br><dt><b>Library_Symbol_File</b><dd><a name="index-_0040code_007bLibrary_005fSymbol_005fFile_007d-65"></a> This attribute may define the name of the symbol file to be created when
building a stand-alone library when the symbol policy is either "compliant",
"controlled" or "restricted", on platforms that support symbol control,
such as VMS. When symbol policy is "direct", then a file with this name
must exist in the object directory.
</dl>
<!-- -->
<p><a name="Installing-a-library-with-project-files"></a>
<h4 class="subsection">1.5.4 Installing a library with project files</h4>
<!-- -->
<p class="noindent">When using project files, library installation is part of the library build
process. Thus no further action is needed in order to make use of the
libraries that are built as part of the general application build. A usable
version of the library is installed in the directory specified by the
<code>Library_Dir</code> attribute of the library project file.
<p>You may want to install a library in a context different from where the library
is built. This situation arises with third party suppliers, who may want
to distribute a library in binary form where the user is not expected to be
able to recompile the library. The simplest option in this case is to provide
a project file slightly different from the one used to build the library, by
using the <code>externally_built</code> attribute. <a href="#Using-Library-Projects">Using Library Projects</a>
<!-- -->
<p><a name="Project-Extension"></a>
<h3 class="section">1.6 Project Extension</h3>
<!-- -->
<p class="noindent">During development of a large system, it is sometimes necessary to use
modified versions of some of the source files, without changing the original
sources. This can be achieved through the <b>project extension</b> facility.
<p>Suppose for instance that our example <code>Build</code> project is build every night
for the whole team, in some shared directory. A developer usually need to work
on a small part of the system, and might not want to have a copy of all the
sources and all the object files (mostly because that would require too much
disk space, time to recompile everything). He prefers to be able to override
some of the source files in his directory, while taking advantage of all the
object files generated at night.
<p>Another example can be taken from large software systems, where it is common to have
multiple implementations of a common interface; in Ada terms, multiple
versions of a package body for the same spec. For example, one implementation
might be safe for use in tasking programs, while another might only be used
in sequential applications. This can be modeled in GNAT using the concept
of <em>project extension</em>. If one project (the “child”) <em>extends</em>
another project (the “parent”) then by default all source files of the
parent project are inherited by the child, but the child project can
override any of the parent's source files with new versions, and can also
add new files or remove unnecessary ones.
This facility is the project analog of a type extension in
object-oriented programming. Project hierarchies are permitted (an extending
project may itself be extended), and a project that
extends a project can also import other projects.
<p>A third example is that of using project extensions to provide different
versions of the same system. For instance, assume that a <code>Common</code>
project is used by two development branches. One of the branches has now
been frozen, and no further change can be done to it or to <code>Common</code>.
However, the other development branch still needs evolution of <code>Common</code>.
Project extensions provide a flexible solution to create a new version
of a subsystem while sharing and reusing as much as possible from the original
one.
<p>A project extension inherits implicitly all the sources and objects from the
project it extends. It is possible to create a new version of some of the
sources in one of the additional source dirs of the extending project. Those new
versions hide the original versions. Adding new sources or removing existing
ones is also possible. Here is an example on how to extend the project
<code>Build</code> from previous examples:
<pre class="smallexample"> project Work extends "../bld/build.gpr" is
end Work;
</pre>
<p class="noindent">The project after <b>extends</b> is the one being extended. As usual, it can be
specified using an absolute path, or a path relative to any of the directories
in the project path (see <a href="#Project-Dependencies">Project Dependencies</a>). This project does not
specify source or object directories, so the default value for these attribute
will be used that is to say the current directory (where project <code>Work</code> is
placed). We can already compile that project with
<pre class="smallexample"> gnatmake -Pwork
</pre>
<p class="noindent">If no sources have been placed in the current directory, this command
won't do anything, since this project does not change the
sources it inherited from <code>Build</code>, therefore all the object files
in <code>Build</code> and its dependencies are still valid and are reused
automatically.
<p>Suppose we now want to supply an alternate version of <span class="file">pack.adb</span>
but use the existing versions of <span class="file">pack.ads</span> and <span class="file">proc.adb</span>.
We can create the new file Work's current directory (likely
by copying the one from the <code>Build</code> project and making changes to
it. If new packages are needed at the same time, we simply create
new files in the source directory of the extending project.
<p>When we recompile, <span class="command">gnatmake</span> will now automatically recompile
this file (thus creating <span class="file">pack.o</span> in the current directory) and
any file that depends on it (thus creating <span class="file">proc.o</span>). Finally, the
executable is also linked locally.
<p>Note that we could have obtained the desired behavior using project import
rather than project inheritance. A <code>base</code> project would contain the
sources for <span class="file">pack.ads</span> and <span class="file">proc.adb</span>, and <code>Work</code> would
import <code>base</code> and add <span class="file">pack.adb</span>. In this scenario, <code>base</code>
cannot contain the original version of <span class="file">pack.adb</span> otherwise there would be
2 versions of the same unit in the closure of the project and this is not
allowed. Generally speaking, it is not recommended to put the spec and the
body of a unit in different projects since this affects their autonomy and
reusability.
<p>In a project file that extends another project, it is possible to
indicate that an inherited source is <b>not part</b> of the sources of the
extending project. This is necessary sometimes when a package spec has
been overridden and no longer requires a body: in this case, it is
necessary to indicate that the inherited body is not part of the sources
of the project, otherwise there will be a compilation error
when compiling the spec.
<p><a name="index-_0040code_007bExcluded_005fSource_005fFiles_007d-66"></a><a name="index-_0040code_007bExcluded_005fSource_005fList_005fFile_007d-67"></a>For that purpose, the attribute <b>Excluded_Source_Files</b> is used.
Its value is a list of file names.
It is also possible to use attribute <code>Excluded_Source_List_File</code>.
Its value is the path of a text file containing one file name per
line.
<pre class="smallexample"> project Work extends "../bld/build.gpr" is
for Source_Files use ("pack.ads");
-- New spec of Pkg does not need a completion
for Excluded_Source_Files use ("pack.adb");
end Work;
</pre>
<p class="noindent">An extending project retains all the switches specified in the
extended project.
<!-- -->
<p><a name="Project-Hierarchy-Extension"></a>
<h4 class="subsection">1.6.1 Project Hierarchy Extension</h4>
<!-- -->
<p class="noindent">One of the fundamental restrictions in project extension is the following:
<b>A project is not allowed to import directly or indirectly at the same time an
extending project and one of its ancestors</b>.
<p>By means of example, consider the following hierarchy of projects.
<pre class="smallexample"> a.gpr contains package A1
b.gpr, imports a.gpr and contains B1, which depends on A1
c.gpr, imports b.gpr and contains C1, which depends on B1
</pre>
<p class="noindent">If we want to locally extend the packages <code>A1</code> and <code>C1</code>, we need to
create several extending projects:
<pre class="smallexample"> a_ext.gpr which extends a.gpr, and overrides A1
b_ext.gpr which extends b.gpr and imports a_ext.gpr
c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
</pre>
<p class="noindent">
<pre class="smallexample"> project A_Ext extends "a.gpr" is
for Source_Files use ("a1.adb", "a1.ads");
end A_Ext;
with "a_ext.gpr";
project B_Ext extends "b.gpr" is
end B_Ext;
with "b_ext.gpr";
project C_Ext extends "c.gpr" is
for Source_Files use ("c1.adb");
end C_Ext;
</pre>
<p class="noindent">The extension <span class="file">b_ext.gpr</span> is required, even though we are not overriding
any of the sources of <span class="file">b.gpr</span> because otherwise <span class="file">c_expr.gpr</span> would
import <span class="file">b.gpr</span> which itself knows nothing about <span class="file">a_ext.gpr</span>.
<p><a name="index-extends-all-68"></a>When extending a large system spanning multiple projects, it is often
inconvenient to extend every project in the hierarchy that is impacted by a
small change introduced in a low layer. In such cases, it is possible to create
an <b>implicit extension</b> of entire hierarchy using <b>extends all</b>
relationship.
<p>When the project is extended using <code>extends all</code> inheritance, all projects
that are imported by it, both directly and indirectly, are considered virtually
extended. That is, the project manager creates implicit projects
that extend every project in the hierarchy; all these implicit projects do not
control sources on their own and use the object directory of
the "extending all" project.
<p>It is possible to explicitly extend one or more projects in the hierarchy
in order to modify the sources. These extending projects must be imported by
the "extending all" project, which will replace the corresponding virtual
projects with the explicit ones.
<p>When building such a project hierarchy extension, the project manager will
ensure that both modified sources and sources in implicit extending projects
that depend on them, are recompiled.
<p>Thus, in our example we could create the following projects instead:
<pre class="smallexample"> a_ext.gpr, extends a.gpr and overrides A1
c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
</pre>
<p class="noindent">
<pre class="smallexample"> project A_Ext extends "a.gpr" is
for Source_Files use ("a1.adb", "a1.ads");
end A_Ext;
with "a_ext.gpr";
project C_Ext extends all "c.gpr" is
for Source_Files use ("c1.adb");
end C_Ext;
</pre>
<p class="noindent">When building project <span class="file">c_ext.gpr</span>, the entire modified project space is
considered for recompilation, including the sources of <span class="file">b.gpr</span> that are
impacted by the changes in <code>A1</code> and <code>C1</code>.
<!-- -->
<p><a name="Project-File-Reference"></a>
<h3 class="section">1.7 Project File Reference</h3>
<!-- -->
<p class="noindent">This section describes the syntactic structure of project files, the various
constructs that can be used. Finally, it ends with a summary of all available
attributes.
<!-- -->
<p><a name="Project-Declaration"></a>
<h4 class="subsection">1.7.1 Project Declaration</h4>
<!-- -->
<p class="noindent">Project files have an Ada-like syntax. The minimal project file is:
<pre class="smallexample"> project Empty is
end Empty;
</pre>
<p class="noindent">The identifier <code>Empty</code> is the name of the project.
This project name must be present after the reserved
word <code>end</code> at the end of the project file, followed by a semi-colon.
<p><b>Identifiers</b> (ie the user-defined names such as project or variable names)
have the same syntax as Ada identifiers: they must start with a letter,
and be followed by zero or more letters, digits or underscore characters;
it is also illegal to have two underscores next to each other. Identifiers
are always case-insensitive ("Name" is the same as "name").
<pre class="smallexample"> simple_name ::= identifier
name ::= simple_name { . simple_name }
</pre>
<p class="noindent"><b>Strings</b> are used for values of attributes or as indexes for these
attributes. They are in general case sensitive, except when noted
otherwise (in particular, strings representing file names will be case
insensitive on some systems, so that "file.adb" and "File.adb" both
represent the same file).
<p><b>Reserved words</b> are the same as for standard Ada 95, and cannot
be used for identifiers. In particular, the following words are currently
used in project files, but others could be added later on. In bold are the
extra reserved words in project files: <code>all, at, case, end, for, is,
limited, null, others, package, renames, type, use, when, with, </code><b>extends</b><code>,
</code><b>external</b><code>, </code><b>project</b>.
<p><b>Comments</b> in project files have the same syntax as in Ada, two consecutive
hyphens through the end of the line.
<p>A project may be an <b>independent project</b>, entirely defined by a single
project file. Any source file in an independent project depends only
on the predefined library and other source files in the same project.
But a project may also depend on other projects, either by importing them
through <b>with clauses</b>, or by <b>extending</b> at most one other project. Both
types of dependency can be used in the same project.
<p>A path name denotes a project file. It can be absolute or relative.
An absolute path name includes a sequence of directories, in the syntax of
the host operating system, that identifies uniquely the project file in the
file system. A relative path name identifies the project file, relative
to the directory that contains the current project, or relative to a
directory listed in the environment variables ADA_PROJECT_PATH and
GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
operating system are case sensitive. As a special case, the directory
separator can always be "/" even on Windows systems, so that project files
can be made portable across architectures.
The syntax of the environment variable ADA_PROJECT_PATH and
GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
semicolons on Windows.
<p>A given project name can appear only once in a context clause.
<p>It is illegal for a project imported by a context clause to refer, directly
or indirectly, to the project in which this context clause appears (the
dependency graph cannot contain cycles), except when one of the with clause
in the cycle is a <b>limited with</b>.
<!-- ??? Need more details here -->
<pre class="smallexample"> with "other_project.gpr";
project My_Project extends "extended.gpr" is
end My_Project;
</pre>
<p class="noindent">These dependencies form a <b>directed graph</b>, potentially cyclic when using
<b>limited with</b>. The subprogram reflecting the <b>extends</b> relations is a
tree.
<p>A project's <b>immediate sources</b> are the source files directly defined by
that project, either implicitly by residing in the project source directories,
or explicitly through any of the source-related attributes.
More generally, a project sources are the immediate sources of the project
together with the immediate sources (unless overridden) of any
project on which it depends directly or indirectly.
<p>A <b>project hierarchy</b> can be created, where projects are children of
other projects. The name of such a child project must be <code>Parent.Child</code>,
where <code>Parent</code> is the name of the parent project. In particular, this
makes all <code>with</code> clauses of the parent project automatically visible
in the child project.
<pre class="smallexample"> project ::= context_clause project_declaration
context_clause ::= {with_clause}
with_clause ::= <i>with</i> path_name { , path_name } ;
path_name ::= string_literal
project_declaration ::= simple_project_declaration | project_extension
simple_project_declaration ::=
<i>project</i> <i><project_></i>name <i>is</i>
{declarative_item}
<i>end</i> <project_>simple_name;
</pre>
<!-- -->
<p><a name="Qualified-Projects"></a>
<h4 class="subsection">1.7.2 Qualified Projects</h4>
<!-- -->
<p class="noindent">Before the reserved <code>project</code>, there may be one or two <b>qualifiers</b>, that
is identifiers or reserved words, to qualify the project.
The current list of qualifiers is:
<dl>
<dt><b>abstract</b>: qualifies a project with no sources. Such a<dd> project must either have no declaration of attributes <code>Source_Dirs</code>,
<code>Source_Files</code>, <code>Languages</code> or <code>Source_List_File</code>, or one of
<code>Source_Dirs</code>, <code>Source_Files</code>, or <code>Languages</code> must be declared
as empty. If it extends another project, the project it extends must also be a
qualified abstract project.
<br><dt><b>standard</b>: a standard project is a non library project with sources.<dd> This is the default (implicit) qualifier.
<br><dt><b>aggregate</b>: for future extension<br><dt><b>aggregate library</b>: for future extension<br><dt><b>library</b>: a library project must declare both attributes<dd> <code>Library_Name</code> and <code>Library_Dir</code>.
<br><dt><b>configuration</b>: a configuration project cannot be in a project tree.<dd> It describes compilers and other tools to <code>gprbuild</code>.
</dl>
<!-- -->
<p><a name="Declarations"></a>
<h4 class="subsection">1.7.3 Declarations</h4>
<!-- -->
<p class="noindent">Declarations introduce new entities that denote types, variables, attributes,
and packages. Some declarations can only appear immediately within a project
declaration. Others can appear within a project or within a package.
<pre class="smallexample"> declarative_item ::= simple_declarative_item
| typed_string_declaration
| package_declaration
simple_declarative_item ::= variable_declaration
| typed_variable_declaration
| attribute_declaration
| case_construction
| empty_declaration
empty_declaration ::= <i>null</i> ;
</pre>
<p class="noindent">An empty declaration is allowed anywhere a declaration is allowed. It has
no effect.
<!-- -->
<p><a name="Packages"></a>
<h4 class="subsection">1.7.4 Packages</h4>
<!-- -->
<p class="noindent">A project file may contain <b>packages</b>, that group attributes (typically
all the attributes that are used by one of the GNAT tools).
<p>A package with a given name may only appear once in a project file.
The following packages are currently supported in project files
(See see <a href="#Attributes">Attributes</a> for the list of attributes that each can contain).
<dl>
<dt><code>Binder</code><dd> This package specifies characteristics useful when invoking the binder either
directly via the <span class="command">gnat</span> driver or when using a builder such as
<span class="command">gnatmake</span> or <span class="command">gprbuild</span>. See <a href="#Main-Subprograms">Main Subprograms</a>.
<br><dt><code>Builder</code><dd> This package specifies the compilation options used when building an
executable or a library for a project. Most of the options should be
set in one of <code>Compiler</code>, <code>Binder</code> or <code>Linker</code> packages,
but there are some general options that should be defined in this
package. See <a href="#Main-Subprograms">Main Subprograms</a>, and see <a href="#Executable-File-Names">Executable File Names</a> in
particular.
<br><dt><code>Check</code><dd> This package specifies the options used when calling the checking tool
<span class="command">gnatcheck</span> via the <span class="command">gnat</span> driver. Its attribute
<b>Default_Switches</b> has the same semantics as for the package
<code>Builder</code>. The first string should always be <code>-rules</code> to specify
that all the other options belong to the <code>-rules</code> section of the
parameters to <span class="command">gnatcheck</span>.
<br><dt><code>Compiler</code><dd> This package specifies the compilation options used by the compiler for
each languages. See <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a>.
<br><dt><code>Cross_Reference</code><dd> This package specifies the options used when calling the library tool
<span class="command">gnatxref</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Eliminate</code><dd> This package specifies the options used when calling the tool
<span class="command">gnatelim</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Finder</code><dd> This package specifies the options used when calling the search tool
<span class="command">gnatfind</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Gnatls</code><dd> This package the options to use when invoking <span class="command">gnatls</span> via the
<span class="command">gnat</span> driver.
<br><dt><code>Gnatstub</code><dd> This package specifies the options used when calling the tool
<span class="command">gnatstub</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>IDE</code><dd> This package specifies the options used when starting an integrated
development environment, for instance <span class="command">GPS</span> or <span class="command">Gnatbench</span>.
See <a href="#The-Development-Environments">The Development Environments</a>.
<br><dt><code>Linker</code><dd> This package specifies the options used by the linker.
See <a href="#Main-Subprograms">Main Subprograms</a>.
<br><dt><code>Metrics</code><dd> This package specifies the options used when calling the tool
<span class="command">gnatmetric</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Naming</code><dd> This package specifies the naming conventions that apply
to the source files in a project. In particular, these conventions are
used to automatically find all source files in the source directories,
or given a file name to find out its language for proper processing.
See <a href="#Naming-Schemes">Naming Schemes</a>.
<br><dt><code>Pretty_Printer</code><dd> This package specifies the options used when calling the formatting tool
<span class="command">gnatpp</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Stack</code><dd> This package specifies the options used when calling the tool
<span class="command">gnatstack</span> via the <span class="command">gnat</span> driver. Its attributes
<b>Default_Switches</b> and <b>Switches</b> have the same semantics as for the
package <code>Builder</code>.
<br><dt><code>Synchronize</code><dd> This package specifies the options used when calling the tool
<span class="command">gnatsync</span> via the <span class="command">gnat</span> driver.
</dl>
<p>In its simplest form, a package may be empty:
<pre class="smallexample"> project Simple is
package Builder is
end Builder;
end Simple;
</pre>
<p class="noindent">A package may contain <b>attribute declarations</b>,
<b>variable declarations</b> and <b>case constructions</b>, as will be
described below.
<p>When there is ambiguity between a project name and a package name,
the name always designates the project. To avoid possible confusion, it is
always a good idea to avoid naming a project with one of the
names allowed for packages or any name that starts with <code>gnat</code>.
<p>A package can also be defined by a <b>renaming declaration</b>. The new package
renames a package declared in a different project file, and has the same
attributes as the package it renames. The name of the renamed package
must be the same as the name of the renaming package. The project must
contain a package declaration with this name, and the project
must appear in the context clause of the current project, or be its parent
project. It is not possible to add or override attributes to the renaming
project. If you need to do so, you should use an <b>extending declaration</b>
(see below).
<p>Packages that are renamed in other project files often come from project files
that have no sources: they are just used as templates. Any modification in the
template will be reflected automatically in all the project files that rename
a package from the template. This is a very common way to share settings
between projects.
<p>Finally, a package can also be defined by an <b>extending declaration</b>. This is
similar to a <b>renaming declaration</b>, except that it is possible to add or
override attributes.
<pre class="smallexample"> package_declaration ::= package_spec | package_renaming | package_extension
package_spec ::=
<i>package</i> <i><package_></i>simple_name <i>is</i>
{simple_declarative_item}
<i>end</i> package_identifier ;
package_renaming ::==
<i>package</i> <i><package_></i>simple_name <i>renames</i> <i><project_></i>simple_name.package_identifier ;
package_extension ::==
<i>package</i> <i><package_></i>simple_name <i>extends</i> <i><project_></i>simple_name.package_identifier <i>is</i>
{simple_declarative_item}
<i>end</i> package_identifier ;
</pre>
<!-- -->
<p><a name="Expressions"></a>
<h4 class="subsection">1.7.5 Expressions</h4>
<!-- -->
<p class="noindent">An expression is any value that can be assigned to an attribute or a
variable. It is either a litteral value, or a construct requiring runtime
computation by the project manager. In a project file, the computed value of
an expression is either a string or a list of strings.
<p>A string value is one of:
<ul>
<li>A literal string, for instance <code>"comm/my_proj.gpr"</code>
<li>The name of a variable that evaluates to a string (see <a href="#Variables">Variables</a>)
<li>The name of an attribute that evaluates to a string (see <a href="#Attributes">Attributes</a>)
<li>An external reference (see <a href="#External-Values">External Values</a>)
<li>A concatenation of the above, as in <code>"prefix_" & Var</code>.
</ul>
<p class="noindent">A list of strings is one of the following:
<ul>
<li>A parenthesized comma-separated list of zero or more string expressions, for
instance <code>(File_Name, "gnat.adc", File_Name & ".orig")</code> or <code>()</code>.
<li>The name of a variable that evaluates to a list of strings
<li>The name of an attribute that evaluates to a list of strings
<li>A concatenation of a list of strings and a string (as defined above), for
instance <code>("A", "B") & "C"</code>
<li>A concatenation of two lists of strings
</ul>
<p class="noindent">The following is the grammar for expressions
<pre class="smallexample"> string_literal ::= "{string_element}" -- Same as Ada
string_expression ::= string_literal
| <i>variable_</i>name
| external_value
| attribute_reference
| ( string_expression { & string_expression } )
string_list ::= ( string_expression { , string_expression } )
| <i>string_variable</i>_name
| <i>string_</i>attribute_reference
term ::= string_expression | string_list
expression ::= term { & term } -- Concatenation
</pre>
<p class="noindent">Concatenation involves strings and list of strings. As soon as a list of
strings is involved, the result of the concatenation is a list of strings. The
following Ada declarations show the existing operators:
<pre class="smallexample"> function "&" (X : String; Y : String) return String;
function "&" (X : String_List; Y : String) return String_List;
function "&" (X : String_List; Y : String_List) return String_List;
</pre>
<p class="noindent">Here are some specific examples:
<pre class="smallexample"> List := () & File_Name; -- One string in this list
List2 := List & (File_Name & ".orig"); -- Two strings
Big_List := List & Lists2; -- Three strings
Illegal := "gnat.adc" & List2; -- Illegal, must start with list
</pre>
<!-- -->
<p><a name="External-Values"></a>
<h4 class="subsection">1.7.6 External Values</h4>
<!-- -->
<p class="noindent">An external value is an expression whose value is obtained from the command
that invoked the processing of the current project file (typically a
gnatmake or gprbuild command).
<pre class="smallexample"> external_value ::= <i>external</i> ( string_literal [, string_literal] )
</pre>
<p class="noindent">The first string_literal is the string to be used on the command line or
in the environment to specify the external value. The second string_literal,
if present, is the default to use if there is no specification for this
external value either on the command line or in the environment.
<p>Typically, the external value will either exist in the
environment variables
or be specified on the command line through the
<span class="option">-X</span><em>vbl</em><span class="option">=</span><em>value</em> switch. If both
are specified, then the command line value is used, so that a user can more
easily override the value.
<p>The function <code>external</code> always returns a string, possibly empty if the
value was not found in the environment and no default was specified in the
call to <code>external</code>.
<p>An external reference may be part of a string expression or of a string
list expression, and can therefore appear in a variable declaration or
an attribute declaration.
<p>Most of the time, this construct is used to initialize typed variables, which
are then used in <b>case</b> statements to control the value assigned to
attributes in various scenarios. Thus such variables are often called
<b>scenario variables</b>.
<!-- -->
<p><a name="Typed-String-Declaration"></a>
<h4 class="subsection">1.7.7 Typed String Declaration</h4>
<!-- -->
<p class="noindent">A <b>type declaration</b> introduces a discrete set of string literals.
If a string variable is declared to have this type, its value
is restricted to the given set of literals. These are the only named
types in project files. A string type may only be declared at the project
level, not inside a package.
<pre class="smallexample"> typed_string_declaration ::=
<i>type</i> <i><typed_string_></i>_simple_name <i>is</i> ( string_literal {, string_literal} );
</pre>
<p class="noindent">The string literals in the list are case sensitive and must all be different.
They may include any graphic characters allowed in Ada, including spaces.
Here is an example of a string type declaration:
<pre class="smallexample"> type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
</pre>
<p class="noindent">Variables of a string type are called <b>typed variables</b>; all other
variables are called <b>untyped variables</b>. Typed variables are
particularly useful in <code>case</code> constructions, to support conditional
attribute declarations. (see <a href="#Case-Statements">Case Statements</a>).
<p>A string type may be referenced by its name if it has been declared in the same
project file, or by an expanded name whose prefix is the name of the project
in which it is declared.
<!-- -->
<p><a name="Variables"></a>
<h4 class="subsection">1.7.8 Variables</h4>
<!-- -->
<p class="noindent"><b>Variables</b> store values (strings or list of strings) and can appear
as part of an expression. The declaration of a variable creates the
variable and assigns the value of the expression to it. The name of the
variable is available immediately after the assignment symbol, if you
need to reuse its old value to compute the new value. Before the completion
of its first declaration, the value of a variable defaults to the empty
string ("").
<p>A <b>typed</b> variable can be used as part of a <b>case</b> expression to
compute the value, but it can only be declared once in the project file,
so that all case statements see the same value for the variable. This
provides more consistency and makes the project easier to understand.
The syntax for its declaration is identical to the Ada syntax for an
object declaration. In effect, a typed variable acts as a constant.
<p>An <b>untyped</b> variable can be declared and overridden multiple times
within the same project. It is declared implicitly through an Ada
assignment. The first declaration establishes the kind of the variable
(string or list of strings) and successive declarations must respect
the initial kind. Assignments are executed in the order in which they
appear, so the new value replaces the old one and any subsequent reference
to the variable uses the new value.
<p>A variable may be declared at the project file level, or within a package.
<pre class="smallexample"> typed_variable_declaration ::=
<i><typed_variable_></i>simple_name : <i><typed_string_></i>name := string_expression;
variable_declaration ::= <i><variable_></i>simple_name := expression;
</pre>
<p class="noindent">Here are some examples of variable declarations:
<pre class="smallexample"> This_OS : OS := external ("OS"); -- a typed variable declaration
That_OS := "GNU/Linux"; -- an untyped variable declaration
Name := "readme.txt";
Save_Name := Name & ".saved";
Empty_List := ();
List_With_One_Element := ("-gnaty");
List_With_Two_Elements := List_With_One_Element & "-gnatg";
Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
</pre>
<p class="noindent">A <b>variable reference</b> may take several forms:
<ul>
<li>The simple variable name, for a variable in the current package (if any)
or in the current project
<li>An expanded name, whose prefix is a context name.
</ul>
<p class="noindent">A <b>context</b> may be one of the following:
<ul>
<li>The name of an existing package in the current project
<li>The name of an imported project of the current project
<li>The name of an ancestor project (i.e., a project extended by the current
project, either directly or indirectly)
<li>An expanded name whose prefix is an imported/parent project name, and
whose selector is a package name in that project.
</ul>
<!-- -->
<p><a name="Attributes"></a>
<h4 class="subsection">1.7.9 Attributes</h4>
<!-- -->
<p class="noindent">A project (and its packages) may have <b>attributes</b> that define
the project's properties. Some attributes have values that are strings;
others have values that are string lists.
<pre class="smallexample"> attribute_declaration ::=
simple_attribute_declaration | indexed_attribute_declaration
simple_attribute_declaration ::= <i>for</i> attribute_designator <i>use</i> expression ;
indexed_attribute_declaration ::=
<i>for</i> <i><indexed_attribute_></i>simple_name ( string_literal) <i>use</i> expression ;
attribute_designator ::=
<i><simple_attribute_></i>simple_name
| <i><indexed_attribute_></i>simple_name ( string_literal )
</pre>
<p class="noindent">There are two categories of attributes: <b>simple attributes</b>
and <b>indexed attributes</b>.
Each simple attribute has a default value: the empty string (for string
attributes) and the empty list (for string list attributes).
An attribute declaration defines a new value for an attribute, and overrides
the previous value. The syntax of a simple attribute declaration is similar to
that of an attribute definition clause in Ada.
<p>Some attributes are indexed. These attributes are mappings whose
domain is a set of strings. They are declared one association
at a time, by specifying a point in the domain and the corresponding image
of the attribute.
Like untyped variables and simple attributes, indexed attributes
may be declared several times. Each declaration supplies a new value for the
attribute, and replaces the previous setting.
<p>Here are some examples of attribute declarations:
<pre class="smallexample"> -- simple attributes
for Object_Dir use "objects";
for Source_Dirs use ("units", "test/drivers");
-- indexed attributes
for Body ("main") use "Main.ada";
for Switches ("main.ada") use ("-v", "-gnatv");
for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
-- indexed attributes copy (from package Builder in project Default)
-- The package name must always be specified, even if it is the current
-- package.
for Default_Switches use Default.Builder'Default_Switches;
</pre>
<p class="noindent">Attributes references may be appear anywhere in expressions, and are used
to retrieve the value previously assigned to the attribute. If an attribute
has not been set in a given package or project, its value defaults to the
empty string or the empty list.
<pre class="smallexample"> attribute_reference ::= attribute_prefix ' <i><simple_attribute>_</i>simple_name [ (string_literal) ]
attribute_prefix ::= <i>project</i>
| <i><project_></i>simple_name
| package_identifier
| <i><project_></i>simple_name . package_identifier
</pre>
<p class="noindent">Examples are:
<pre class="smallexample"> project'Object_Dir
Naming'Dot_Replacement
Imported_Project'Source_Dirs
Imported_Project.Naming'Casing
Builder'Default_Switches ("Ada")
</pre>
<p class="noindent">The prefix of an attribute may be:
<ul>
<li><code>project</code> for an attribute of the current project
<li>The name of an existing package of the current project
<li>The name of an imported project
<li>The name of a parent project that is extended by the current project
<li>An expanded name whose prefix is imported/parent project name,
and whose selector is a package name
</ul>
<p class="noindent">Legal attribute names are listed below, including the package in
which they must be declared. These names are case-insensitive. The
semantics for the attributes is explained in great details in other sections.
<p>The column <em>index</em> indicates whether the attribute is an indexed attribute,
and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the
system (file). The text is between brackets ([]) if the index is optional.
<p><table summary=""><tr align="left"><th valign="top" width="30%">Attribute Name </th><th valign="top" width="10%">Value </th><th valign="top" width="20%">Package </th><th valign="top" width="40%">Index
<br></th></tr><tr align="left"><th valign="top" width="30%">General attributes </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">see <a href="#Building-With-Projects">Building With Projects</a>
<br></th></tr><tr align="left"><td valign="top" width="30%">Name </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">(Read-only, name of project)
<br></td></tr><tr align="left"><td valign="top" width="30%">Project_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">(Read-only, directory of project)
<br></td></tr><tr align="left"><td valign="top" width="30%">Source_Files </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Source_Dirs </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Source_List_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Locally_Removed_Files </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Excluded_Source_Files </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Object_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Exec_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Excluded_Source_Dirs </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Excluded_Source_Files </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Excluded_Source_List_File </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Inherit_Source_Path </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Languages </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Main </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Main_Language </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Externally_Built </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Roots </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">file
<br></td></tr><tr align="left"><th valign="top" width="30%"> Library-related attributes </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">see <a href="#Library-Projects">Library Projects</a>
<br></th></tr><tr align="left"><td valign="top" width="30%">Library_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Name </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Kind </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Version </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Interface </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Auto_Init </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Options </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Leading_Library_Options </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Src_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_ALI_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_GCC </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Symbol_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Symbol_Policy </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Reference_Symbol_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Interfaces </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><th valign="top" width="30%"> Naming </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">see <a href="#Naming-Schemes">Naming Schemes</a>
<br></th></tr><tr align="left"><td valign="top" width="30%">Spec_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Body_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Separate_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Casing </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Dot_Replacement </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Spec </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (Ada unit)
<br></td></tr><tr align="left"><td valign="top" width="30%">Body </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (Ada unit)
<br></td></tr><tr align="left"><td valign="top" width="30%">Specification_Exceptions </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Implementation_Exceptions </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Naming </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><th valign="top" width="30%"> Building </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">see <a href="#Switches-and-Project-Files">Switches and Project Files</a>
<br></th></tr><tr align="left"><td valign="top" width="30%">Default_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE </td><td valign="top" width="40%">insensitive (language name)
<br></td></tr><tr align="left"><td valign="top" width="30%">Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack </td><td valign="top" width="40%">[file] (file name)
<br></td></tr><tr align="left"><td valign="top" width="30%">Local_Configuration_Pragmas </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Local_Config_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">insensitive </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Global_Configuration_Pragmas </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Builder </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Global_Compilation_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Builder </td><td valign="top" width="40%">language
<br></td></tr><tr align="left"><td valign="top" width="30%">Executable </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Builder </td><td valign="top" width="40%">[file]
<br></td></tr><tr align="left"><td valign="top" width="30%">Executable_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Builder </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Global_Config_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Builder </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><th valign="top" width="30%"> IDE (used and created by GPS) </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">
<br></th></tr><tr align="left"><td valign="top" width="30%">Remote_Host </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Program_Host </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Communication_Protocol </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Compiler_Command </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Debugger_Command </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Gnatlist </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">VCS_Kind </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">VCS_File_Check </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">VCS_Log_Check </td><td valign="top" width="10%">string </td><td valign="top" width="20%">IDE </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><th valign="top" width="30%"> Configuration files </th><th valign="top" width="10%"></th><th valign="top" width="20%"></th><th valign="top" width="40%">See gprbuild manual
<br></th></tr><tr align="left"><td valign="top" width="30%">Default_Language </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Run_Path_Option </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Run_Path_Origin </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Separate_Run_Path_Options </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Toolchain_Version </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Toolchain_Description </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Object_Generated </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Objects_Linked </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Target </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Builder </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Support </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Archive_Builder </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Archive_Builder_Append_Option </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Archive_Indexer </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Archive_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Partial_Linker </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Shared_Library_Prefix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Shared_Library_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Symbolic_Link_Supported </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Major_Minor_Id_Supported </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Auto_Init_Supported </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Shared_Library_Minimum_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Version_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Library_Install_Name_Option </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Runtime_Library_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Runtime_Source_Dir </td><td valign="top" width="10%">string </td><td valign="top" width="20%">- </td><td valign="top" width="40%">insensitive
<br></td></tr><tr align="left"><td valign="top" width="30%">Driver </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler,Binder,Linker </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Required_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler,Binder,Linker </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Leading_Required_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Trailing_Required_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Pic_Options </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Path_Syntax </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Object_File_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Object_File_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Multi_Unit_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Multi_Unit_Object_Separator </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitve (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Mapping_File_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Mapping_Spec_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Mapping_body_Suffix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_File_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Body_File_Name </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Body_File_Name_Index </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Body_File_Name_Pattern </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Spec_File_Name </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Spec_File_Name_Index </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_Spec_File_Name_Pattern </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Config_File_Unique </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Dependency_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Dependency_Driver </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Include_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Include_Path </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Include_Path_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Compiler </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Prefix </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Binder </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Objects_Path </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Binder </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Objects_Path_File </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Binder </td><td valign="top" width="40%">insensitive (language)
<br></td></tr><tr align="left"><td valign="top" width="30%">Linker_Options </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Leading_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Map_File_Options </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Executable_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Lib_Dir_Switch </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Lib_Name_Switch </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Max_Command_Line_Length </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Response_File_Format </td><td valign="top" width="10%">string </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr><tr align="left"><td valign="top" width="30%">Response_File_Switches </td><td valign="top" width="10%">list </td><td valign="top" width="20%">Linker </td><td valign="top" width="40%">-
<br></td></tr></table>
<!-- -->
<p><a name="Case-Statements"></a>
<h4 class="subsection">1.7.10 Case Statements</h4>
<!-- -->
<p class="noindent">A <b>case</b> statement is used in a project file to effect conditional
behavior. Through this statement, you can set the value of attributes
and variables depending on the value previously assigned to a typed
variable.
<p>All choices in a choice list must be distinct. Unlike Ada, the choice
lists of all alternatives do not need to include all values of the type.
An <code>others</code> choice must appear last in the list of alternatives.
<p>The syntax of a <code>case</code> construction is based on the Ada case statement
(although the <code>null</code> statement for empty alternatives is optional).
<p>The case expression must be a typed string variable, whose value is often
given by an external reference (see <a href="#External-Values">External Values</a>).
<p>Each alternative starts with the reserved word <code>when</code>, either a list of
literal strings separated by the <code>"|"</code> character or the reserved word
<code>others</code>, and the <code>"=>"</code> token.
Each literal string must belong to the string type that is the type of the
case variable.
After each <code>=></code>, there are zero or more statements. The only
statements allowed in a case construction are other case statements,
attribute declarations and variable declarations. String type declarations and
package declarations are not allowed. Variable declarations are restricted to
variables that have already been declared before the case construction.
<pre class="smallexample"> case_statement ::=
<i>case</i> <i><typed_variable_></i>name <i>is</i> {case_item} <i>end case</i> ;
case_item ::=
<i>when</i> discrete_choice_list =>
{case_statement
| attribute_declaration
| variable_declaration
| empty_declaration}
discrete_choice_list ::= string_literal {| string_literal} | <i>others</i>
</pre>
<p class="noindent">Here is a typical example:
<pre class="smallexample"> project MyProj is
type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
OS : OS_Type := external ("OS", "GNU/Linux");
package Compiler is
case OS is
when "GNU/Linux" | "Unix" =>
for Switches ("Ada") use ("-gnath");
when "NT" =>
for Switches ("Ada") use ("-gnatP");
when others =>
null;
end case;
end Compiler;
end MyProj;
</pre>
<!-- -->
<p><a name="Tools-Supporting-Project-Files"></a>
<h2 class="chapter">2 Tools Supporting Project Files</h2>
<!-- -->
<p class="noindent">
<!-- -->
<a name="gnatmake-and-Project-Files"></a>
<h3 class="section">2.1 gnatmake and Project Files</h3>
<!-- -->
<p class="noindent">This section covers several topics related to <span class="command">gnatmake</span> and
project files: defining switches for <span class="command">gnatmake</span>
and for the tools that it invokes; specifying configuration pragmas;
the use of the <code>Main</code> attribute; building and rebuilding library project
files.
<!-- -->
<p><a name="Switches-Related-to-Project-Files"></a>
<h4 class="subsection">2.1.1 Switches Related to Project Files</h4>
<!-- -->
<p class="noindent">The following switches are used by GNAT tools that support project files:
<dl>
<dt><span class="option">-P</span><var>project</var><dd><a name="index-_0040option_007b_002dP_007d-_0028any-project_002daware-tool_0029-69"></a>Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by <span class="option">-vP</span><em>x</em>,
if any, and using the external references indicated
by <span class="option">-X</span> switches, if any.
There may zero, one or more spaces between <span class="option">-P</span> and <var>project</var>.
<p>There must be only one <span class="option">-P</span> switch on the command line.
<p>Since the Project Manager parses the project file only after all the switches
on the command line are checked, the order of the switches
<span class="option">-P</span>,
<span class="option">-vP</span><em>x</em>
or <span class="option">-X</span> is not significant.
<br><dt><span class="option">-X</span><var>name=value</var><dd><a name="index-_0040option_007b_002dX_007d-_0028any-project_002daware-tool_0029-70"></a>Indicates that external variable <var>name</var> has the value <var>value</var>.
The Project Manager will use this value for occurrences of
<code>external(name)</code> when parsing the project file.
<p>If <var>name</var> or <var>value</var> includes a space, then <var>name=value</var> should be
put between quotes.
<pre class="smallexample"> -XOS=NT
-X"user=John Doe"
</pre>
<p>Several <span class="option">-X</span> switches can be used simultaneously.
If several <span class="option">-X</span> switches specify the same
<var>name</var>, only the last one is used.
<p>An external variable specified with a <span class="option">-X</span> switch
takes precedence over the value of the same name in the environment.
<br><dt><span class="option">-vP</span><em>x</em><dd><a name="index-_0040option_007b_002dvP_007d-_0028any-project_002daware-tool_0029-71"></a>Indicates the verbosity of the parsing of GNAT project files.
<p><span class="option">-vP0</span> means Default;
<span class="option">-vP1</span> means Medium;
<span class="option">-vP2</span> means High.
<p>The default is Default: no output for syntactically correct
project files.
If several <span class="option">-vP</span><em>x</em> switches are present,
only the last one is used.
<br><dt><span class="option">-aP<dir></span><dd><a name="index-_0040option_007b_002daP_007d-_0028any-project_002daware-tool_0029-72"></a>Add directory <dir> at the beginning of the project search path, in order,
after the current working directory.
<br><dt><span class="option">-eL</span><dd><a name="index-_0040option_007b_002deL_007d-_0028any-project_002daware-tool_0029-73"></a>Follow all symbolic links when processing project files.
<br><dt><span class="option">--subdirs=<subdir></span><dd><a name="index-_0040option_007b_002d_002dsubdirs_003d_007d-_0028gnatmake-and-gnatclean_0029-74"></a>This switch is recognized by gnatmake and gnatclean. It indicate that the real
directories (except the source directories) are the subdirectories <subdir>
of the directories specified in the project files. This applies in particular
to object directories, library directories and exec directories. If the
subdirectories do not exist, they are created automatically.
</dl>
<!-- -->
<p><a name="Switches-and-Project-Files"></a>
<h4 class="subsection">2.1.2 Switches and Project Files</h4>
<!-- -->
<p class="noindent">For each of the packages <code>Builder</code>, <code>Compiler</code>, <code>Binder</code>, and
<code>Linker</code>, you can specify a <code>Default_Switches</code>
attribute, a <code>Switches</code> attribute, or both;
as their names imply, these switch-related
attributes affect the switches that are used for each of these GNAT
components when
<span class="command">gnatmake</span> is invoked. As will be explained below, these
component-specific switches precede
the switches provided on the <span class="command">gnatmake</span> command line.
<p>The <code>Default_Switches</code> attribute is an attribute
indexed by language name (case insensitive) whose value is a string list.
For example:
<pre class="smallexample"> package Compiler is
for Default_Switches ("Ada")
use ("-gnaty",
"-v");
end Compiler;
</pre>
<p class="noindent">The <code>Switches</code> attribute is indexed on a file name (which may or may
not be case sensitive, depending
on the operating system) whose value is a string list. For example:
<pre class="smallexample"> package Builder is
for Switches ("main1.adb")
use ("-O2");
for Switches ("main2.adb")
use ("-g");
end Builder;
</pre>
<p class="noindent">For the <code>Builder</code> package, the file names must designate source files
for main subprograms. For the <code>Binder</code> and <code>Linker</code> packages, the
file names must designate <span class="file">ALI</span> or source files for main subprograms.
In each case just the file name without an explicit extension is acceptable.
<p>For each tool used in a program build (<span class="command">gnatmake</span>, the compiler, the
binder, and the linker), the corresponding package <dfn>contributes</dfn> a set of
switches for each file on which the tool is invoked, based on the
switch-related attributes defined in the package.
In particular, the switches
that each of these packages contributes for a given file <var>f</var> comprise:
<ul>
<li>the value of attribute <code>Switches (</code><var>f</var><code>)</code>,
if it is specified in the package for the given file,
<li>otherwise, the value of <code>Default_Switches ("Ada")</code>,
if it is specified in the package.
</ul>
<p class="noindent">If neither of these attributes is defined in the package, then the package does
not contribute any switches for the given file.
<p>When <span class="command">gnatmake</span> is invoked on a file, the switches comprise
two sets, in the following order: those contributed for the file
by the <code>Builder</code> package;
and the switches passed on the command line.
<p>When <span class="command">gnatmake</span> invokes a tool (compiler, binder, linker) on a file,
the switches passed to the tool comprise three sets,
in the following order:
<ol type=1 start=1>
<li>the applicable switches contributed for the file
by the <code>Builder</code> package in the project file supplied on the command line;
<li>those contributed for the file by the package (in the relevant project file –
see below) corresponding to the tool; and
<li>the applicable switches passed on the command line.
</ol>
<p>The term <em>applicable switches</em> reflects the fact that
<span class="command">gnatmake</span> switches may or may not be passed to individual
tools, depending on the individual switch.
<p><span class="command">gnatmake</span> may invoke the compiler on source files from different
projects. The Project Manager will use the appropriate project file to
determine the <code>Compiler</code> package for each source file being compiled.
Likewise for the <code>Binder</code> and <code>Linker</code> packages.
<p>As an example, consider the following package in a project file:
<pre class="smallexample"> project Proj1 is
package Compiler is
for Default_Switches ("Ada")
use ("-g");
for Switches ("a.adb")
use ("-O1");
for Switches ("b.adb")
use ("-O2",
"-gnaty");
end Compiler;
end Proj1;
</pre>
<p class="noindent">If <span class="command">gnatmake</span> is invoked with this project file, and it needs to
compile, say, the files <span class="file">a.adb</span>, <span class="file">b.adb</span>, and <span class="file">c.adb</span>, then
<span class="file">a.adb</span> will be compiled with the switch
<span class="option">-O1</span>,
<span class="file">b.adb</span> with switches
<span class="option">-O2</span>
and <span class="option">-gnaty</span>,
and <span class="file">c.adb</span> with <span class="option">-g</span>.
<p>The following example illustrates the ordering of the switches
contributed by different packages:
<pre class="smallexample"> project Proj2 is
package Builder is
for Switches ("main.adb")
use ("-g",
"-O1",
"-f");
end Builder;
package Compiler is
for Switches ("main.adb")
use ("-O2");
end Compiler;
end Proj2;
</pre>
<p class="noindent">If you issue the command:
<pre class="smallexample"> gnatmake -Pproj2 -O0 main
</pre>
<p class="noindent">then the compiler will be invoked on <span class="file">main.adb</span> with the following
sequence of switches
<pre class="smallexample"> -g -O1 -O2 -O0
</pre>
<p class="noindent">with the last <span class="option">-O</span>
switch having precedence over the earlier ones;
several other switches
(such as <span class="option">-c</span>) are added implicitly.
<p>The switches
<span class="option">-g</span>
and <span class="option">-O1</span> are contributed by package
<code>Builder</code>, <span class="option">-O2</span> is contributed
by the package <code>Compiler</code>
and <span class="option">-O0</span> comes from the command line.
<p>The <span class="option">-g</span>
switch will also be passed in the invocation of
<span class="command">Gnatlink.</span>
<p>A final example illustrates switch contributions from packages in different
project files:
<pre class="smallexample"> project Proj3 is
for Source_Files use ("pack.ads", "pack.adb");
package Compiler is
for Default_Switches ("Ada")
use ("-gnata");
end Compiler;
end Proj3;
with "Proj3";
project Proj4 is
for Source_Files use ("foo_main.adb", "bar_main.adb");
package Builder is
for Switches ("foo_main.adb")
use ("-s",
"-g");
end Builder;
end Proj4;
-- Ada source file:
with Pack;
procedure Foo_Main is
...
end Foo_Main;
</pre>
<p class="noindent">If the command is
<pre class="smallexample"> gnatmake -PProj4 foo_main.adb -cargs -gnato
</pre>
<p class="noindent">then the switches passed to the compiler for <span class="file">foo_main.adb</span> are
<span class="option">-g</span> (contributed by the package <code>Proj4.Builder</code>) and
<span class="option">-gnato</span> (passed on the command line).
When the imported package <code>Pack</code> is compiled, the switches used
are <span class="option">-g</span> from <code>Proj4.Builder</code>,
<span class="option">-gnata</span> (contributed from package <code>Proj3.Compiler</code>,
and <span class="option">-gnato</span> from the command line.
<p>When using <span class="command">gnatmake</span> with project files, some switches or
arguments may be expressed as relative paths. As the working directory where
compilation occurs may change, these relative paths are converted to absolute
paths. For the switches found in a project file, the relative paths
are relative to the project file directory, for the switches on the command
line, they are relative to the directory where <span class="command">gnatmake</span> is invoked.
The switches for which this occurs are:
-I,
-A,
-L,
-aO,
-aL,
-aI, as well as all arguments that are not switches (arguments to
switch
-o, object files specified in package <code>Linker</code> or after
-largs on the command line). The exception to this rule is the switch
–RTS= for which a relative path argument is never converted.
<!-- -->
<p><a name="Specifying-Configuration-Pragmas"></a>
<h4 class="subsection">2.1.3 Specifying Configuration Pragmas</h4>
<!-- -->
<p class="noindent">When using <span class="command">gnatmake</span> with project files, if there exists a file
<span class="file">gnat.adc</span> that contains configuration pragmas, this file will be
ignored.
<p>Configuration pragmas can be defined by means of the following attributes in
project files: <code>Global_Configuration_Pragmas</code> in package <code>Builder</code>
and <code>Local_Configuration_Pragmas</code> in package <code>Compiler</code>.
<p>Both these attributes are single string attributes. Their values is the path
name of a file containing configuration pragmas. If a path name is relative,
then it is relative to the project directory of the project file where the
attribute is defined.
<p>When compiling a source, the configuration pragmas used are, in order,
those listed in the file designated by attribute
<code>Global_Configuration_Pragmas</code> in package <code>Builder</code> of the main
project file, if it is specified, and those listed in the file designated by
attribute <code>Local_Configuration_Pragmas</code> in package <code>Compiler</code> of
the project file of the source, if it exists.
<!-- -->
<p><a name="Project-Files-and-Main-Subprograms"></a>
<h4 class="subsection">2.1.4 Project Files and Main Subprograms</h4>
<!-- -->
<p class="noindent">When using a project file, you can invoke <span class="command">gnatmake</span>
with one or several main subprograms, by specifying their source files on the
command line.
<pre class="smallexample"> gnatmake -Pprj main1 main2 main3
</pre>
<p class="noindent">Each of these needs to be a source file of the same project, except
when the switch -u is used.
<p>When -u is not used, all the mains need to be sources of the
same project, one of the project in the tree rooted at the project specified
on the command line. The package <code>Builder</code> of this common project, the
"main project" is the one that is considered by <span class="command">gnatmake</span>.
<p>When -u is used, the specified source files may be in projects
imported directly or indirectly by the project specified on the command line.
Note that if such a source file is not part of the project specified on the
command line, the switches found in package <code>Builder</code> of the
project specified on the command line, if any, that are transmitted
to the compiler will still be used, not those found in the project file of
the source file.
<p>When using a project file, you can also invoke <span class="command">gnatmake</span> without
explicitly specifying any main, and the effect depends on whether you have
defined the <code>Main</code> attribute. This attribute has a string list value,
where each element in the list is the name of a source file (the file
extension is optional) that contains a unit that can be a main subprogram.
<p>If the <code>Main</code> attribute is defined in a project file as a non-empty
string list and the switch <span class="option">-u</span> is not used on the command
line, then invoking <span class="command">gnatmake</span> with this project file but without any
main on the command line is equivalent to invoking <span class="command">gnatmake</span> with all
the file names in the <code>Main</code> attribute on the command line.
<p>Example:
<pre class="smallexample"> project Prj is
for Main use ("main1", "main2", "main3");
end Prj;
</pre>
<p class="noindent">With this project file, <code>"gnatmake -Pprj"</code>
is equivalent to
<code>"gnatmake -Pprj main1 main2 main3"</code>.
<p>When the project attribute <code>Main</code> is not specified, or is specified
as an empty string list, or when the switch <span class="option">-u</span> is used on the command
line, then invoking <span class="command">gnatmake</span> with no main on the command line will
result in all immediate sources of the project file being checked, and
potentially recompiled. Depending on the presence of the switch <span class="option">-u</span>,
sources from other project files on which the immediate sources of the main
project file depend are also checked and potentially recompiled. In other
words, the <span class="option">-u</span> switch is applied to all of the immediate sources of the
main project file.
<p>When no main is specified on the command line and attribute <code>Main</code> exists
and includes several mains, or when several mains are specified on the
command line, the default switches in package <code>Builder</code> will
be used for all mains, even if there are specific switches
specified for one or several mains.
<p>But the switches from package <code>Binder</code> or <code>Linker</code> will be
the specific switches for each main, if they are specified.
<!-- -->
<p><a name="Library-Project-Files"></a>
<h4 class="subsection">2.1.5 Library Project Files</h4>
<!-- -->
<p class="noindent">When <span class="command">gnatmake</span> is invoked with a main project file that is a library
project file, it is not allowed to specify one or more mains on the command
line.
<p>When a library project file is specified, switches -b and
-l have special meanings.
<ul>
<li>-b is only allowed for stand-alone libraries. It indicates
to <span class="command">gnatmake</span> that <span class="command">gnatbind</span> should be invoked for the
library.
<li>-l may be used for all library projects. It indicates
to <span class="command">gnatmake</span> that the binder generated file should be compiled
(in the case of a stand-alone library) and that the library should be built.
</ul>
<!-- -->
<p><a name="The-GNAT-Driver-and-Project-Files"></a>
<h3 class="section">2.2 The GNAT Driver and Project Files</h3>
<!-- -->
<p class="noindent">A number of GNAT tools, other than <span class="command">gnatmake</span>
can benefit from project files:
(<span class="command">gnatbind</span>,
<span class="command">gnatcheck</span>,
<span class="command">gnatclean</span>,
<span class="command">gnatelim</span>,
<span class="command">gnatfind</span>,
<span class="command">gnatlink</span>,
<span class="command">gnatls</span>,
<span class="command">gnatmetric</span>,
<span class="command">gnatpp</span>,
<span class="command">gnatstub</span>,
and <span class="command">gnatxref</span>). However, none of these tools can be invoked
directly with a project file switch (<span class="option">-P</span>).
They must be invoked through the <span class="command">gnat</span> driver.
<p>The <span class="command">gnat</span> driver is a wrapper that accepts a number of commands and
calls the corresponding tool. It was designed initially for VMS platforms (to
convert VMS qualifiers to Unix-style switches), but it is now available on all
GNAT platforms.
<p>On non-VMS platforms, the <span class="command">gnat</span> driver accepts the following commands
(case insensitive):
<ul>
<li>BIND to invoke <span class="command">gnatbind</span>
<li>CHOP to invoke <span class="command">gnatchop</span>
<li>CLEAN to invoke <span class="command">gnatclean</span>
<li>COMP or COMPILE to invoke the compiler
<li>ELIM to invoke <span class="command">gnatelim</span>
<li>FIND to invoke <span class="command">gnatfind</span>
<li>KR or KRUNCH to invoke <span class="command">gnatkr</span>
<li>LINK to invoke <span class="command">gnatlink</span>
<li>LS or LIST to invoke <span class="command">gnatls</span>
<li>MAKE to invoke <span class="command">gnatmake</span>
<li>NAME to invoke <span class="command">gnatname</span>
<li>PREP or PREPROCESS to invoke <span class="command">gnatprep</span>
<li>PP or PRETTY to invoke <span class="command">gnatpp</span>
<li>METRIC to invoke <span class="command">gnatmetric</span>
<li>STUB to invoke <span class="command">gnatstub</span>
<li>XREF to invoke <span class="command">gnatxref</span>
</ul>
<p class="noindent">(note that the compiler is invoked using the command
<span class="command">gnatmake -f -u -c</span>).
<p>On non-VMS platforms, between <span class="command">gnat</span> and the command, two
special switches may be used:
<ul>
<li><span class="command">-v</span> to display the invocation of the tool.
<li><span class="command">-dn</span> to prevent the <span class="command">gnat</span> driver from removing
the temporary files it has created. These temporary files are
configuration files and temporary file list files.
</ul>
<p class="noindent">The command may be followed by switches and arguments for the invoked
tool.
<pre class="smallexample"> gnat bind -C main.ali
gnat ls -a main
gnat chop foo.txt
</pre>
<p class="noindent">Switches may also be put in text files, one switch per line, and the text
files may be specified with their path name preceded by '@'.
<pre class="smallexample"> gnat bind @args.txt main.ali
</pre>
<p class="noindent">In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
METRIC, PP or PRETTY, STUB and XREF, the project file related switches
(<span class="option">-P</span>,
<span class="option">-X</span> and
<span class="option">-vPx</span>) may be used in addition to
the switches of the invoking tool.
<p>When GNAT PP or GNAT PRETTY is used with a project file, but with no source
specified on the command line, it invokes <span class="command">gnatpp</span> with all
the immediate sources of the specified project file.
<p>When GNAT METRIC is used with a project file, but with no source
specified on the command line, it invokes <span class="command">gnatmetric</span>
with all the immediate sources of the specified project file and with
<span class="option">-d</span> with the parameter pointing to the object directory
of the project.
<p>In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
a project file, no source is specified on the command line and
switch -U is specified on the command line, then
the underlying tool (gnatpp or
gnatmetric) is invoked for all sources of all projects,
not only for the immediate sources of the main project.
(-U stands for Universal or Union of the project files of the project tree)
<p>For each of the following commands, there is optionally a corresponding
package in the main project.
<ul>
<li>package <code>Binder</code> for command BIND (invoking <code>gnatbind</code>)
<li>package <code>Check</code> for command CHECK (invoking
<code>gnatcheck</code>)
<li>package <code>Compiler</code> for command COMP or COMPILE (invoking the compiler)
<li>package <code>Cross_Reference</code> for command XREF (invoking
<code>gnatxref</code>)
<li>package <code>Eliminate</code> for command ELIM (invoking
<code>gnatelim</code>)
<li>package <code>Finder</code> for command FIND (invoking <code>gnatfind</code>)
<li>package <code>Gnatls</code> for command LS or LIST (invoking <code>gnatls</code>)
<li>package <code>Gnatstub</code> for command STUB
(invoking <code>gnatstub</code>)
<li>package <code>Linker</code> for command LINK (invoking <code>gnatlink</code>)
<li>package <code>Check</code> for command CHECK
(invoking <code>gnatcheck</code>)
<li>package <code>Metrics</code> for command METRIC
(invoking <code>gnatmetric</code>)
<li>package <code>Pretty_Printer</code> for command PP or PRETTY
(invoking <code>gnatpp</code>)
</ul>
<p class="noindent">Package <code>Gnatls</code> has a unique attribute <code>Switches</code>,
a simple variable with a string list value. It contains switches
for the invocation of <code>gnatls</code>.
<pre class="smallexample"> project Proj1 is
package gnatls is
for Switches
use ("-a",
"-v");
end gnatls;
end Proj1;
</pre>
<p class="noindent">All other packages have two attribute <code>Switches</code> and
<code>Default_Switches</code>.
<p><code>Switches</code> is an indexed attribute, indexed by the
source file name, that has a string list value: the switches to be
used when the tool corresponding to the package is invoked for the specific
source file.
<p><code>Default_Switches</code> is an attribute,
indexed by the programming language that has a string list value.
<code>Default_Switches ("Ada")</code> contains the
switches for the invocation of the tool corresponding
to the package, except if a specific <code>Switches</code> attribute
is specified for the source file.
<pre class="smallexample"> project Proj is
for Source_Dirs use ("./**");
package gnatls is
for Switches use
("-a",
"-v");
end gnatls;
package Compiler is
for Default_Switches ("Ada")
use ("-gnatv",
"-gnatwa");
end Binder;
package Binder is
for Default_Switches ("Ada")
use ("-C",
"-e");
end Binder;
package Linker is
for Default_Switches ("Ada")
use ("-C");
for Switches ("main.adb")
use ("-C",
"-v",
"-v");
end Linker;
package Finder is
for Default_Switches ("Ada")
use ("-a",
"-f");
end Finder;
package Cross_Reference is
for Default_Switches ("Ada")
use ("-a",
"-f",
"-d",
"-u");
end Cross_Reference;
end Proj;
</pre>
<p class="noindent">With the above project file, commands such as
<pre class="smallexample"> gnat comp -Pproj main
gnat ls -Pproj main
gnat xref -Pproj main
gnat bind -Pproj main.ali
gnat link -Pproj main.ali
</pre>
<p class="noindent">will set up the environment properly and invoke the tool with the switches
found in the package corresponding to the tool:
<code>Default_Switches ("Ada")</code> for all tools,
except <code>Switches ("main.adb")</code>
for <code>gnatlink</code>.
It is also possible to invoke some of the tools,
(<code>gnatcheck</code>,
<code>gnatmetric</code>,
and <code>gnatpp</code>)
on a set of project units thanks to the combination of the switches
<span class="option">-P</span>, <span class="option">-U</span> and possibly the main unit when one is interested
in its closure. For instance,
<pre class="smallexample"> gnat metric -Pproj
</pre>
<p class="noindent">will compute the metrics for all the immediate units of project
<code>proj</code>.
<pre class="smallexample"> gnat metric -Pproj -U
</pre>
<p class="noindent">will compute the metrics for all the units of the closure of projects
rooted at <code>proj</code>.
<pre class="smallexample"> gnat metric -Pproj -U main_unit
</pre>
<p class="noindent">will compute the metrics for the closure of units rooted at
<code>main_unit</code>. This last possibility relies implicitly
on <span class="command">gnatbind</span>'s option <span class="option">-R</span>. But if the argument files for the
tool invoked by the the <span class="command">gnat</span> driver are explicitly specified
either directly or through the tool <span class="option">-files</span> option, then the tool
is called only for these explicitly specified files.
<!-- -->
<p><a name="The-Development-Environments"></a>
<h3 class="section">2.3 The Development Environments</h3>
<!-- -->
<p class="noindent">See the appropriate manuals for more details. These environments will
store a number of settings in the project itself, when they are meant
to be shared by the whole team working on the project. Here are the
attributes defined in the package <b>IDE</b> in projects.
<dl>
<dt><code>Remote_Host</code><dd>This is a simple attribute. Its value is a string that designates the remote
host in a cross-compilation environment, to be used for remote compilation and
debugging. This field should not be specified when running on the local
machine.
<br><dt><code>Program_Host</code><dd>This is a simple attribute. Its value is a string that specifies the
name of IP address of the embedded target in a cross-compilation environment,
on which the program should execute.
<br><dt><code>Communication_Protocol</code><dd>This is a simple string attribute. Its value is the name of the protocol
to use to communicate with the target in a cross-compilation environment,
e.g. <code>"wtx"</code> or <code>"vxworks"</code>.
<br><dt><code>Compiler_Command</code><dd>This is an associative array attribute, whose domain is a language name. Its
value is string that denotes the command to be used to invoke the compiler.
The value of <code>Compiler_Command ("Ada")</code> is expected to be compatible with
gnatmake, in particular in the handling of switches.
<br><dt><code>Debugger_Command</code><dd>This is simple attribute, Its value is a string that specifies the name of
the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
<br><dt><code>Default_Switches</code><dd>This is an associative array attribute. Its indexes are the name of the
external tools that the GNAT Programming System (GPS) is supporting. Its
value is a list of switches to use when invoking that tool.
<br><dt><code>Gnatlist</code><dd>This is a simple attribute. Its value is a string that specifies the name
of the <span class="command">gnatls</span> utility to be used to retrieve information about the
predefined path; e.g., <code>"gnatls"</code>, <code>"powerpc-wrs-vxworks-gnatls"</code>.
<br><dt><code>VCS_Kind</code><dd>This is a simple attribute. Its value is a string used to specify the
Version Control System (VCS) to be used for this project, e.g. CVS, RCS
ClearCase or Perforce.
<br><dt><code>VCS_File_Check</code><dd>This is a simple attribute. Its value is a string that specifies the
command used by the VCS to check the validity of a file, either
when the user explicitly asks for a check, or as a sanity check before
doing the check-in.
<br><dt><code>VCS_Log_Check</code><dd>This is a simple attribute. Its value is a string that specifies
the command used by the VCS to check the validity of a log file.
<br><dt><code>VCS_Repository_Root</code><dd>The VCS repository root path. This is used to create tags or branches
of the repository. For subversion the value should be the <code>URL</code>
as specified to check-out the working copy of the repository.
<br><dt><code>VCS_Patch_Root</code><dd>The local root directory to use for building patch file. All patch chunks
will be relative to this path. The root project directory is used if
this value is not defined.
</dl>
<!-- -->
<p><a name="Cleaning-up-with-GPRclean"></a>
<h3 class="section">2.4 Cleaning up with GPRclean</h3>
<!-- -->
<p class="noindent">The GPRclean tool removes the files created by GPRbuild.
At a minimum, to invoke GPRclean you must specify a main project file
in a command such as <code>gprclean proj.gpr</code> or <code>gprclean -P proj.gpr</code>.
<p>Examples of invocation of GPRclean:
<pre class="smallexample"> gprclean -r prj1.gpr
gprclean -c -P prj2.gpr
</pre>
<!-- -->
<p><a name="Switches-for-GPRclean"></a>
<h4 class="subsection">2.4.1 Switches for GPRclean</h4>
<!-- -->
<p class="noindent">The switches for GPRclean are:
<ul>
<li><span class="option">--config=<main config project file name></span> : Specify the
configuration project file name
<li><span class="option">--autoconf=<config project file name></span>
<p>This specifies a configuration project file name that already exists or will
be created automatically. Option <span class="option">--autoconf=</span>
cannot be specified more than once. If the configuration project file
specified with <span class="option">--autoconf=</span> exists, then it is used. Otherwise,
GPRconfig is invoked to create it automatically.
<li><span class="option">-c</span> : Only delete compiler-generated files. Do not delete
executables and libraries.
<li><span class="option">-f</span> : Force deletions of unwritable files
<li><span class="option">-F</span> : Display full project path name in brief error messages
<li><span class="option">-h</span> : Display this message
<li><span class="option">-n</span> : Do not delete files, only list files to delete
<li><span class="option">-P<proj></span> : Use Project File <em><proj></em>.
<li><span class="option">-q</span> : Be quiet/terse. There is no output, except to report
problems.
<li><span class="option">-r</span> : (recursive) Clean all projects referenced by the main
project directly or indirectly. Without this switch, GPRclean only
cleans the main project.
<li><span class="option">-v</span> : Verbose mode
<li><span class="option">-vPx</span> : Specify verbosity when parsing Project Files.
x = 0 (default), 1 or 2.
<li><span class="option">-Xnm=val</span> : Specify an external reference for Project Files.
</ul>
<!-- -->
<p><a name="Gprbuild"></a>
<h2 class="chapter">3 Gprbuild</h2>
<!-- -->
<p class="noindent"><code>GPRbuild</code> is a generic build tool designed for the construction of
large multi-language systems organized into subsystems and libraries.
It is well-suited for compiled languages supporting separate compilation,
such as Ada, C, C++ and Fortran.
<p><code>GPRbuild</code> manages a three step build process.
<ul>
<li>compilation phase:
<p>Each compilation unit of each subsystem is examined in turn, checked for
consistency, and compiled or recompiled when necessary by the appropriate
compiler. The recompilation decision is based on dependency information
that is typically produced by a previous compilation.
<li>post-compilation phase (or binding):
<p>Compiled units from a given language are passed to a language-specific
post-compilation tool if any. Also during this phase
objects are grouped into static or dynamic libraries as specified.
<li>linking phase:
<p>All units or libraries from all subsystems are passed to a linker tool
specific to the set of toolchains being used.
</ul>
<p class="noindent">The tool is generic in that it provides, when possible, equivalent
build capabilities for all supported languages. For this, it uses a
configuration file <span class="file"><file>.cgpr</span> that has a syntax and structure very
similar to a project file, but which defines the characteristics
of the supported languages and toolchains. The configuration file contains
information such as:
<ul>
<li>the default source naming conventions for each language,
<li>the compiler name, location and required options,
<li>how to compute inter-unit dependencies,
<li>how to build static or dynamic libraries,
<li>which post-compilation actions are needed,
<li>how to link together units from different languages.
</ul>
<p class="noindent">On the other hand, <code>GPRbuild</code> is not a replacement for general-purpose
build tools such as <code>make</code> or <code>ant</code> which give the user a high
level of control over the build process itself. When building a system
requires complex actions that do not fit well in the three-phase process
described above, <code>GPRbuild</code> might not be sufficient.
In such situations, <code>GPRbuild</code> can still
be used to manage the appropriate part of the build. For
instance it can be called from within a Makefile.
<!-- -->
<p><a name="Building-with-GPRbuild"></a>
<h3 class="section">3.1 Building with GPRbuild</h3>
<!-- -->
<p class="noindent">
<!-- -->
<a name="Command-Line"></a>
<h4 class="subsection">3.1.1 Command Line</h4>
<!-- -->
<p class="noindent">Three elements can optionally be specified on GPRbuild's command line:
<ul>
<li>the main project file,
<li>the switches for GPRbuild itself or for the tools it
drives, and
<li>the main source files.
</ul>
<p class="noindent">The general syntax is thus:
<pre class="smallexample"> gprbuild [<proj>.gpr] [switches] [names]
{[-cargs opts] [-cargs:lang opts] [-largs opts] [-gargs opts]}
</pre>
<p class="noindent">GPRbuild requires a project file, which may be specified on the
command line either directly or through the <span class="option">-P</span> switch. If not
specified, GPRbuild uses the project file <span class="file">default.gpr</span> if there
is one in the current working directory. Otherwise, if there is only
one project file in the current working directory, GPRbuild uses this
project file.
<p>Main source files represent the sources to be used as the main
programs. If they are not specified on the command line, GPRbuild uses
the source files specified with the <code>Main</code> attribute in the project
file. If none exists, then no executable will be built.
<p>When source files are specified along with the option <span class="option">-c</span>, then
recompilation will be considered only for those source files. In all
other cases, GPRbuild compiles or recompiles all sources in the
project tree that are not up to date, and builds or rebuilds libraries
that are not up to date.
<p>If invoked without the <span class="option">--config=</span> or
<span class="option">--autoconf=</span> options, then GPRbuild will look for a configuration
project file <span class="file">default.cgpr</span>, or <span class="file"><targetname>.cgpr</span> if option
<span class="option">--target=<targetname></span> is used. If there is no such file in the default
locations expected by GPRbuild (<install>/share/gpr and the current
directory) then GPRbuild will invoke GPRconfig with
the languages from the project files, and create a configuration project
file <span class="file">auto.cgpr</span> in the object directory of the main project. The project
<span class="file">auto.cgpr</span> will be rebuilt at each GPRbuild invocation unless you use
the switch <span class="option">--autoconf=path/auto.cgpr</span>, which will use the configuration
project file if it exists and create it otherwise.
<p>Options given on the GPRbuild command line may be passed along to
individual tools by preceding them with one of the “command line
separators” shown below. Options following the separator, up to the
next separator (or end of the command line), are passed along. The
different command line separators are:
<ul>
<li><span class="option">-cargs</span>
<p>The arguments that follow up to the next command line separator are
options for all compilers for all languages.
Example: <span class="option">-cargs -g</span>
<li><span class="option">-cargs:<language name></span>
<p>The arguments that follow up to the next command line separator are
options for the compiler of the specific language.
<p>Examples:
<ul>
<li><span class="option">-cargs:Ada -gnatf</span>
<li><span class="option">-cargs:C -E</span>
</ul>
<li><span class="option">-bargs</span>
<p>The arguments that follow up to the next command line separator are
options for all binder drivers.
<li><span class="option">-bargs:<language name></span>
<p>The arguments that follow up to the next command line separators are
options for the binder driver of the specific language.
<p>Examples:
<ul>
<li><span class="option">-bargs:Ada binder_prefix=ppc-elf</span>
<li><span class="option">-bargs:C++ c_compiler_name=ccppc</span>
</ul>
<li><span class="option">-largs</span>
<p>The arguments that follow up to the next command line separator are
options for the linker.
<li><span class="option">-gargs</span>
<p>The arguments that follow up to the next command line separator are
options for GPRbuild itself. Usually <span class="option">-gargs</span> is specified after one or
several other command line separators.
<li><span class="option">-margs</span>
<p>Equivalent to <span class="option">-gargs</span>, provided for compatibility with
<span class="command">gnatmake</span>.
</ul>
<!-- -->
<p><a name="Switches"></a>
<h4 class="subsection">3.1.2 Switches</h4>
<!-- -->
<p>GPRbuild takes into account switches that may be specified on the command
line or in attributes Switches(<main or language>) or Default_Switches
(<language) in package Builder of the main project.
<p>When there are a single main (specified on the command line or in
attribute Main in the main project), the switches that are taken into account
in package Builder of the main project are Switches (<main>), if declared, or
Switches (<language of main>), if declared.
<p>When there are several mains, if there are sources of the same language, then
Switches (<language of main>) is taken into account, if specified.
<p>When there are no main specified, if there is only one compiled language
(that is a language with a non empty Compiler Driver), then
Switches (<single language>) is taken into account, if specified.
<p class="noindent">The switches that are interpreted directly by GPRbuild are listed below.
<p>First, the switches that may be specified only on the command line, but not in
package Builder of the main project:
<ul>
<li><span class="option">--version</span>
<p>Display information about GPRbuild: version, origin and legal status, then
exit successfully, ignoring other options.
<li><span class="option">--help</span>
<p>Display GPRbuild usage, then exit successfully, ignoring other options.
<li><span class="option">--display-paths</span>
<p>Display two lines: the configuration project file search path and the user
project file search path, then exit successfully, ignoring other options.
<li><span class="option">--config=<config project file name></span>
<p>This specifies the configuration project file name. By default, the
configuration project file name is <span class="file">default.cgpr</span>. Option <span class="option">--config=</span>
cannot be specified more than once. The configuration project file specified
with <span class="option">--config=</span> must exist.
<li><span class="option">--autoconf=<config project file name></span>
<p>This specifies a configuration project file name that already exists
or will be created automatically. Option <span class="option">--autoconf=</span> cannot
be specified more than once. If the configuration project file
specified with <span class="option">--autoconf=</span> exists, then it is
used. Otherwise, GPRconfig is invoked to create it automatically.
<li><span class="option">--target=<targetname></span>
<p>This specifies that the default configuration project file is
<span class="file"><targetname>.cgpr</span>. If no configuration project file with this name
is found, then GPRconfig is invoked with option
<span class="option">--target=<targetname></span>to create a configuration project file
<span class="file">auto.cgpr</span>.
<p>Note: only one of <span class="option">--config</span>, <span class="option">--autoconf</span> or <span class="option">--target=</span>
can be specified.
<li><span class="option">--no-object-check</span>
<p>Do not check if an object has been created after compilation.
<li><span class="option">--subdirs=<subdir></span>
<p>This indicates that the real directories (except the source directories) are
subdirectories of the directories specified in the project files. This applies
in particular to object directories, library directories and exec directories.
If the directories do not exist, they are created automatically.
<li><span class="option">--unchecked-shared-lib-imports</span>
<p>Allow shared library projects to import projects that are not shared
library projects.
<li><span class="option">-aP dir</span> (Add directory <span class="file">dir</span> to project search path)
<p>Specify to GPRbuild to add directory <span class="file">dir</span> to the user project file search
path, before the default directory.
<li><span class="option">-b</span> (Bind only)
<p>Specify to GPRbuild that the post-compilation (or binding) phase is to be
performed, but not the other phases unless they are specified by appropriate
switches.
<li><span class="option">-c</span> (Compile only)
<p>Specify to GPRbuild that the compilation phase is to be performed, but not
the other phases unless they are specified by appropriate switches.
<li><span class="option">-d</span> (Display progress)
<p>Display progress for each source, up to date or not, as a single
line <em>completed x out of y (zz%)...</em>. If the file needs to be compiled
this is displayed after the invocation of the compiler. These lines are
displayed even in quiet output mode (switch <span class="option">-q</span>).
<li><span class="option">-Inn</span> (Index of main unit in multi-unit source file)
Indicate the index of the main unit in a multi-unit source file.
The index must be a positive number and there should be one and only
one main source file name on the command line.
<li><span class="option">-eL</span> (Follow symbolic links when processing project files)
<p>By default, symbolic links on project files are not taken into account
when processing project files. Switch <span class="option">-eL</span> changes this default
behavior.
<li><span class="option">-eS</span> (no effect)
<p>This switch is only accepted for compatibility with gnatmake, but it has
no effect. For gnatmake, it means: echo commands to standard output instead
of standard error, but for gprbuild, commands are always echoed to standard
output.
<li><span class="option">-F</span> (Full project path name in brief error messages)
<p>By default, in non verbose mode, when an error occurs while processing
a project file, only the simple name of the project file is displayed in the
error message. When switch <span class="option">-F</span> is used, the full path of the project
file is used. This switch has no effect when switch <span class="option">-v</span> is used.
<li><span class="option">-l</span> (Link only)
<p>Specify to GPRbuild that the linking phase is to be performed, but not
the other phases unless they are specified by appropriate switches.
<li><span class="option">-m</span> (Minimum Ada recompilation)
<p>Do not recompile Ada code if timestamps are different but checksums are the
same.
<li><span class="option">-o name</span> (Choose an alternate executable name)
<p>Specify the file name of the executable. Switch <span class="option">-o</span> can
be used only if there is exactly one executable being built;
that is, there is exactly one main on the command line,
or there are no mains on the command line and exactly one
main in attribute <code>Main</code> of the main project.
<li><span class="option">-P proj</span> (use Project file <em>proj</em>)
<p>Specify the path name of the main project file. The space between <span class="option">-P</span>
and the project file name is optional. Specifying a project file name (with
suffix <span class="file">.gpr</span>) may be used in place of option <span class="option">-P</span>. Exactly one main
project file can be specified.
<li><span class="option">-r</span> (Recursive)
<p>This switch has an effect only when <span class="option">-c</span> or <span class="option">-u</span> is also
specified and there are no mains: it means that all sources of all projects
need to be compiled or recompiled.
<li><span class="option">-u</span> (Unique compilation, only compile the given files)
<p>If there are sources specified on the command line, only compile these
sources. If there are no sources specified on the command line, compile
all the sources of the main project.
<p>In both cases, do not attempt the binding and the linking phases.
<li><span class="option">-U</span> (Compile all sources of all projects)
<p>If there are sources specified on the command line, only compile these
sources. If there are no sources specified on the command line, compile
all the sources of all the projects in the project tree.
<p>In both cases, do not attempt the binding and the linking phases.
<li><span class="option">-vPx</span> (Specify verbosity when parsing Project Files)
<p>By default, GPRbuild does not display anything when processing project files,
except when there are errors. This default behavior is obtained with switch
<span class="option">-vP0</span>. Switches <span class="option">-vP1</span> and <span class="option">-vP2</span> yield increasingly
detailed output.
<li><span class="option">-Xnm=val</span> (Specify an external reference for Project Files)
<p>Specify an external reference that may be queried inside the project files
using built-in function <code>external</code>. For example, with
<span class="option">-XBUILD=DEBUG</span>,
<code>external("BUILD")</code> inside a project file will have the value
<code>"DEBUG"</code>.
</ul>
<p class="noindent">Then, the switches that may be specified on the command line as well as in
package Builder of the main project (attribute Switches):
<ul>
<li><span class="option">--create-map-file</span>
<p>When linking an executable, if supported by the platform, create a map file
with the same name as the executable, but with suffix <span class="file">.map</span>.
<li><span class="option">--create-map-file=<map file></span>
<p>When linking an executable, if supported by the platform, create a map file
with file name <span class="file"><map file></span>.
<li><span class="option">--no-indirect-imports</span>
<p>This indicates that sources of a project should import only sources or
header files from directly imported projects, that is those projects mentioned
in a with clause and the projects they extend directly or indirectly.
A check is done in the compilation phase, after a successful compilation, that
the sources follow these restrictions. For Ada sources, the check is fully
enforced. For non Ada sources, the check is partial, as in the dependency
file there is no distinction between header files directly included and those
indirectly included. The check will fail if there is no possibility that a
header file in a non directly imported project could have been indirectly
imported. If the check fails, the compilation artifacts (dependency file,
object file, switches file) are deleted.
<li><span class="option">--indirect-imports</span>
<p>This indicates that sources of a project can import sources or header files
from directly or indirectly imported projects. This is the default behavior.
This switch is provided to cancel a previous switch
<span class="option">--no-indirect-imports</span> on the command line.
<li><span class="option">--no-split-units</span>
<p>Forbid the sources of the same Ada unit to be in different projects.
<li><span class="option">--single-compile-per-obj-dir</span>
<p>Disallow several simultaneous compilations for the same object directory.
<li><span class="option">-f</span> (Force recompilations)
<p>Force the complete processing of all phases (or of those explicitly specified)
even when up to date.
<li><span class="option">-j<num></span> (use <em>num</em> simultaneous compilation jobs)
<p>By default, GPRbuild invokes one compiler at a time. With switch <span class="option">-j</span>,
it is possible to instruct GPRbuild to spawn several simultaneous compilation
jobs if needed. For example, <span class="option">-j2</span> for two simultaneous compilation
jobs or <span class="option">-j4</span> for four. On a multi-processor system,
<span class="option">-j<num></span> can greatly speed up the build process.
<li><span class="option">-k</span> (Keep going after compilation errors)
<p>By default, GPRbuild stops spawning new compilation jobs at the first
compilation failure. Using switch <span class="option">-k</span>, it is possible to attempt to
compile/recompile all the sources that are not up to date, even when some
compilations failed. The post-compilation phase and the linking phase are never
attempted if there are compilation failures, even when switch <span class="option">-k</span> is
used.
<li><span class="option">-p</span> or <span class="option">--create-missing-dirs</span> (Create missing object, library and exec directories)
<p>By default, GPRbuild checks that the object, library and exec directories
specified in project files exist. Switch <span class="option">-p</span> instructs GPRbuild to
attempt to create missing directories. Note that these switches may be
specified in package Builder of the main project, but they are useless there
as either the directories already exist or the processing of the project
files has failed before the evaluation of the Builder switches, because there
is at least one missing directory.
<li><span class="option">-q</span> (Quiet output)
<p>Do not display anything except errors and progress (switch <span class="option">-d</span>).
Cancel any previous switch <span class="option">-v</span>.
<li><span class="option">-s</span> (recompile if compilation switches have changed)
<p>By default, GPRbuild will not recompile a source if all dependencies are
satisfied. Switch <span class="option">-s</span> instructs GPRbuild to recompile sources when a
different set of compilation switches has been used in the previous
compilation, even if all dependencies are satisfied. Each time GPRbuild
invokes a compiler, it writes a text file that lists the switches used in the
invocation of the compiler, so that it can retrieve these switches if
<span class="option">-s</span> is used later.
<li><span class="option">-v</span> (Verbose output)
<p>Display full paths, all options used in spawned processes, and reasons why
these processes are spawned. Cancel any previous switch <span class="option">-q</span>.
<li><span class="option">-we</span> (Treat all warnings as errors)
<p>When <span class="option">-we</span> is used, any warning during the processing of the project
files becomes an error and GPRbuild does not attempt any of the phases.
<li><span class="option">-wn</span> (Treat warnings as warnings)
<p>Switch <span class="option">-wn</span> may be used to restore the default after <span class="option">-we</span> or
<span class="option">-ws</span>.
<li><span class="option">-ws</span> (Suppress all warnings)
<p>Do not generate any warnings while processing the project files.
</ul>
<p class="noindent">Switches that are accepted for compatibility with gnatmake, either on the
command line or in the Builder Ada switches in the main project file:
<ul>
<li><span class="option">-nostdinc</span>
<li><span class="option">-nostdlib</span>
<li><span class="option">-fstack-check</span>
<li><span class="option">-fno-inline</span>
<li><span class="option">-g*</span> Any switch starting with <span class="option">-g</span>
<li><span class="option">-O*</span> Any switch starting with <span class="option">-O</span>
</ul>
<p class="noindent">These switches are passed to the Ada compiler.
<!-- -->
<p><a name="Initialization"></a>
<h4 class="subsection">3.1.3 Initialization</h4>
<!-- -->
<p class="noindent">Before performing one or several of its three phases, GPRbuild has to read the
command line, obtain its configuration, and process the project files.
<p>If GPRbuild is invoked with an invalid switch or without any project file on
the command line, it will fail immediately.
<p>Examples:
<pre class="smallexample"> $ gprbuild -P
gprbuild: project file name missing after -P
$ gprbuild -P c_main.gpr -WW
gprbuild: illegal option "-WW"
</pre>
<p class="noindent">GPRbuild looks for the configuration project file first in the current
working directory, then in the default configuration project directory.
If the GPRbuild executable is located in a subdirectory <span class="file"><prefix>/bin</span>,
then
the default configuration project directory is <span class="file"><prefix>/share/gpr</span>,
otherwise there is no default configuration project directory.
<p>When it has found its configuration project path, GPRbuild needs to obtain its
configuration. By default, the file name of the main configuration project
is <span class="file">default.cgpr</span>. This default may be modified using the switch
<span class="option">--config=...</span>
<p>Example:
<pre class="smallexample"> $ gprbuild --config=my_standard.cgpr -P my_project.gpr
</pre>
<p class="noindent">If GPRbuild cannot find the main configuration project on the configuration
project path, then it will look for all the languages specified in the user
project tree and invoke GPRconfig to create a configuration project file
named <span class="file">auto.cgpr</span> that is located in the object directory of the main
project file.
<p>Once it has found the configuration project, GPRbuild will process its
configuration: if a single string attribute is specified in the configuration
project and is not specified in a user project, then the attribute is added
to the user project. If a string list attribute is specified in the
configuration project then its value is prepended to the corresponding
attribute in the user project.
<p>After GPRbuild has processed its configuration, it will
process the user project file or files. If these user project files are
incorrect then GPRbuild will fail with the appropriate error messages:
<pre class="smallexample"> $ gprbuild -P my_project.gpr
ada_main.gpr:3:26: "src" is not a valid directory
gprbuild: "my_project.gpr" processing failed
</pre>
<p class="noindent">Once the user project files have been dealt with successfully, GPRbuild
will start its processing.
<!-- -->
<p><a name="Compilation-of-one-or-several-sources"></a>
<h4 class="subsection">3.1.4 Compilation of one or several sources</h4>
<!-- -->
<p class="noindent">If GPRbuild is invoked with <span class="option">-u</span> or <span class="option">-U</span> and there are one or
several source file names specified on the command line, GPRbuild will compile
or recompile these sources, if they are not up to date or if <span class="option">-f</span> is
also specified. Then GPRbuild will stop its execution.
<p>The options/switches used to compile these sources are described in section
<a href="#Compilation-Phase">Compilation Phase</a>.
<p>If GPRbuild is invoked with <span class="option">-u</span> and no source file name is specified
on the command line, GPRbuild will compile or recompile all the sources of the
<em>main</em> project and then stop.
<p>In contrast, if GPRbuild is invoked with <span class="option">-U</span>, and again no source file name is specified
on the command line, GPRbuild will compile or recompile all the sources of <em>all
the projects in the project tree</em> and then stop.
<!-- -->
<p><a name="Compilation-Phase"></a>
<h4 class="subsection">3.1.5 Compilation Phase</h4>
<!-- -->
<p class="noindent">When switch <span class="option">-c</span> is used or when switches <span class="option">-b</span> or <span class="option">-l</span>
are not used, GPRbuild will first compile or recompile the sources that
are not up to date in all the projects in the project tree. The sources
considered are:
<ul>
<li>all the sources in languages other than Ada
<li>if there are no main specified, all the Ada sources
<li>if there is a non Ada main, but no attribute <code>Roots</code> specified for
this main, all the Ada sources
<li>if there is a main with an attribute <code>Roots</code> specified, all
the Ada sources in the closures of these Roots.
<li>if there is an Ada main specified, all the Ada sources in the closure
of the main
</ul>
<p class="noindent">Attribute Roots takes as an index a main and a string list value. Each string
in the list is the name of an Ada library unit.
<p>Example:
<pre class="smallexample"> for Roots ("main.c") use ("pkga", "pkgb");
</pre>
<p class="noindent">Package PkgA and PkgB will be considered, and all the Ada units in their
closure will also be considered.
<p>GPRbuild will first consider each source and decide if it needs to be
(re)compiled.
<p>A source needs to be compiled in the following cases:
<ul>
<li>Switch <span class="option">-f</span> (force recompilations) is used
<li>The object file does not exist
<li>The source is more recent than the object file
<li>The dependency file does not exist
<li>The source is more recent than the dependency file
<li>When <span class="option">-s</span> is used: the switch file does not exist
<li>When <span class="option">-s</span> is used: the source is more recent than the switch file
<li>The dependency file cannot be read
<li>The dependency file is empty
<li>The dependency file has a wrong format
<li>A source listed in the dependency file does not exist
<li>A source listed in the dependency file has an incompatible time stamp
<li>A source listed in the dependency file has been replaced
<li>Switch <span class="option">-s</span> is used and the source has been compiled with
different switches or with the same switches in a different order
</ul>
<p class="noindent">When a source is successfully compiled, the following files are normally
created in the object directory of the project of the source:
<ul>
<li>An object file
<li>A dependency file, except when the dependency kind for the language
is <code>none</code>
<li>A switch file if switch <span class="option">-s</span> is used
</ul>
<p class="noindent">The compiler for the language corresponding to the source file name is invoked with the following
switches/options:
<ul>
<li>The required compilation switches for the language
<li>The compilation switches coming from package <code>Compiler</code> of the
project of the source
<li>The compilation switches specified on the command line for all compilers,
after <span class="option">-cargs</span>
<li>The compilation switches for the language of the source, specified
after <span class="option">-cargs:<language></span>
<li>Various other options including a switch to create the dependency file
while compiling, a switch to specify a configuration file, a switch
to specify a mapping file, and switches to indicate where to look for
other source or header files that are needed to compile the source.
</ul>
<p class="noindent">If compilation is needed, then all the options/switches, except those
described as “Various other options” are written to the switch file.
The switch file is a text file. Its file name is obtained by replacing
the suffix of the source with <span class="file">.cswi</span>. For example, the switch file
for source <span class="file">main.adb</span> is <span class="file">main.cswi</span> and for
<span class="file">toto.c</span> it is <span class="file">toto.cswi</span>.
<p>If the compilation is successful, then if the creation of the dependency
file is not done during compilation but after (see configuration attribute
<code>Compute_Dependency</code>), then the process to create the dependency file is
invoked.
<p>If GPRbuild is invoked with a switch <span class="option">-j</span> specifying more than one
compilation process, then several compilation processes for several sources of
possibly different languages are spawned concurrently.
<p>For each project file, attribute Interfaces may be declared. Its value is a
list of sources or header files of the project file. For a project file
extending another one, directly or indirectly, inherited sources may be in
the list. When Interfaces is not declared, all sources or header files are
part of the interface of the project. When Interfaces is declared, only those
sources or header files are part of the interface of the project file. After
a successful compilation, gprbuild checks that all imported or included sources
or header files that are from an imported project are part of the interface of
the imported project. If this check fails, the compilation is invalidated and
the compilation artifacts (dependency, object and switches files) are deleted.
<p>Example:
<pre class="smallexample"> project Prj is
for Languages use ("Ada", "C");
for Interfaces use ("pkg.ads", "toto.h");
end Prj;
</pre>
<p class="noindent">If a source from a project importing project Prj imports sources from Prj other
than package Pkg or includes header files from Prj other than "toto.h", then
its compilation will be invalidated.
<!-- -->
<p><a name="Post_002dCompilation-Phase"></a>
<h4 class="subsection">3.1.6 Post-Compilation Phase</h4>
<!-- -->
<p class="noindent">The post-compilation phase has two parts: library building and program binding.
<p>If there are libraries that need to be built or rebuilt, <em>gprbuild</em> will
call the library builder, specified by attribute <code>Library_Builder</code>.
This is generally the tool <em>gprlib</em>, provided with GPRbuild. If gprbuild
can determine that a library is already up to date, then the library builder
will not be called.
<p>If there are mains specified, and for these mains there are sources of
languages with a binder driver (specified by attribute Binder'Driver
(<language>), then the binder driver is called for each such main, but only
if it needs to.
<p>For Ada, the binder driver is normally <em>gprbind</em>, which will call
the appropriate version of <em>gnatbind</em>, that either the one in the same
directory as the Ada compiler or the fist one found on the path.
When neither of those is appropriate, it is possible to specify to
<em>gprbind</em> the full path of <em>gnatbind</em>, using the Binder switch
<code>--gnatbind_path=</code>.
<p>Example:
<pre class="smallexample"> package Binder is
for Switches ("Ada") use ("--gnatbind_path=/toto/gnatbind");
end Binder;
</pre>
<p class="noindent">If gprbuild can determine that the artifacts from a previous
post-compilation phase are already up to date, the binder driver is not called.
<p>If there are no libraries and no binder drivers, then the post-compilation
phase is empty.
<!-- -->
<p><a name="Linking-Phase"></a>
<h4 class="subsection">3.1.7 Linking Phase</h4>
<!-- -->
<p class="noindent">When there are mains specified, either in attribute Main or on the command
line, and these mains are not up to date, the linker is invoked for each main,
with all the specified or implied options, including the object files generated
during the post-compilation phase by the binder drivers.
<!-- -->
<p><a name="Incompatibilities-with-gnatmake"></a>
<h4 class="subsection">3.1.8 Incompatibilities with gnatmake</h4>
<!-- -->
<p class="noindent">Here is a list of incompatibilities between gnatmake invoked with a
project file and gprbuild:
<ul>
<li>gprbuild never recompiles the runtime sources.
<li>gnatmake switches that are not recognized by gprbuild:
<ul>
<li>-a (Consider all files, even readonly ali files)
<li>-M (List object file dependences for Makefile)
<li>-n (Check objects up to date, output next file to compile if not)
<li>-R (Do not use a run_path_option when linking)
<li>-x (Allow compilation of needed units external to the projects)
<li>-z No main subprogram (zero main)
<li>–GCC=command
<li>–GNATBIND=command
<li>–GNATLINK=command
<li>-aLdir (Skip missing library sources if ali in dir)
<li>-Adir (like -aLdir -aIdir)
<li>-aOdir (Specify library/object files search path)
<li>-aIdir (Specify source files search path)
<li>-Idir (Like -aIdir -aOdir)
<li>-I- (Don't look for sources & library files in the default directory)
<li>-Ldir (Look for program libraries also in dir)
</ul>
<li>The switches that are not directly recognized by gprbuild and passed to
the Ada compiler are only:
<ul>
<li>-nostdlib
<li>-nostdinc
<li>-fstack-check
<li>-fno-inline
<li>-Oxxx (any switch starting with -O)
<li>-gxxx (any switch starting with -g)
</ul>
</ul>
<!-- -->
<p><a name="Configuring-with-GPRconfig"></a>
<h3 class="section">3.2 Configuring with GPRconfig</h3>
<!-- -->
<p class="noindent">
<!-- -->
<a name="Configuration"></a>
<h4 class="subsection">3.2.1 Configuration</h4>
<!-- -->
<p class="noindent">GPRbuild requires one configuration file describing the languages and
toolchains to be used, and project files describing the
characteristics of the user project. Typically the configuration
file can be created automatically by <code>GPRbuild</code> based on the languages
defined in your projects and the compilers on your path. In more
involved situations — such as cross compilation, or
environments with several compilers for the same language —
you may need to control more precisely the generation of
the desired configuration of toolsets. A tool, GPRconfig, described in
<a href="#Configuring-with-GPRconfig">Configuring with GPRconfig</a>), offers this capability. In this
chapter most of the examples can use autoconfiguration.
<p>GPRbuild will start its build process by trying to locate a configuration
file. The following tests are performed in the specified order, and the
first that matches provides the configuration file to use.
<ul>
<li>If a file has a base names that matches <code><target>-<rts>.cgpr</code>,
<code><target.cgpr</code>, <code><rts>.cgpr</code> or <code>default.cgpr</code> is found in
the default configuration files directory, this file is used. The target
and rts parameters are specified via the <code>--target</code> and <code>--RTS</code>
switches of <code>gprbuild</code>. The default directory is is <span class="file">share/gpr</span>
in the installation directory of <code>gprbuild</code>
<li>If not found, the environment variable <code>GPR_CONFIG</code> is tested
to check whether it contains the name of a valid configuration file. This
can either be an absolute path name or a base name that will be searched
in the same default directory as above.
<li>If still not found and you used the <code>--autoconf</code> switch, then
a new configuration file is automatically generated based on the specified
target and on the list of languages specified in your projects.
<p>GPRbuild assumes that there are known compilers on your path for each of
the necessary languages. It is preferable and often necessary to manually
generate your own configuration file when:
<ul>
<li>using cross compilers (in which case you need to use gprconfig's
<span class="option">--target=</span>) option,
<li>using a specific Ada runtime (e.g. <span class="option">--RTS=sjlj</span>),
<li>working with compilers not in the path or not first in the path, or
<li>autoconfiguration does not give the expected results.
</ul>
</ul>
<p class="noindent">GPRconfig provides several ways of generating configuration files. By
default, a simple interactive mode lists all the known compilers for all
known languages. You can then select a compiler for each of the languages;
once a compiler has been selected, only compatible compilers for other
languages are proposed. Here are a few examples of GPRconfig
invocation:
<ul>
<li>The following command triggers interactive mode. The configuration will be
generated in GPRbuild's default location,
<code><gprbuild_install_root>/share/gpr/default.cgpr)</code>
<pre class="smallexample"> gprconfig
</pre>
<li>The first command below also triggers interactive mode, but the resulting
configuration
file has the name and path selected by the user. The second command shows
how GPRbuild can make use of this specific configuration file instead of
the default one.
<pre class="smallexample"> gprconfig -o path/my_config.cgpr
gprbuild --config=path/my_config.cgpr
</pre>
<li>The following command again triggers interactive mode, and only the
relevant cross compilers for target ppc-elf will be proposed.
<pre class="smallexample"> gprconfig --target=ppc-elf
</pre>
<li>The next command triggers batch mode and generates at the default location
a configuration file using the first native Ada and C compilers on
the path.
<pre class="smallexample"> gprconfig --config=Ada --config=C --batch
</pre>
<li>The next command, a combination of the previous examples, creates in
batch mode a configuration file named <span class="file">x.cgpr</span> for cross-compiling
Ada with a run-time called <code>hi</code> and using C for the LEON
processor.
<pre class="smallexample"> gprconfig --target=leon-elf --config=Ada,,hi --config=C --batch -o x.cgpr
</pre>
</ul>
<!-- -->
<p><a name="Using-GPRconfig"></a>
<h4 class="subsection">3.2.2 Using GPRconfig</h4>
<!-- -->
<p class="noindent">
<h4 class="subsection">3.2.3 Description</h4>
<p class="noindent">The GPRconfig tool helps you generate the configuration
files for GPRbuild. It automatically detects the available compilers
on your system and, after you have selected the one needed for your
application, it generates the proper configuration file.
<p><div class="note">In general, you will not launch GPRconfig
explicitly. Instead, it is used implicitly by GPRbuild through the use
of <code>--config</code> and <code>--autoconf</code> switches.
</div>
<h4 class="subsection">3.2.4 Command line arguments</h4>
<p class="noindent">GPRconfig supports the following command line switches:
<dl>
<dt><span class="option">--target=platform</span><dd> <a name="index-_0040option_007b_002d_002dtarget_007d-for-gprconfig-75"></a>
<div class="tip">Use <span class="option">--target</span> to specify on which machine your application will
run
</div>
<p>This switch indicates the target computer on which your application will
be run. It is mostly useful for cross configurations. Examples include
<span class="samp">ppc-elf</span>, <span class="samp">ppc-vx6-windows</span>. It can also be used in native
configurations and is useful when the same machine can run different kind
of compilers such as mingw32 and cygwin on Windows or x86-32 and x86-64
on GNU Linux. Since different compilers will often return a different
name for those targets, GPRconfig has an extensive knowledge of which
targets are compatible, and will for example accept <span class="samp">x86-linux</span> as
an alias for <span class="samp">i686-pc-linux-gnu</span>.
The default target is the machine on which GPRconfig is run.
<p>If you enter the special target <span class="samp">all</span>, then all compilers found on the
<span class="env">PATH</span> will be displayed.
<br><dt><span class="option">--show-targets</span><dd> <a name="index-_0040option_007b_002d_002dshow_002dtarget_007d-for-gprconfig-76"></a>
As mentioned above, GPRconfig knows which targets are compatible. You
can use this switch to find the list of targets that are compatible
with <code>--target</code>.
<br><dt><span class="option">--config=language[,version[,runtime[,path[,name]]]]</span><dd> <a name="index-_0040option_007b_002d_002dconfig_007d-for-gprconfig-77"></a>
<div class="tip">Use <span class="option">--config</span> to automatically select the first matching
compiler
</div>
<p>The intent of this switch is to preselect one or more compilers directly
from the command line. This switch takes several optional arguments, which
you can omit simply by passing the empty string. When omitted, the arguments
will be computed automatically by GPRconfig.
<p>In general, only <span class="option">language</span> needs to be specified, and the first
compiler on the <span class="env">PATH</span> that can compile this language will be selected.
As an example, for a multi-language application programmed in C and Ada,
the command line would be:
<pre class="smallexample"> --config=Ada --config=C
</pre>
<p class="noindent"><span class="option">path</span> is the directory that contains the compiler executable, for
instance <span class="file">/usr/bin</span> (and not the installation prefix <span class="file">/usr</span>).
<p><span class="option">name</span> should be one of the compiler names defined in the GPRconfig
knowledge base. The list of supported names includes <span class="samp">GNAT</span>,
<span class="samp">GCC</span>,<small class="dots">...</small>. This name is
generally not needed, but can be used to distinguish among several compilers
that could match the other arguments of <span class="option">--config</span>.
<p>Another possible more frequent use of <span class="option">name</span> is to specify the base
name of an executable. For instance, if you prefer to use a diab C compiler
(executable is called <span class="file">dcc</span>) instead of <span class="file">gcc</span>, even if the latter
appears first in the path, you could specify <span class="file">dcc</span> as the name parameter.
<pre class="smallexample"> gprconfig --config Ada,,,/usr/bin # automatic parameters
gprconfig --config C,,,/usr/bin,GCC # automatic version
gprconfig --config C,,,/usr/bin,gcc # same as above, with exec name
</pre>
<p class="noindent">This switch is also the only possibility to include in your project some
languages that are not associated with a compiler. This is sometimes useful
especially when you are using environments like GPS that support project files.
For instance, if you select "Project file" as a language, the files matching
the <span class="file">.gpr</span> extension will be shown in the editor, although they of course
play no role for gprbuild itself.
<br><dt><span class="option">--batch</span><dd> <a name="index-_0040option_007b_002d_002dbatch_007d-for-gprconfig-78"></a>
<div class="tip">Use <span class="option">--batch</span> to generate the configuration file with no user
interaction
</div>
<p>If this switch is specified, GPRconfig automatically selects the first
compiler matching each of the <code>--config</code> switches, and generates the
configuration file immediately. It will not display an interactive menu.
<br><dt><span class="option">-o file</span><dd> <a name="index-_0040option_007b_002do_007d-for-gprconfig-79"></a>
<div class="tip">Use <span class="option">-o</span> to specify the name of the configuration file to generate
</div>
<p>This specifies the name of the configuration file that will be generated.
If this switch is not specified, a default file is generated in the
installation directory of GPRbuild (assuming you have write access to
that directory), so that it is automatically picked up by GPRbuild later
on. If you select a different output file, you will need to specify it
to GPRbuild.
<br><dt><span class="option">--db directory</span><dt><span class="option">--db-</span><dd> <a name="index-_0040option_007b_002d_002ddb_007d-for-gprconfig-80"></a>
Indicates another directory that should be parsed for GPRconfig's knowledge
base. Most of the time this is only useful if you are creating your own
XML description files locally. The second version of the switch prevents
GPRconfig from reading its default knowledge base.
<br><dt><span class="option">-h</span><dd> <a name="index-_0040option_007b_002dh_007d-for-gprconfig-81"></a>
Generates a brief help message listing all GPRconfig switches and the
default value for their arguments. This includes the location of the
knowledge base, the default target,<small class="dots">...</small>
</dl>
<h4 class="subsection">3.2.5 Interactive use</h4>
<p class="noindent">When you launch GPRconfig, it first searches for all compilers it
can find on your <span class="env">PATH</span>, that match the target specified by
<span class="option">--target</span>. It is recommended, although not
required, that you place the compilers that you expect to use for your
application in your <span class="env">PATH</span> before you launch <span class="command">gprconfig</span>,
since that simplifies the setup.
<p><div class="tip">The list of compilers is sorted so that the most likely compilers
appear first
</div>
<p>GPRconfig then displays the list of all the compilers
it has found, along with the language they can compile, the run-time
they use (when applicable),<small class="dots">...</small>. It then waits for you to select
one of the compilers. This list is sorted by language, then by order
in the <span class="env">PATH</span> environment variable (so that compilers that you
are more likely to use appear first), then by run-time names and
finally by version of the compiler. Thus the first
compiler for any language is most likely the one you want to use.
<p>You make a selection by entering the letter that appears on the line for
each compiler (be aware that this letter is case sensitive). If the compiler was
already selected, it is deselected.
<p><div class="tip">The list of compilers is filtered, so that only compatible compilers
can be selected
</div>
<p>A filtered list of compilers is then displayed:
only compilers that target the same platform as the selected
compiler are now shown. GPRconfig then checks whether it is
possible to link sources compiled with the selected compiler and each of
the remaining compilers; when linking is not possible, the compiler is not
displayed. Likewise, all compilers for the same language are hidden, so that
you can only select one compiler per language.
<p>As an example, if you need to compile your application with several C compilers,
you should create another language, for instance called C2, for that purpose.
That will give you the flexibility to indicate in the project files which
compiler should be used for which sources.
<p>The goal of this filtering is to make it more obvious whether you have
a good chance of being able to link. There is however no guarantee that
GPRconfig will know for certain how to link any combination of the
remaining compilers.
<p>You can select as many compilers as are needed by your application. Once you
have finished selecting the compilers, select <s>, and GPRconfig will
generate the configuration file.
<!-- -->
<p><a name="The-GPRconfig-knowledge-base"></a>
<h4 class="subsection">3.2.6 The GPRconfig knowledge base</h4>
<!-- -->
<p class="noindent">GPRconfig itself has no hard-coded knowledge of compilers. Thus there
is no need to recompile a new version of GPRconfig when a new compiler
is distributed.
<p><div class="note">The role and format of the knowledge base are irrelevant for most users
of GPRconfig, and are only needed when you need to add support for new
compilers. You can skip this section if you only want to learn how to use
GPRconfig.
</div>
<p>All knowledge of compilers is embedded in a set of XML files called the
<em>knowledge base</em>.
Users can easily contribute to this general knowledge base, and have
GPRconfig immediately take advantage of any new data.
<p>The knowledge base contains various kinds of information:
<ul>
<li>Compiler description
<p>When it is run interactively, GPRconfig searches the user's
<span class="env">PATH</span> for known compilers, and tries to deduce their
configuration (version, supported languages, supported targets, run-times,
<small class="dots">...</small>). From the knowledge base GPRconfig knows how to extract the
relevant information about a compiler.
<p>This step is optional, since a user can also enter all the information
manually. However, it is recommended that the knowledge base explicitly
list its known compilers, to make configuration easier for end users.
<li>Specific compilation switches
<p>When a compiler is used, depending on its version, target, run-time,<small class="dots">...</small>,
some specific command line switches might have to be supplied. The
knowledge base is a good place to store such information.
<p>For instance, with the GNAT compiler, using the soft-float runtime should
force <em>gprbuild</em> to use the <span class="option">-msoft-float</span> compilation switch.
<li>Linker options
<p>Linking a multi-language application often has some subtleties,
and typically requires specific linker switches.
These switches depend on the list of languages, the list
of compilers,<small class="dots">...</small>.
<li>Unsupported compiler mix
<p>It is sometimes not possible to link together code compiled with two
particular compilers. The knowledge base should store this information,
so that end users are informed immediately when attempting to
use such a compiler combination.
</ul>
<p class="noindent">The end of this section will describe in more detail the format of this
knowledge base, so that you can add your own information
and have GPRconfig advantage of it.
<!-- -->
<p><a name="General-file-format"></a>
<h5 class="subsubsection">3.2.6.1 General file format</h5>
<!-- -->
<p class="noindent">The knowledge base is implemented as a set of XML files. None of these
files has a special name, nor a special role. Instead, the user can
freely create new files, and put them in the knowledge base directory,
to contribute new knowledge.
<p>The location of the knowledge base is <span class="file">$prefix/share/gprconfig</span>,
where <span class="file">$prefix</span> is the directory in which GPRconfig was
installed. Any file with extension <span class="file">.xml</span> in this directory will
be parsed automatically by GPRconfig at startup.
<p>All files must have the following format:
<pre class="smallexample"> <?xml version="1.0">
<gprconfig>
...
</gprconfig>
</pre>
<p class="noindent">The root tag must be <code><gprconfig></code>.
<p>The remaining sections in this chapter will list the valid XML tags that
can be used to replace the “<small class="dots">...</small>” code above. These tags can either all be
placed in a single XML file, or split across several files.
<!-- -->
<p><a name="Compiler-description"></a>
<h5 class="subsubsection">3.2.6.2 Compiler description</h5>
<!-- -->
<p class="noindent">One of the XML tags that can be specified as a child of <code><gprconfig></code> is
<code><compiler_description></code>. This node and its children describe one of
the compilers known to GPRconfig. The tool uses them when it
initially looks for all compilers known on the user's <span class="env">PATH</span>
environment variable.
<p>This is optional information, but simplifies the use of GPRconfig,
since the user is then able to omit some parameters from the <span class="option">--config</span>
command line argument, and have them automatically computed.
<p>The <code><compiler_description></code> node doesn't accept any XML
attribute. However, it accepts a number of child tags that explain
how to query the various attributes of the compiler. The child tags
are evaluated (if necessary) in the same order as they are documented below.
<dl>
<dt><code><name></code><dd> This tag contains a simple string, which is the name of the compiler.
This name must be unique across all the configuration files, and is used to
identify that <code>compiler_description</code> node.
<pre class="smallexample"> <compiler_description>
<name>GNAT</name>
</compiler_description>
</pre>
<br><dt><code><executable></code><dd> This tag contains a string, which is the name of an executable
to search for on the PATH. Examples are <span class="samp">gnatls</span>, <span class="samp">gcc</span>,<small class="dots">...</small>
<p>In some cases, the tools have a common suffix, but a prefix that might depend
on the target. For instance, GNAT uses <span class="samp">gnatmake</span> for native platforms,
but <span class="samp">powerpc-wrs-vxworks-gnatmake</span> for cross-compilers to VxWorks.
Most of the compiler description is the same, however.
For such cases, the value of the <code>executable</code> node is considered as
beginning a regular expression. The tag also accepts an attribute <code>prefix</code>,
which is an integer indicating the parenthesis group that contains the prefix.
In the following example, you obtain the version of the GNAT compiler by running
either <span class="command">gnatls</span> or <span class="command">powerpc-wrs-vxworks-gnatls</span>, depending on
the name of the executable that was found.
<p>The regular expression needs to match the whole name of the file, i.e. it
contains an implicit “^” at the start, and an implicit “$” at the end.
Therefore if you specify <span class="samp">.*gnatmake</span> as the regexp, it will not match
<span class="samp">gnatmake-debug</span>.
<p>A special case is when this node is empty (but it must be specified!). In
such a case, you must also specify the language (see <language> below) as a
simple string. It is then assumed that the specified language does not
require a compiler. In the configurations file (see <a href="#Configurations">Configurations</a>),
you can test whether that language was specified on the command line by
using a filter such as
<pre class="smallexample"> <compilers>
<compiler language="name"/>
</compilers>
</pre>
<p class="noindent">
<pre class="smallexample"> <executable prefix="1">(powerpc-wrs-vxworks-)?gnatmake</executable>
<version><external>${PREFIX}gnatls -v</external></version>
</pre>
<p class="noindent">GPRconfig searches in all directories listed on the PATH for such
an executable. When one is found, the rest of the <code><compiler_description></code>
children are checked to know whether the compiler is valid. The directory
in which the executable was found becomes the “current directory” for
the remaining XML children.
<br><dt><code><target></code><dd>
This node indicates how to query the target architecture for the compiler.
See <a href="#GPRconfig-external-values">GPRconfig external values</a> for valid children.
<p>If this isn't specified, the compiler will always be considered as matching
on the current target.
<br><dt><code><version></code><dd>
This tag contains any of the nodes defined in <a href="#GPRconfig-external-values">GPRconfig external values</a> below.
It shows how to query the version number of the compiler. If the version
cannot be found, the executable will not be listed in the list of compilers.
<br><dt><code><variable name="varname"></code><dd>
This node will define a user variable which may be later referenced. The
variables are evaluated just after the version but before the languages
and the runtimes nodes. See <a href="#GPRconfig-external-values">GPRconfig external values</a>
below for valid children of
this node. If the evaluation of this variable is empty then the compiler
is considered as invalid.
<br><dt><code><languages></code><dd>
This node indicates how to query the list of languages. See
<a href="#GPRconfig-external-values">GPRconfig external values</a>
below for valid children of this node.
<p>The value returned by the system will be split into words. As a result, if
the returned value is “ada,c,c++”, there are three languages supported by the
compiler (and three entries are added to the menu when using GPRconfig
interactively).
<p>If the value is a simple string, the words must be comma-separated, so that
you can specify languages whose names include spaces. However, if the actual
value is computed from the result of a command, the words can also be
space-separated, to be compatible with more tools.
<br><dt><code><runtimes></code><dd>
This node indicates how to query the list of supported runtimes for the
compiler. See <a href="#GPRconfig-external-values">GPRconfig external values</a>
below for valid children. The returned value
is split into words as for <code><languages></code>.
</dl>
<!-- -->
<p><a name="GPRconfig-external-values"></a>
<h5 class="subsubsection">3.2.6.3 GPRconfig external values</h5>
<!-- -->
<p class="noindent">A number of the XML nodes described above can contain one or more children,
and specify how to query a value from an executable. Here is the list of
valid contents for these nodes. The <code><directory></code> and <code><external></code>
children can be repeated multiple times, and the <code><filter></code> and
<code><must_match></code> nodes will be applied to each of these. The final
value of the external value is the concatenation of the computation for each
of the <code><directory></code> and <code><external></code> nodes.
<p><a name="index-gprconfig_002c-external-values-82"></a>
<ul>
<li>A simple string
<p>A simple string given in the node indicates a constant. For
instance, the list of supported languages might be defined as:
<pre class="smallexample"> <compiler_description>
<name>GNAT</name>
<executable>gnatmake</executable>
<languages>Ada</languages>
</compiler_description>
</pre>
<p class="noindent">for the GNAT compiler, since this is an Ada-only compiler.
<p>Variables can be referenced in simple strings.
<li><code><getenv name="variable" /></code>
<p>If the contents of the node is a <code><getenv></code> child, the value of
the environment variable <span class="env">variable</span> is returned. If the variable is
not defined, this is an error and the compiler is ignored.
<pre class="smallexample"> <compiler_description>
<name>GCC-WRS</name>
<executable prefix="1">cc(arm|pentium)</executable>
<version>
<getenv name="WIND_BASE" />
</version>
</compile_description>
</pre>
<li><code><external>command</external></code>
<p>If the contents of the node is an <code><external></code> child, this indicates
that a command should be run on the system.
When the command is run, the current directory (i.e., the one that contains
the executable found through the <code><executable></code> node), is placed first
on the <span class="env">PATH</span>. The output of the command is returned and may be later
filtered. The command is not executed through a shell; therefore you cannot
use output redirection, pipes, or other advanced features.
<p>For instance, extracting the target processor from <span class="command">gcc</span> can be done
with:
<pre class="smallexample"> <version>
<external>gcc -dumpmachine</external>
</version>
</pre>
<p class="noindent">Since the <span class="env">PATH</span> has been modified, we know that the <span class="command">gcc</span> command
that is executed is the one from the same directory as the <code><external></code>
node.
<p>Variables are substituted in <var>command</var>.
<li><code><grep regexp="regexp" group="0" /></code>
<p>This node must come after the previously described ones. It is used to
further filter the output. The previous output is matched against the regular
expression <var>regexp</var> and the parenthesis group specified by
<var>group</var> is returned. By default, group is 0, which indicates the
whole output of the command.
<p>For instance, extracting the version number from <span class="command">gcc</span> can be done
with:
<pre class="smallexample"> <version>
<external>gcc -v</external>
<grep regexp="^gcc version (S+)" group="1" />
</version>
</pre>
<li><code><directory group="0">regexp</directory></code>
<p>If the contents of the node is a <code><directory</code>> child, this
indicates that GPRconfig should find all the files matching the
regular expression. Regexp is a path relative to the directory that contains
the <code><executable></code> file, and should use unix directory separators
(ie '/'), since the actual directory will be converted into this format
before the match, for system independence of the knowledge base.
<p>The group attribute indicates which parenthesis group should be returned.
It defaults to 0 which indicates the whole matched path. If this attribute is
a string rather than an integer, then it is the value returned.
<p><var>regexp</var> can be any valid regular expression. This will only match
a directory name, not a subdirectory. Remember to quote special characters,
including “.”, if you do not mean to use a regexp.
<p>For instance, finding the list of supported runtimes for the GNAT compiler
is done with:
<pre class="smallexample"> <runtimes>
<directory group="1">
../lib/gcc/${TARGET}/.*/rts-(.*)/adainclude
</directory>
<directory group="default">
../lib/gcc/${TARGET}/.*/adainclude
</directory>
</runtimes>
</pre>
<p class="noindent">Note the second node, which matches the default run-time, and displays it as
such.
<li><code><filter>value1,value2,...</filter></code>
<p>This node must come after one the previously described ones. It is used to
further filter the output. The previous output is split into words (it is
considered as a comma-separated or space-separated list of words), and only
those words in <span class="samp">value1</span>, <span class="samp">value2</span>,<small class="dots">...</small> are kept.
<p>For instance, the <span class="command">gcc</span> compiler will return a variety of supported
languages, including “ada”. If we do not want to use it as an Ada
compiler we can specify:
<pre class="smallexample"> <languages>
<external regexp="languages=(S+)" group="1">gcc -v</external>
<filter>c,c++,fortran</filter>
</languages>
</pre>
<li><code><must_match>regexp</must_match></code>
<p>If this node is present, then the filtered output is compared with the
specified regular expression. If no match is found, then the executable
is not stored in the list of known compilers.
<p>For instance, if you want to have a <code><compiler_description></code> tag
specific to an older version of GCC, you could write:
<pre class="smallexample"> <version>
<external regexp="gcc version (S+)"
group="1">gcc -v </external>
<must_match>2.8.1</must_match>
</version>
</pre>
<p class="noindent">Other versions of gcc will not match this <code><compiler_description></code>
node.
</ul>
<!-- -->
<p><a name="GPRconfig-variable-substitution"></a>
<h5 class="subsubsection">3.2.6.4 GPRconfig variable substitution</h5>
<!-- -->
<p class="noindent">The various compiler attributes defined above are made available as
variables in the rest of the XML files. Each of these variables can be used
in the value of the various nodes (for instance in <code><directory></code>),
and in the configurations (see <a href="#Configuration">Configuration</a>).
<p>A variable is referenced by <code>${name}</code> where <var>name</var> is either
a user variable or a predefined variable. An alternate reference is
<code>$name</code> where <var>name</var> is a sequence of alpha numeric characters or
underscores. Finally <code>$$</code> is replaced by a simple <code>$</code>.
<p>User variables are defined by <code><variable></code> nodes and may override
predefined variables. To avoid a possible override use lower case names.
<p>Predefined variables are always in upper case. Here is the list of
predefined variables
<dl>
<dt><var>${EXEC}</var><dd>is the name of the executable that was found through <code><executable></code>. It
only contains the basename, not the directory information.
<br><dt><var>${HOST}</var><dd>is replaced by the architecture of the host on which GPRconfig is
running. This name is hard-coded in GPRconfig itself, and is generated
by <span class="command">configure</span> when GPRconfig was built.
<br><dt><var>${TARGET}</var><dd>is replaced by the target architecture of the compiler, as returned by the
<code><target></code> node. This is of course not available when computing the
target itself.
<br><dt><var>${VERSION}</var><dd>is replaced by the version of the compiler. This is not available when
computing the target or, of course, the version itself.
<br><dt><var>${PREFIX}</var><dd>is replaced by the prefix to the executable name, as defined by the
<code><executable></code> node.
<br><dt><var>${PATH}</var><dd>is the current directory, i.e. the one containing the executable found through
<code><executable></code>. It always ends with a directory separator.
<br><dt><var>${GPRCONFIG_PREFIX}</var><dd>is the directory in which GPRconfig was installed (e.g
<span class="file">"/usr/local/"</span> if the executable is <span class="file">"/usr/local/bin/gprconfig"</span>.
This directory always ends with a directory separator.
<br><dt><var>${LANGUAGE}</var><dd>is the language supported by the compiler, always folded to lower-case
<br><dt><var>${RUNTIME}</var><dt><var>${RUNTIME_DIR}</var><dd>This string will always be substituted by the empty string when the
value of the external value is computed. These are special strings
used when substituting text in configuration chunks.
<p><var>RUNTIME_DIR</var> always end with a directory separator.
</dl>
<p>If a variable is not defined, an error message is issued and the variable
is substituted by an empty string.
<!-- -->
<p><a name="Configurations"></a>
<h5 class="subsubsection">3.2.6.5 Configurations</h5>
<!-- -->
<p class="noindent">The second type of information stored in the knowledge base are the chunks
of <em>gprbuild</em> configuration files.
<p>Each of these chunks is also placed in an XML node that provides optional
filters. If all the filters match, then the chunk will be merged with other
similar chunks and placed in the final configuration file that is generated
by GPRconfig.
<p>For instance, it is possible to indicate that a chunk should only be
included if the GNAT compiler with the soft-float runtime is used. Such
a chunk can for instance be used to ensure that Ada sources are always
compiled with the <code>-msoft-float</code> command line switch.
<p>GPRconfig does not perform sophisticated merging of chunks. It simply
groups packages together. For example, if the two chunks are:
<pre class="smallexample"> chunk1:
<b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> ("foo");
<b>end</b> Language_Processing;
chunk2:
<b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> ("bar");
<b>end</b> Language_Processing;
</pre>
<p class="noindent">Then the final configuration file will look like:
<pre class="smallexample"> <b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> ("foo");
<b>for</b> Attr1 <b>use</b> ("bar");
<b>end</b> Language_Processing;
</pre>
<p class="noindent">As a result, to avoid conflicts, it is recommended that the chunks be
written so that they easily collaborate together. For instance,
to obtain something equivalent to
<pre class="smallexample"> <b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> ("foo", "bar");
<b>end</b> Language_Processing;
</pre>
<p class="noindent">the two chunks above should be written as:
<pre class="smallexample"> chunk1:
<b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> Language_Processing'Attr1 & ("foo");
<b>end</b> Language_Processing;
chunk2:
<b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> Language_Processing'Attr1 & ("bar");
<b>end</b> Language_Processing;
</pre>
<p class="noindent">The chunks are described in a <code><configuration></code> XML node. The most
important child of such a node is <code><config></code>, which contains the
chunk itself. For instance, you would write:
<pre class="smallexample"> <configuration>
<i>... list of filters, see below</i>
<config>
<b>package</b> Language_Processing <b>is</b>
<b>for</b> Attr1 <b>use</b> Language_Processing'Attr1 & ("foo");
<b>end</b> Language_Processing;
</config>
</configuration>
</pre>
<p class="noindent">If <code><config></code> is an empty node (i.e., <span class="samp"><config/></span> or
<span class="samp"><config></config></span>) was used, then the combination of selected
compilers will be reported as invalid, in the sense that code
compiled with these compilers cannot be linked together. As a result,
GPRconfig will not create the configuration file.
<p>The special variables (see <a href="#GPRconfig-variable-substitution">GPRconfig variable substitution</a>) are also
substituted in the chunk. That allows you to compute some attributes of the
compiler (its path, the runtime,<small class="dots">...</small>), and use them when generating the
chunks.
<p>The filters themselves are of course defined through XML tags, and can
be any of:
<dl>
<dt><code><compilers negate="false"></code><dd>
This filter contains a list of <code><compiler></code> children. The
<code><compilers></code> filter matches if any of its children match.
However, you can have several <code><compilers></code> filters, in which
case they must all match. This can be used to include linker switches
chunks. For instance, the following code would be used to describe
the linker switches to use when GNAT 5.05 or 5.04 is used in addition to
g++ 3.4.1:
<pre class="smallexample"> <configuration>
<compilers>
<compiler name="GNAT" version="5.04" />
<compiler name="GNAT" version="5.05" />
</compilers>
<compilers>
<compiler name="G++" version="3.4.1" />
</compilers>
...
</configuration>
</pre>
<p class="noindent">If the attribute <var>negate</var> is <span class="samp">true</span>, then the meaning of this
filter is inverted, and it will match if none of its children matches.
<p>The format of the <code><compiler></code> is the following:
<pre class="smallexample"> <compiler name="name" version="..."
runtime="..." language="..." />
</pre>
<p class="noindent">The name and language attributes, when specified, match
the corresponding attributes used in the <code><compiler_description></code>
children. All other attributes are regular expressions, which are matched
against the corresponding selected compilers. When an attribute is not
specified, it will always match. Matching is done in a case-insensitive
manner.
<p>For instance, to check a GNAT compiler in the 5.x family, use:
<pre class="smallexample"> <compiler name="GNAT" version="5.d+" />
</pre>
<br><dt><code><hosts negate="false"></code><dd>
This filter contains a list of <code><host></code> children. It matches when
any of its children matches. You can specify only one <code><hosts></code>
node.
The format of <code><host></code> is a node with a single mandatory attribute
<var>name</var>, which is a regexp matched against the architecture on
which GPRconfig is running. The name of the architecture was
computed by <code>configure</code> when GPRconfig was built. Note that
the regexp might match a substring of the host name, so you might want
to surround it with "^" and "$" so that it only matches the whole host
name (for instance, "elf" would match "powerpc-elf", but "^elf$" would
not).
<p>If the <var>negate</var> attribute is <span class="samp">true</span>, then the meaning of this
filter is inverted, and it will match when none of its children matches.
<p>For instance, to active a chunk only if the compiler is running on an
intel linux machine, use:
<pre class="smallexample"> <hosts>
<host name="i.86-.*-linux(-gnu)?" />
</hosts>
</pre>
<br><dt><code><targets negate="false"></code><dd>
This filter contains a list of <code><target></code> children. It behaves
exactly like <code><hosts></code>, but matches against the architecture
targeted by the selected compilers. For instance, to activate a chunk
only when the code is targeted for linux, use:
<p>If the <var>negate</var> attribute is <span class="samp">true</span>, then the meaning of this filter
is inverted, and it will match when none of its children matches.
<pre class="smallexample"> <targets>
<target name="i.86-.*-linux(-gnu)?" />
</targets>
</pre>
</dl>
<!-- -->
<p><a name="Configuration-File-Reference"></a>
<h3 class="section">3.3 Configuration File Reference</h3>
<!-- -->
<p class="noindent"><!-- ??? From the "Important concepts" section -->
A text file using the project file syntax. It defines languages and
their characteristics as well as toolchains for those languages and their
characteristics.
<!-- ??? end -->
<p>GPRbuild needs to have a configuration file to know the different
characteristics of the toolchains that can be used to compile sources and
build libraries and executables.
<p>A configuration file is a special kind of project file: it uses the same
syntax as a standard project file. Attributes in the configuration file
define the configuration. Some of these attributes have a special meaning
in the configuration.
<p>The default name of the configuration file, when not specified to
GPRbuild by switches <span class="option">--config=</span> or <span class="option">--autoconf=</span> is
<span class="file">default.cgpr</span>. Although the name of the configuration file can
be any valid file name, it is recommended that its suffix be
<span class="file">.cgpr</span> (for Configuration GNAT Project), so that it cannot be
confused with a standard project file which has the suffix
<span class="file">.gpr</span>.
<p>When <span class="file">default.cgpr</span> cannot be found in the configuration project path,
GPRbuild invokes GPRconfig to create a configuration file.
<p>In the following description of the attributes, when an attribute is an
associative array indexed by the language name, for example
<code>Spec_Suffix (<language>)</code>, then the name of the language is case insensitive.
For example, both <code>C</code> and <code>c</code> are allowed.
<p>Any attribute may appear in a configuration project file. All attributes in
a configuration project file are inherited by each user project file in the
project tree. However, usually only the attributes listed below make sense
in the configuration project file.
<!-- -->
<p><a name="Project-Level-Attributes"></a>
<h4 class="subsection">3.3.1 Project Level Attributes</h4>
<!-- -->
<p class="noindent">
<!-- -->
<a name="General-Attributes"></a>
<h5 class="subsubsection">3.3.1.1 General Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Default_Language
<p>Specifies the name of the language of the immediate sources of a project when
attribute <code>Languages</code> is not declared in the project. If attribute
<code>Default_Language</code> is not declared in the configuration file, then each user
project file in the project tree must have an attribute <code>Languages</code> declared,
unless it extends another project. Example:
<pre class="smallexample"> for Default_Language use "ada";
</pre>
<li>Run_Path_Option
<p>Specifies a “run path option”; i.e., an option to use when linking an
executable or a shared library to indicate the path where to look for other
libraries. The value of this attribute is a string list. When linking an
executable or a shared library, the search path is concatenated with the last
string in the list, which may be an empty string. Example:
<pre class="smallexample"> for Run_Path_Option use ("-Wl,-rpath,");
</pre>
<li>Toolchain_Version (<language>)
<p>Specifies a version for a toolchain, as a single string. This toolchain
version is passed to the library builder. Example:
<pre class="smallexample"> for Toolchain_Version ("Ada") use "GNAT 6.1";
</pre>
<p class="noindent">This attribute is used by GPRbind to decide on the names of the shared GNAT
runtime libraries.
<li>Toolchain_Description (<language>)
<p>Specifies as a single string a description of a toolchain. This attribute is
not directly used by GPRbuild or its auxiliary tools (GPRbind and GPRlib) but
may be used by other tools, for example GPS. Example:
<pre class="smallexample"> for Toolchain_Description ("C") use "gcc version 4.1.3 20070425";
</pre>
</ul>
<!-- -->
<p><a name="General-Library-Related-Attributes"></a>
<h5 class="subsubsection">3.3.1.2 General Library Related Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Library_Support
<p>Specifies the level of support for library project. If this attribute is not
specified, then library projects are not supported. The only potential values
for this attribute are <code>none</code>, <code>static_only</code> and <code>full</code>. Example:
<pre class="smallexample"> for Library_Support use "full";
</pre>
<li>Library_Builder
<p>Specifies the name of the executable for the library builder. Example:
<pre class="smallexample"> for Library_Builder use "/.../gprlib";
</pre>
</ul>
<!-- -->
<p><a name="Archive-Related-Attributes"></a>
<h5 class="subsubsection">3.3.1.3 Archive Related Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Archive_Builder
<p>Specifies the name of the executable of the archive builder with the minimum
options, if any. Example:
<pre class="smallexample"> for Archive_Builder use ("ar", "cr");
</pre>
<li>Archive_Indexer
<p>Specifies the name of the executable of the archive indexer with the minimum
options, if any. If this attribute is not specified, then there is no
archive indexer. Example:
<pre class="smallexample"> for Archive_Indexer use ("ranlib");
</pre>
<li>Archive_Suffix
<p>Specifies the suffix of the archives. If this attribute is not specified, then
the suffix of the archives is defaulted to <span class="file">.a</span>. Example:
<pre class="smallexample"> for Archive_Suffix use ".olb"; -- for VMS
</pre>
<li>Library_Partial_Linker
<p>Specifies the name of the executable of the partial linker with the options
to be used, if any. If this attribute is not specified, then there is no
partial linking. Example:
<pre class="smallexample"> for Library_Partial_Linker use ("gcc", "-nostdlib", "-Wl,-r", "-o");
</pre>
</ul>
<!-- -->
<p><a name="Shared-Library-Related-Attributes"></a>
<h5 class="subsubsection">3.3.1.4 Shared Library Related Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Shared_Library_Prefix
<p>Specifies the prefix of the file names of shared libraries. When this attribute
is not specified, the prefix is <code>lib</code>. Example:
<pre class="smallexample"> for Shared_Library_Prefix use ""; -- for Windows, if needed
</pre>
<li>Shared_Library_Suffix
<p>Specifies the suffix of the file names of shared libraries. When this attribute
is not specified, the suffix is <span class="file">.so</span>. Example:
<pre class="smallexample"> for Shared_Library_Suffix use ".dll"; -- for Windows
</pre>
<li>Symbolic_Link_Supported
<p>Specifies if symbolic links are supported by the platforms. The possible values
of this attribute are <code>"false"</code> (the default) and <code>"true"</code>. When this attribute is
not specified, symbolic links are not supported.
<pre class="smallexample"> for Symbolic_Link_Supported use "true";
</pre>
<li>Library_Major_Minor_ID_Supported
<p>Specifies if major and minor IDs are supported for shared libraries.
The possible values of this attribute are <code>"false"</code> (the default) and <code>"true"</code>.
When this attribute is not specified, major and minor IDs are not supported.
<pre class="smallexample"> for Library_Major_Minor_ID_Supported use "True";
</pre>
<li>Library_Auto_Init_Supported
<p>Specifies if library auto initialization is supported. The possible values of
this attribute are <code>"false"</code> (the default) and <code>"true"</code>. When this attribute is not
specified, library auto initialization is not supported.
<pre class="smallexample"> for Library_Auto_Init_Supported use "true";
</pre>
<li>Shared_Library_Minimum_Switches
<p>Specifies the minimum options to be used when building a shared
library. These options are put in the appropriate section in the
library exchange file when the library builder is invoked. Example:
<pre class="smallexample"> for Shared_Library_Minimum_Switches use ("-shared");
</pre>
<li>Library_Version_Switches
<p>Specifies the option or options to be used when a library version is used.
These options are put in the appropriate section in the library exchange file
when the library builder is invoked. Example:
<pre class="smallexample"> for Library_Version_Switches use ("-Wl,-soname,");
</pre>
<li>Runtime_Library_Dir (<language>)
<p>Specifies the directory for the runtime libraries for the language.
Example:
<pre class="smallexample"> for Runtime_Library_Dir ("Ada") use "/path/to/adalib";
</pre>
<p class="noindent">This attribute is used by GPRlib to link shared libraries with Ada code.
</ul>
<!-- -->
<p><a name="Package-Naming"></a>
<h4 class="subsection">3.3.2 Package Naming</h4>
<!-- -->
<p class="noindent">Attributes in package <code>Naming</code> of a configuration file specify defaults. These
attributes may be used in user project files to replace these defaults.
<p>The following attributes usually appear in package <code>Naming</code> of a configuration
file:
<ul>
<li>Spec_Suffix (<language>)
<p>Specifies the default suffix for a “spec” or header file. Examples:
<pre class="smallexample"> for Spec_Suffix ("Ada") use ".ads";
for Spec_Suffix ("C") use ".h";
for Spec_Suffix ("C++") use ".hh";
</pre>
<li>Body_Suffix (<language>)
<p>Specifies the default suffix for a “body” or a source file. Examples:
<pre class="smallexample"> for Body_Suffix ("Ada") use ".adb";
for Body_Suffix ("C") use ".c";
for Body_Suffix ("C++") use ".cpp";
</pre>
<li>Separate_Suffix
<p>Specifies the suffix for a subunit source file (separate) in Ada. If attribute
<code>Separate_Suffix</code> is not specified, then the default suffix of subunit source
files is the same as the default suffix for body source files. Example:
<pre class="smallexample"> for Separate_Suffix use ".sep";
</pre>
<li>Casing
<p>Specifies the casing of spec and body files in a unit based language
(such as Ada) to know how to map a unit name to its file name. The values for
this attribute may only be <code>"lowercase"</code>, <code>"UPPERCASE"</code> and <code>"Mixedcase"</code>.
The default, when attribute <code>Casing</code> is not specified is lower case.
This attribute rarely needs to be specified, since on
platforms where file names are not case sensitive (such as Windows or VMS)
the default (lower case) will suffice.
<li>Dot_Replacement
<p>Specifies the string to replace a dot (“.”) in unit names of a unit based
language (such as Ada) to obtain its file name. If there is any unit based
language in the configuration, attribute <code>Dot_Replacement</code> must be declared.
Example:
<pre class="smallexample"> for Dot_Replacement use "-";
</pre>
</ul>
<!-- -->
<p><a name="Package-Builder"></a>
<h4 class="subsection">3.3.3 Package Builder</h4>
<!-- -->
<p class="noindent">
<ul>
<li>Executable_Suffix
<p>Specifies the default executable suffix. If no attribute <code>Executable_Suffix</code> is
declared, then the default executable suffix for the host platform is used.
Example:
<pre class="smallexample"> for Executable_Suffix use ".exe";
</pre>
</ul>
<!-- -->
<p><a name="Package-Compiler"></a>
<h4 class="subsection">3.3.4 Package Compiler</h4>
<!-- -->
<p class="noindent">
<!-- -->
<a name="General-Compilation-Attributes"></a>
<h5 class="subsubsection">3.3.4.1 General Compilation Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Driver (<language>)
<p>Specifies the name of the executable for the compiler of a language. The single
string value of this attribute may be an absolute path or a relative path. If
relative, then the execution path is searched. Specifying the empty string for
this attribute indicates that there is no compiler for the language.
<p>Examples:
<pre class="smallexample"> for Driver ("C++") use "g++";
for Driver ("Ada") use "/.../bin/gcc";
for Driver ("Project file") use "";
</pre>
<li>Required_Switches (<language>)
<p>Specifies the minimum options that must be used when invoking the compiler
of a language. Examples:
<pre class="smallexample"> for Required_Switches ("C") use ("-c", "-x", "c");
for Required_Switches ("Ada") use ("-c", "-x", "ada", "-gnatA");
</pre>
<li>PIC_Option (<language>)
<p>Specifies the option or options that must be used when compiling a source of
a language to be put in a shared library. Example:
<pre class="smallexample"> for PIC_Option ("C") use ("-fPIC");
</pre>
</ul>
<!-- -->
<p><a name="Mapping-File-Related-Attributes"></a>
<h5 class="subsubsection">3.3.4.2 Mapping File Related Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Mapping_File_Switches (<language>)
<p>Specifies the switch or switches to be used to specify a mapping file to the
compiler. When attribute <code>Mapping_File_Switches</code> is not declared, then no
mapping file is specified to the compiler. The value of this attribute is a
string list. The path name of the mapping file is concatenated with the last
string in the string list, which may be empty. Example:
<pre class="smallexample"> for Mapping_File_Switches ("Ada") use ("-gnatem=");
</pre>
<li>Mapping_Spec_Suffix (<language>)
<p>Specifies, for unit based languages that support mapping files, the suffix in
the mapping file that needs to be added to the unit name for specs. Example:
<pre class="smallexample"> for Mapping_Spec_Suffix ("Ada") use "%s";
</pre>
<li>Mapping_Body_Suffix (<language>)
<p>Specifies, for unit based languages that support mapping files, the suffix in
the mapping file that needs to be added to the unit name for bodies. Example:
<pre class="smallexample"> for Mapping_Spec_Suffix ("Ada") use "%b";
</pre>
</ul>
<!-- -->
<p><a name="Config-File-Related-Attributes"></a>
<h5 class="subsubsection">3.3.4.3 Config File Related Attributes</h5>
<!-- -->
<p class="noindent">In the value of config file attributes defined below, there are some
placeholders that GPRbuild will replace. These placeholders are:
<ul>
<li>%u : the unit name
<li>%f : the file name of the source
<li>%s : the spec suffix
<li>%b : the body suffix
<li>%c : the casing
<li>%d : the dot replacement string
</ul>
<p class="noindent">Attributes:
<ul>
<li>Config_File_Switches (<language>)
<p>Specifies the switch or switches to be used to specify a configuration file to
the compiler. When attribute <code>Config_File_Switches</code> is not declared, then no
config file is specified to the compiler. The value of this attribute is a
string list. The path name of the config file is concatenated with the last
string in the string list, which may be empty. Example:
<pre class="smallexample"> for Config_File_Switches ("Ada") use ("-gnatec=");
</pre>
<li>Config_Body_File_Name (<language>)
<p>Specifies the line to be put in a config file to indicate the file name of a
body. Example:
<pre class="smallexample"> for Config_Body_File_Name ("Ada") use
"pragma Source_File_Name_Project (%u, Body_File_Name => ""%f"");";
</pre>
<li>Config_Spec_File_Name (<language>)
<p>Specifies the line to be put in a config file to indicate the file name of a
spec. Example:
<pre class="smallexample"> for Config_Spec_File_Name ("Ada") use
"pragma Source_File_Name_Project (%u, Spec_File_Name => ""%f"");";
</pre>
<li>Config_Body_File_Name_Pattern (<language>)
<p>Specifies the line to be put in a config file to indicate a body file name
pattern. Example:
<pre class="smallexample"> for Config_Body_File_Name_Pattern ("Ada") use
"pragma Source_File_Name_Project " &
" (Body_File_Name => ""*%b""," &
" Casing => %c," &
" Dot_Replacement => ""%d"");";
</pre>
<li>Config_Spec_File_Name_Pattern (<language>)
<p>Specifies the line to be put in a config file to indicate a spec file name
pattern. Example:
<pre class="smallexample"> for Config_Spec_File_Name_Pattern ("Ada") use
"pragma Source_File_Name_Project " &
" (Spec_File_Name => ""*%s""," &
" Casing => %c," &
" Dot_Replacement => ""%d"");";
</pre>
<li>Config_File_Unique (<language>)
<p>Specifies, for languages that support config files, if several config files
may be indicated to the compiler, or not. This attribute may have only two
values: <code>"true"</code> or <code>"false"</code> (case insensitive). The default, when this attribute
is not specified, is <code>"false"</code>. When the value <code>"true"</code> is specified for this
attribute, GPRbuild will concatenate the config files, if there are more than
one. Example:
<pre class="smallexample"> for Config_File_Unique ("Ada") use "True";
</pre>
</ul>
<!-- -->
<p><a name="Dependency-Related-Attributes"></a>
<h5 class="subsubsection">3.3.4.4 Dependency Related Attributes</h5>
<!-- -->
<p class="noindent">There are two dependency-related attributes: <code>Dependency_Switches</code> and
<code>Dependency_Driver</code>. If neither of these two attributes are specified for
a language other than Ada, then the source needs to be (re)compiled if
the object file does not exist or the source file is more recent than
the object file or the switch file.
<ul>
<li>Dependency_Switches (<language>)
<p>For languages other than Ada, attribute <code>Dependency_Switches</code> specifies
the option or options to add to the compiler invocation so that it creates
the dependency file at the same time. The value of attribute <code>Dependency_Option</code>
is a string list. The name of the dependency file is added to the last string
in the list, which may be empty. Example:
<pre class="smallexample"> for Dependency_Switches ("C") use ("-Wp,-MD,");
</pre>
<p class="noindent">With these <code>Dependency_Switches</code>, when compiling <span class="file">file.c</span> the compiler will be
invoked with the option <span class="option">-Wp,-MD,file.d</span>.
<li>Dependency_Driver (<language>)
<p>Specifies the command and options to create a dependency file for a source.
The full path name of the source is appended to the last string of the string
list value. Example:
<pre class="smallexample"> for Dependency_Driver ("C") use ("gcc", "-E", "-Wp,-M", "");
</pre>
<p class="noindent">Usually, attributes <code>Dependency_Switches</code> and <code>Dependency_Driver</code> are not both
specified.
</ul>
<!-- -->
<p><a name="Search-Path-Related-Attributes"></a>
<h5 class="subsubsection">3.3.4.5 Search Path Related Attributes</h5>
<!-- -->
<p class="noindent">
<ul>
<li>Include_Switches (<language>)
<p>Specifies the option or options to use when invoking the compiler to indicate
that a directory is part of the source search path. The value of this
attribute is a string list. The full path name of the directory is concatenated
with the last string in the string list, which may be empty. Example:
<pre class="smallexample"> for Include_Switches ("C") use ("-I");
</pre>
<p class="noindent">Attribute <code>Include_Switches</code> is ignored if either one of the attributes
<code>Include_Path</code> or <code>Include_Path_File</code> are specified.
<li>Include_Path (<language>)
<p>Specifies the name of an environment variable that is used by the compiler to
get the source search path. The value of the environment variable is the source
search path to be used by the compiler. Example:
<pre class="smallexample"> for Include_Path ("C") use "CPATH";
for Include_Path ("Ada") use "ADA_INCLUDE_PATH";
</pre>
<p class="noindent">Attribute <code>Include_Path</code> is ignored if attribute <code>Include_Path_File</code> is declared
for the language.
<li>Include_Path_File (<language>)
<p>Specifies the name of an environment variable that is used by the compiler to
get the source search path. The value of the environment variable is the path
name of a text file that contains the path names of the directories of the
source search path. Example:
<pre class="smallexample"> for Include_Path_File ("Ada") use "ADA_PRJ_INCLUDE_FILE";
</pre>
</ul>
<!-- -->
<p><a name="Package-Binder"></a>
<h4 class="subsection">3.3.5 Package Binder</h4>
<!-- -->
<p class="noindent">
<ul>
<li>Driver (<language>)
<p>Specifies the name of the executable of the binder driver. When this attribute
is not specified, there is no binder for the language. Example:
<pre class="smallexample"> for Driver ("Ada") use "/.../gprbind";
</pre>
<li>Required_Switches (<language>)
<p>Specifies the minimum options to be used when invoking the binder driver.
These options are put in the appropriate section in the binder exchange file,
one option per line. Example:
<pre class="smallexample"> for Required_Switches ("Ada") use ("--prefix=<prefix>");
</pre>
<li>Prefix (<language>)
<p>Specifies the prefix to be used in the name of the binder exchange file.
Example:
<pre class="smallexample"> for Prefix ("C++") use ("c__");
</pre>
<li>Objects_Path (<language>)
<p>Specifies the name of an environment variable that is used by the compiler to
get the object search path. The value of the environment variable is the object
search path to be used by the compiler. Example:
<pre class="smallexample"> for Objects_Path ("Ada") use "ADA_OBJECTS_PATH";
</pre>
<li>Objects_Path_File (<language>)
<p>Specifies the name of an environment variable that is used by the compiler to
get the object search path. The value of the environment variable is the path
name of a text file that contains the path names of the directories of the
object search path. Example:
<pre class="smallexample"> for Objects_Path_File ("Ada") use "ADA_PRJ_OBJECTS_FILE";
</pre>
</ul>
<!-- -->
<p><a name="Package-Linker"></a>
<h4 class="subsection">3.3.6 Package Linker</h4>
<!-- -->
<p class="noindent">
<ul>
<li>Driver
<p>Specifies the name of the executable of the linker. Example:
<pre class="smallexample"> for Driver use "g++";
</pre>
<li>Required_Switches
<p>Specifies the minimum options to be used when invoking the linker. Those
options are happened at the end of the link command so that potentially
conflicting user options take precedence.
</ul>
<p><a name="GNU-Free-Documentation-License"></a>
<h2 class="appendix">Appendix A GNU Free Documentation License</h2>
<p><a name="index-GNU-Free-Documentation-License-83"></a><a name="index-License_002c-GNU-Free-Documentation-84"></a><a name="index-Free-Documentation-License_002c-GNU-85"></a>
<!-- GNU Free Documentation License -->
Version 1.1, March 2000
<pre class="sp">
</pre>
Copyright © 2000 Free Software Foundation, Inc.
<br>
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
<pre class="sp">
</pre>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
<h3 class="heading">0. PREAMBLE</h3>
<p>The purpose of this License is to make a manual, textbook, or other
written document “free” in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.
<p>This License is a kind of “copyleft”, which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
<p>We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
<h3 class="heading">1. APPLICABILITY AND DEFINITIONS</h3>
<p>This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License. The “Document”, below, refers to any
such manual or work. Any member of the public is a licensee, and is
addressed as “you”.
<p>A “Modified Version” of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
<p>A “Secondary Section” is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
<p>The “Invariant Sections” are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
<p>The “Cover Texts” are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
<p>A “Transparent” copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not “Transparent” is called “Opaque”.
<p>Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML designed for human modification. Opaque formats include
PostScript, PDF, proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output
purposes only.
<p>The “Title Page” means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, “Title Page” means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
<h3 class="heading">2. VERBATIM COPYING</h3>
<p>You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
<p>You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
<h3 class="heading">3. COPYING IN QUANTITY</h3>
<p>If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
<p>If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
<p>If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.
<p>It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
<h3 class="heading">4. MODIFICATIONS</h3>
<p>You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
<ol type=A start=1>
<li>Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
<li>List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five).
<li>State on the Title page the name of the publisher of the
Modified Version, as the publisher.
<li>Preserve all the copyright notices of the Document.
<li>Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
<li>Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
<li>Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
<li>Include an unaltered copy of this License.
<li>Preserve the section entitled “History”, and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section entitled “History” in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
<li>Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the “History” section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
<li>In any section entitled “Acknowledgements” or “Dedications”,
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
<li>Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
<li>Delete any section entitled “Endorsements”. Such a section
may not be included in the Modified Version.
<li>Do not retitle any existing section as “Endorsements”
or to conflict in title with any Invariant Section.
</ol>
<p>If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
<p>You may add a section entitled “Endorsements”, provided it contains
nothing but endorsements of your Modified Version by various
parties – for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
<p>You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
<p>The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
<h3 class="heading">5. COMBINING DOCUMENTS</h3>
<p>You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.
<p>The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
<p>In the combination, you must combine any sections entitled “History”
in the various original documents, forming one section entitled
“History”; likewise combine any sections entitled “Acknowledgements”,
and any sections entitled “Dedications”. You must delete all sections
entitled “Endorsements.”
<p>Heading 6. COLLECTIONS OF DOCUMENTS
<p>You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
<p>You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
<h3 class="heading">7. AGGREGATION WITH INDEPENDENT WORKS</h3>
<p>A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an “aggregate”, and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
<p>If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.
<h3 class="heading">8. TRANSLATION</h3>
<p>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the
original English version of this License. In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.
<h3 class="heading">9. TERMINATION</h3>
<p>You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
<h3 class="heading">10. FUTURE REVISIONS OF THIS LICENSE</h3>
<p>The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
<p>Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License “or any later version” applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
<h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
<p>To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
<blockquote>
Copyright (c) YEAR YOUR NAME.
<br>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled “GNU
Free Documentation License”.
</blockquote>
<p>If you have no Invariant Sections, write “with no Invariant Sections”
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write “no Front-Cover Texts” instead of
“Front-Cover Texts being LIST”; likewise for Back-Cover Texts.
<p>If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
<!-- -->
<p><a name="Index"></a>
<h2 class="unnumbered">Index</h2>
<!-- -->
<p class="noindent">
<ul class="index-cp" compact>
<li><a href="#index-_0040option_007b_002d_002dbatch_007d-for-gprconfig-78"><span class="option">--batch</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002d_002dconfig_007d-for-gprconfig-77"><span class="option">--config</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002d_002ddb_007d-for-gprconfig-80"><span class="option">--db</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002d_002dshow_002dtarget_007d-for-gprconfig-76"><span class="option">--show-target</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002d_002dsubdirs_003d_007d-_0028gnatmake-and-gnatclean_0029-74"><span class="option">--subdirs=</span> (gnatmake and gnatclean)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040option_007b_002d_002dtarget_007d-for-gprconfig-75"><span class="option">--target</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002daP_007d-_0028any-project_002daware-tool_0029-72"><span class="option">-aP</span> (any project-aware tool)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040option_007b_002deL_007d-_0028any-project_002daware-tool_0029-73"><span class="option">-eL</span> (any project-aware tool)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040option_007b_002dh_007d-for-gprconfig-81"><span class="option">-h</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002do_007d-for-gprconfig-79"><span class="option">-o</span> for gprconfig</a>: <a href="#Using-GPRconfig">Using GPRconfig</a></li>
<li><a href="#index-_0040option_007b_002dP_007d-_0028any-project_002daware-tool_0029-69"><span class="option">-P</span> (any project-aware tool)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040option_007b_002dv_007d-option-_0028for-GPRbuild_0029-21"><span class="option">-v</span> option (for GPRbuild)</a>: <a href="#Compiling-with-Project-Files">Compiling with Project Files</a></li>
<li><a href="#index-_0040option_007b_002dvP_007d-_0028any-project_002daware-tool_0029-71"><span class="option">-vP</span> (any project-aware tool)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040option_007b_002dX_007d-45"><span class="option">-X</span></a>: <a href="#Scenarios-in-Projects">Scenarios in Projects</a></li>
<li><a href="#index-_0040option_007b_002dX_007d-_0028any-project_002daware-tool_0029-70"><span class="option">-X</span> (any project-aware tool)</a>: <a href="#Switches-Related-to-Project-Files">Switches Related to Project Files</a></li>
<li><a href="#index-_0040code_007bADA_005fPROJECT_005fPATH_007d-39"><code>ADA_PROJECT_PATH</code></a>: <a href="#Project-Dependencies">Project Dependencies</a></li>
<li><a href="#index-_0040code_007bBody_007d-33"><code>Body</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bBody_005fSuffix_007d-28"><code>Body_Suffix</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-case-statement-48">case statement</a>: <a href="#Scenarios-in-Projects">Scenarios in Projects</a></li>
<li><a href="#index-_0040code_007bCasing_007d-24"><code>Casing</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-command-line-length-16">command line length</a>: <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a></li>
<li><a href="#index-_0040code_007bDefault_005fSwitches_007d-18"><code>Default_Switches</code></a>: <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a></li>
<li><a href="#index-_0040code_007bDot_005fReplacement_007d-25"><code>Dot_Replacement</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bExcluded_005fSource_005fDirs_007d-5"><code>Excluded_Source_Dirs</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bExcluded_005fSource_005fFiles_007d-66"><code>Excluded_Source_Files</code></a>: <a href="#Project-Extension">Project Extension</a></li>
<li><a href="#index-_0040code_007bExcluded_005fSource_005fFiles_007d-10"><code>Excluded_Source_Files</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bExcluded_005fSource_005fList_005fFile_007d-67"><code>Excluded_Source_List_File</code></a>: <a href="#Project-Extension">Project Extension</a></li>
<li><a href="#index-_0040code_007bExcluded_005fSource_005fList_005fFile_007d-12"><code>Excluded_Source_List_File</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bExec_005fDir_007d-14"><code>Exec_Dir</code></a>: <a href="#Object-and-Exec-Directory">Object and Exec Directory</a></li>
<li><a href="#index-_0040code_007bExecutable_007d-22"><code>Executable</code></a>: <a href="#Executable-File-Names">Executable File Names</a></li>
<li><a href="#index-_0040code_007bExecutable_005fSuffix_007d-23"><code>Executable_Suffix</code></a>: <a href="#Executable-File-Names">Executable File Names</a></li>
<li><a href="#index-extends-all-68">extends all</a>: <a href="#Project-Hierarchy-Extension">Project Hierarchy Extension</a></li>
<li><a href="#index-_0040code_007bexternal_007d-46"><code>external</code></a>: <a href="#Scenarios-in-Projects">Scenarios in Projects</a></li>
<li><a href="#index-_0040code_007bExternally_005fBuilt_007d-37"><code>Externally_Built</code></a>: <a href="#Project-Dependencies">Project Dependencies</a></li>
<li><a href="#index-Free-Documentation-License_002c-GNU-85">Free Documentation License, GNU</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li>
<li><a href="#index-_0040code_007bGlobal_005fCompilation_005fSwitches_007d-43"><code>Global_Compilation_Switches</code></a>: <a href="#Global-Attributes">Global Attributes</a></li>
<li><a href="#index-_0040code_007bGlobal_005fConfiguration_005fPragmas_007d-42"><code>Global_Configuration_Pragmas</code></a>: <a href="#Global-Attributes">Global Attributes</a></li>
<li><a href="#index-GNU-Free-Documentation-License-83">GNU Free Documentation License</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li>
<li><a href="#index-_0040code_007bGPR_005fPROJECT_005fPATH_007d-40"><code>GPR_PROJECT_PATH</code></a>: <a href="#Project-Dependencies">Project Dependencies</a></li>
<li><a href="#index-gprconfig_002c-external-values-82">gprconfig, external values</a>: <a href="#GPRconfig-external-values">GPRconfig external values</a></li>
<li><a href="#index-_0040code_007bImplementation_007d-34"><code>Implementation</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bImplementation_005fExceptions_007d-36"><code>Implementation_Exceptions</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bImplementation_005fSuffix_007d-29"><code>Implementation_Suffix</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bLanguages_007d-6"><code>Languages</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bLeading_005fLibrary_005fOptions_007d-56"><code>Leading_Library_Options</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fALI_005fDir_007d-52"><code>Library_ALI_Dir</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fAuto_005fInit_007d-60"><code>Library_Auto_Init</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fDir_007d-50"><code>Library_Dir</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fDir_007d-61"><code>Library_Dir</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fGCC_007d-54"><code>Library_GCC</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fInterface_007d-59"><code>Library_Interface</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fKind_007d-51"><code>Library_Kind</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fName_007d-49"><code>Library_Name</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fOptions_007d-55"><code>Library_Options</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLibrary_005fReference_005fSymbol_005fFile_007d-64"><code>Library_Reference_Symbol_File</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fSrc_005fDir_007d-62"><code>Library_Src_Dir</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fSymbol_005fFile_007d-65"><code>Library_Symbol_File</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fSymbol_005fPolicy_007d-63"><code>Library_Symbol_Policy</code></a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bLibrary_005fVersion_007d-53"><code>Library_Version</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-License_002c-GNU-Free-Documentation-84">License, GNU Free Documentation</a>: <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></li>
<li><a href="#index-_0040code_007bLinker_005fOptions_007d-57"><code>Linker_Options</code></a>: <a href="#Building-Libraries">Building Libraries</a></li>
<li><a href="#index-_0040code_007bLocal_005fConfiguration_005fPragmas_007d-20"><code>Local_Configuration_Pragmas</code></a>: <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a></li>
<li><a href="#index-_0040code_007bLocally_005fRemoved_005fFiles_007d-11"><code>Locally_Removed_Files</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bMain_007d-15"><code>Main</code></a>: <a href="#Main-Subprograms">Main Subprograms</a></li>
<li><a href="#index-Naming-scheme-7">Naming scheme</a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bObject_005fDir_007d-13"><code>Object_Dir</code></a>: <a href="#Object-and-Exec-Directory">Object and Exec Directory</a></li>
<li><a href="#index-portability-3">portability</a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-project-file-packages-17">project file packages</a>: <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a></li>
<li><a href="#index-project-path-38">project path</a>: <a href="#Project-Dependencies">Project Dependencies</a></li>
<li><a href="#index-project-qualifier-41">project qualifier</a>: <a href="#Sharing-Between-Projects">Sharing Between Projects</a></li>
<li><a href="#index-scenarios-44">scenarios</a>: <a href="#Scenarios-in-Projects">Scenarios in Projects</a></li>
<li><a href="#index-_0040code_007bSeparate_005fSuffix_007d-30"><code>Separate_Suffix</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-Source-directories-1">Source directories</a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-Source-directories_002c-recursive-4">Source directories, recursive</a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bSource_005fDirs_007d-2"><code>Source_Dirs</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bSource_005fFiles_007d-8"><code>Source_Files</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bSource_005fList_005fFile_007d-9"><code>Source_List_File</code></a>: <a href="#Source-Files-and-Directories">Source Files and Directories</a></li>
<li><a href="#index-_0040code_007bSpec_007d-31"><code>Spec</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bSpec_005fSuffix_007d-26"><code>Spec_Suffix</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bSpecification_007d-32"><code>Specification</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bSpecification_005fExceptions_007d-35"><code>Specification_Exceptions</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-_0040code_007bSpecification_005fSuffix_007d-27"><code>Specification_Suffix</code></a>: <a href="#Naming-Schemes">Naming Schemes</a></li>
<li><a href="#index-standalone-libraries-58">standalone libraries</a>: <a href="#Stand_002dalone-Library-Projects">Stand-alone Library Projects</a></li>
<li><a href="#index-_0040code_007bSwitches_007d-19"><code>Switches</code></a>: <a href="#Tools-Options-in-Project-Files">Tools Options in Project Files</a></li>
<li><a href="#index-typed-variable-47">typed variable</a>: <a href="#Scenarios-in-Projects">Scenarios in Projects</a></li>
</ul>
<div class="contents">
<h2>Table of Contents</h2>
<ul>
<li><a name="toc_Top" href="#Top">GPRBUILD User's Guide</a>
<li><a name="toc_GNAT-Project-Manager" href="#GNAT-Project-Manager">1 GNAT Project Manager</a>
<ul>
<li><a href="#Introduction">1.1 Introduction</a>
<li><a href="#Building-With-Projects">1.2 Building With Projects</a>
<ul>
<li><a href="#Source-Files-and-Directories">1.2.1 Source Files and Directories</a>
<li><a href="#Object-and-Exec-Directory">1.2.2 Object and Exec Directory</a>
<li><a href="#Main-Subprograms">1.2.3 Main Subprograms</a>
<li><a href="#Tools-Options-in-Project-Files">1.2.4 Tools Options in Project Files</a>
<li><a href="#Compiling-with-Project-Files">1.2.5 Compiling with Project Files</a>
<li><a href="#Executable-File-Names">1.2.6 Executable File Names</a>
<li><a href="#Avoid-Duplication-With-Variables">1.2.7 Avoid Duplication With Variables</a>
<li><a href="#Naming-Schemes">1.2.8 Naming Schemes</a>
</li></ul>
<li><a href="#Organizing-Projects-into-Subsystems">1.3 Organizing Projects into Subsystems</a>
<ul>
<li><a href="#Project-Dependencies">1.3.1 Project Dependencies</a>
<li><a href="#Cyclic-Project-Dependencies">1.3.2 Cyclic Project Dependencies</a>
<li><a href="#Sharing-Between-Projects">1.3.3 Sharing Between Projects</a>
<li><a href="#Global-Attributes">1.3.4 Global Attributes</a>
</li></ul>
<li><a href="#Scenarios-in-Projects">1.4 Scenarios in Projects</a>
<li><a href="#Library-Projects">1.5 Library Projects</a>
<ul>
<li><a href="#Building-Libraries">1.5.1 Building Libraries</a>
<li><a href="#Using-Library-Projects">1.5.2 Using Library Projects</a>
<li><a href="#Stand_002dalone-Library-Projects">1.5.3 Stand-alone Library Projects</a>
<li><a href="#Installing-a-library-with-project-files">1.5.4 Installing a library with project files</a>
</li></ul>
<li><a href="#Project-Extension">1.6 Project Extension</a>
<ul>
<li><a href="#Project-Hierarchy-Extension">1.6.1 Project Hierarchy Extension</a>
</li></ul>
<li><a href="#Project-File-Reference">1.7 Project File Reference</a>
<ul>
<li><a href="#Project-Declaration">1.7.1 Project Declaration</a>
<li><a href="#Qualified-Projects">1.7.2 Qualified Projects</a>
<li><a href="#Declarations">1.7.3 Declarations</a>
<li><a href="#Packages">1.7.4 Packages</a>
<li><a href="#Expressions">1.7.5 Expressions</a>
<li><a href="#External-Values">1.7.6 External Values</a>
<li><a href="#Typed-String-Declaration">1.7.7 Typed String Declaration</a>
<li><a href="#Variables">1.7.8 Variables</a>
<li><a href="#Attributes">1.7.9 Attributes</a>
<li><a href="#Case-Statements">1.7.10 Case Statements</a>
</li></ul>
</li></ul>
<li><a name="toc_Tools-Supporting-Project-Files" href="#Tools-Supporting-Project-Files">2 Tools Supporting Project Files</a>
<ul>
<li><a href="#gnatmake-and-Project-Files">2.1 gnatmake and Project Files</a>
<ul>
<li><a href="#Switches-Related-to-Project-Files">2.1.1 Switches Related to Project Files</a>
<li><a href="#Switches-and-Project-Files">2.1.2 Switches and Project Files</a>
<li><a href="#Specifying-Configuration-Pragmas">2.1.3 Specifying Configuration Pragmas</a>
<li><a href="#Project-Files-and-Main-Subprograms">2.1.4 Project Files and Main Subprograms</a>
<li><a href="#Library-Project-Files">2.1.5 Library Project Files</a>
</li></ul>
<li><a href="#The-GNAT-Driver-and-Project-Files">2.2 The GNAT Driver and Project Files</a>
<li><a href="#The-Development-Environments">2.3 The Development Environments</a>
<li><a href="#Cleaning-up-with-GPRclean">2.4 Cleaning up with GPRclean</a>
<ul>
<li><a href="#Switches-for-GPRclean">2.4.1 Switches for GPRclean</a>
</li></ul>
</li></ul>
<li><a name="toc_Gprbuild" href="#Gprbuild">3 Gprbuild</a>
<ul>
<li><a href="#Building-with-GPRbuild">3.1 Building with GPRbuild</a>
<ul>
<li><a href="#Command-Line">3.1.1 Command Line</a>
<li><a href="#Switches">3.1.2 Switches</a>
<li><a href="#Initialization">3.1.3 Initialization</a>
<li><a href="#Compilation-of-one-or-several-sources">3.1.4 Compilation of one or several sources</a>
<li><a href="#Compilation-Phase">3.1.5 Compilation Phase</a>
<li><a href="#Post_002dCompilation-Phase">3.1.6 Post-Compilation Phase</a>
<li><a href="#Linking-Phase">3.1.7 Linking Phase</a>
<li><a href="#Incompatibilities-with-gnatmake">3.1.8 Incompatibilities with gnatmake</a>
</li></ul>
<li><a href="#Configuring-with-GPRconfig">3.2 Configuring with GPRconfig</a>
<ul>
<li><a href="#Configuration">3.2.1 Configuration</a>
<li><a href="#Using-GPRconfig">3.2.2 Using GPRconfig</a>
<li><a href="#Using-GPRconfig">3.2.3 Description</a>
<li><a href="#Using-GPRconfig">3.2.4 Command line arguments</a>
<li><a href="#Using-GPRconfig">3.2.5 Interactive use</a>
<li><a href="#The-GPRconfig-knowledge-base">3.2.6 The GPRconfig knowledge base</a>
<ul>
<li><a href="#General-file-format">3.2.6.1 General file format</a>
<li><a href="#Compiler-description">3.2.6.2 Compiler description</a>
<li><a href="#GPRconfig-external-values">3.2.6.3 GPRconfig external values</a>
<li><a href="#GPRconfig-variable-substitution">3.2.6.4 GPRconfig variable substitution</a>
<li><a href="#Configurations">3.2.6.5 Configurations</a>
</li></ul>
</li></ul>
<li><a href="#Configuration-File-Reference">3.3 Configuration File Reference</a>
<ul>
<li><a href="#Project-Level-Attributes">3.3.1 Project Level Attributes</a>
<ul>
<li><a href="#General-Attributes">3.3.1.1 General Attributes</a>
<li><a href="#General-Library-Related-Attributes">3.3.1.2 General Library Related Attributes</a>
<li><a href="#Archive-Related-Attributes">3.3.1.3 Archive Related Attributes</a>
<li><a href="#Shared-Library-Related-Attributes">3.3.1.4 Shared Library Related Attributes</a>
</li></ul>
<li><a href="#Package-Naming">3.3.2 Package Naming</a>
<li><a href="#Package-Builder">3.3.3 Package Builder</a>
<li><a href="#Package-Compiler">3.3.4 Package Compiler</a>
<ul>
<li><a href="#General-Compilation-Attributes">3.3.4.1 General Compilation Attributes</a>
<li><a href="#Mapping-File-Related-Attributes">3.3.4.2 Mapping File Related Attributes</a>
<li><a href="#Config-File-Related-Attributes">3.3.4.3 Config File Related Attributes</a>
<li><a href="#Dependency-Related-Attributes">3.3.4.4 Dependency Related Attributes</a>
<li><a href="#Search-Path-Related-Attributes">3.3.4.5 Search Path Related Attributes</a>
</li></ul>
<li><a href="#Package-Binder">3.3.5 Package Binder</a>
<li><a href="#Package-Linker">3.3.6 Package Linker</a>
</li></ul>
</li></ul>
<li><a name="toc_GNU-Free-Documentation-License" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a>
<li><a name="toc_Index" href="#Index">Index</a>
</li></ul>
</div>
</body></html>
