GPRBUILD User's Guide
*********************

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

1 GNAT Project Manager
**********************



1.1 Introduction
================

This chapter describes GNAT's _Project Manager_, 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:

   * The directory or set of directories containing the source files,
     and/or the   names of the specific source files themselves

   * The directory in which the compiler's output   (`ALI' files,
     object files, tree files, etc.) is to be placed

   * The directory in which the executable programs are to be placed

   * Switch settings for any of the project-enabled tools;   you can
     apply these settings either globally or to individual compilation
     units.

   * The source files containing the main subprogram(s) to be built

   * The source programming language(s)

   * Source file naming conventions; you can specify these either
     globally or for   individual compilation units (*note Naming
     Schemes::).

   * Change any of the above settings depending on external values,
     thus enabling   the reuse of the projects in various scenarios
     (*note Scenarios in Projects::).

   * Automatically build libraries as part of the build process
     (*note Library Projects::).


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 (*note Project File
Reference::).

   Project files can be built hierarchically from other project files,
simplifying complex system integration and project reuse (*note
Organizing Projects into Subsystems::).

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

   * 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
     (*note Project Extension::).


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 `-P_projectfile_'
and `-X_vbl_=_value_').

   The Project Manager supports a wide range of development strategies,
for systems of all sizes.  Here are some typical practices that are
easily handled:

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

   * 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

all OS dependencies in a small number of implementation units.

   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.

   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.

1.2 Building With Projects
==========================

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.

   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.

Project file:
     A text file using an Ada-like syntax, generally using the `.gpr'
     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.

Project attribute:
     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. *Note Attributes::.

Package in a project:
     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 `Builder', `Compiler', `Binder',   and `Linker'.
     *Note Packages::.

Project variables:
     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.
      *Note External Values::, *Note Scenarios in Projects::, and *Note
     Variables::.

Source files and source directories:
     A source file is associated with a language through a naming
     convention. For   instance, `foo.c' is typically the name of a C
     source file;   `bar.ads' or `bar.1.ada' 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 *Note Naming Schemes::, 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 Source_Dirs
     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
     Source_Files or   Source_List_File attributes. Note that those
     last two attributes only   accept basenames with no directory
     information.

Object files and object directory:
     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   Object_Dir 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.
     /first exam


   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.

   The Ada source files `pack.ads', `pack.adb', and `proc.adb' are in
the `common/' directory. The file `proc.adb' contains an Ada main
subprogram `Proc' that `with's package `Pack'. We want to compile these
source files with the switch `-O2', and put the resulting files in the
directory `obj/'.

     common/
       pack.ads
       pack.adb
       proc.adb
     common/release/
       proc.ali, proc.o pack.ali, pack.o

Our project is to be called _Build_. The name of the file is the name
of the project (case-insensitive) with the `.gpr' extension, therefore
the project file name is `build.gpr'. This is not mandatory, but a
warning is issued when this convention is not followed.

   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:

     project Build is
     end Build;

1.2.1 Source Files and Directories
----------------------------------

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,...).

   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 `common' directory is the only source directory.

   There are several ways of defining source directories:

   * When the attribute Source_Dirs is not used, a project contains a
     single source directory which is the one where the project file
     itself   resides. In our example, if `build.gpr' is placed in the
     `common'   directory, the project has the needed implicit source
     directory.

   * The attribute Source_Dirs 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 `"/usr/local/common/"' on UNIX), or
     relative to the   directory in which the project file resides (for
     instance "." if   `build.gpr' is inside `common/', or "common" if
     it is one level up).    Each of the source directories must exist
     and be readable.

     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 "\".

   * The attribute Source_Dirs can automatically include subdirectories
      using a special syntax inspired by some UNIX shells. If any of
     the path in   the list ends with _"**"_, then that path and all
     its subdirectories   (recursively) are included in the list of
     source directories. For instance,   `**' and `./**' represent the
     complete directory tree rooted at ".".  

     When using that construct, it can sometimes be convenient to also
     use the   attribute Excluded_Source_Dirs, 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.

     It is often desirable to remove, from the source directories,
     directory   subtrees rooted at some subdirectories. An example is
     the subdirectories   created by a Version Control System such as
     Subversion that creates directory   subtrees rooted at
     subdirectories ".svn". To do that, attribute
     Ignore_Source_Sub_Dirs can be used. It specifies the list of simple
      file names for the roots of these undesirable directory subtrees.

              for Source_Dirs use ("./**");
              for Ignore_Source_Sub_Dirs use (".svn");


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

        build.gpr
        project Build is
           for Source_Dirs use ("common");  --  <<<<
        end Build;

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.

   * By default, the project manager  search for all source files of all
      specified languages in all the source directories.

     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.

     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 Languages attribute to
     a list of   strings, each of which is the name of a language.
     Tools like   `gnatmake' only know about Ada, while other tools like
      `gprbuild' know about many more languages such as C, C++, Fortran,
      assembly and others can be added dynamically.

     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
     (*note Naming Schemes::). The default is the   standard GNAT
     extension (`.adb' for bodies and `.ads' for   specs), which is
     what is used in our example, explaining why no naming scheme   is
     explicitly specified.    *Note Naming Schemes::.

   * `Source_Files'   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
     Source_Files 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.

   * 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   *note Organizing Projects into Subsystems::. To do this, the
     attribute   _Source_Files_ is set to the empty list, i.e. `()'.
     Alternatively,   _Source_Dirs_ can be set to the empty list, with
     the same   result.

   * `Source_List_File'   If there is a great number of files, it might
     be more convenient to use   the attribute Source_List_File, 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 _Source_Files_. Such a file can easily be created through
     external tools.

     A warning is issued if both attributes `Source_Files' and
     `Source_List_File' are given explicit values. In this case, the
     attribute `Source_Files' prevails.

   * `Excluded_Source_Files'   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 Excluded_Source_Files   (or its synonym
     Locally_Removed_Files).    Its value is the list of file names
     that should not be taken into account.    This attribute is often
     used when extending a project,   *Note Project Extension::. A
     similar attribute   Excluded_Source_List_File plays the same
     role but takes the name of file containing file names similarly to
      `Source_List_File'.


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 `Source_Dirs'. The project manager
automatically finds `pack.ads', `pack.adb' and `proc.adb' as source
files of the project.

   Note that by default a warning is issued when a project has no
sources attached to it and this is not explicitly indicated in the
project file.

1.2.2 Duplicate Sources in Projects
-----------------------------------

If the order of the source directories is known statically, that is if
`"/**"' is not used in the string list `Source_Dirs', 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 `"/**"' is used in the string list `Source_Dirs', it is an
error to have several files with the same source file name in the same
directory `"/**"' subtree, since there would be an ambiguity as to
which one should be used. However, two files with the same source file
name may exist 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.

   If there are two sources in different directories of the same `"/**"'
subtree, one way to resolve the problem is to exclude the directory of
the file that should not be used as a source of the project.

1.2.3 Object and Exec Directory
-------------------------------

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.

   The object directory is specified through the Object_Dir 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 `-p'
for `gnatmake' and `gprbuild').

   If the attribute `Object_Dir' is not specified, it defaults to the
project directory, that is the directory containing the project file.

   For our example, we can specify the object dir in this way:

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";   --  <<<<
        end Build;

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 (*note Organizing Projects into
Subsystems::) to see how each separate object directory can be
associated with one of the subsystem constituting the application.

   When the `linker' 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.

   This can be done through the `Exec_Dir' attribute, which, like
_Object_Dir_ 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
_Object_Dir_ nor _Exec_Dir_ was specified.

   In the case of the example, let's place the executable in the root
of the hierarchy, ie the same directory as `build.gpr'. Hence the
project file is now

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";  --   <<<<
        end Build;

1.2.4 Main Subprograms
----------------------

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 `main' function,
and in Ada the file that contains the main unit.

   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 `makefile', 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.

   The list of main files is specified via the Main 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 `GPS' will be
able to create extra menus to spawn or debug the corresponding
executables.

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";
           for Main use ("proc.adb");  --   <<<<
        end Build;

If this attribute is defined in the project, then spawning the builder
with a command such as

        gnatmake -Pbuild

automatically builds all the executables corresponding to the files
listed in the _Main_ attribute. It is possible to specify one or more
executables on the command line to build a subset of them.

1.2.5 Tools Options in Project Files
------------------------------------

We now have a project file that fully describes our environment, and
can be used to build the application with a simple `gnatmake' 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
fulfill that need if it was put in the `common' directory.

   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.

   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.

   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.

   A project file is subdivided into zero or more packages, 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
(*note Packages::), and the contents of packages are limited to a small
set of constructs and attributes (*note Attributes::).

   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.

        project Build is
           for Source_Dirs use ("common");
           for Object_Dir use "obj";
           for Exec_Dir use ".";
           for Main use ("proc.adb");

           package Builder is  --<<<  for gnatmake and gprbuild
           end Builder;

           package Compiler is --<<<  for the compiler
           end Compiler;

           package Binder is   --<<<  for the binder
           end Binder;

           package Linker is   --<<<  for the linker
           end Linker;
        end Build;

Let's first examine the compiler switches. As stated in the initial
description of the example, we want to compile all files with `-O2'.
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.

   Several attributes can be used to specify the switches:

Default_Switches:
     This is the first mention in this manual of an indexed attribute.
     When   this attribute is defined, one must supply an _index_ in
     the form of a   literal string.    In the case of
     _Default_Switches_, 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.

     In this example, we want to compile all Ada source files with the
     switch   `-O2', and the resulting project file is as follows
     (only the `Compiler' package is shown):

            package Compiler is
              for Default_Switches ("Ada") use ("-O2");
            end Compiler;

Switches:
     in some cases, we might want to use specific switches   for one or
     more files. For instance, compiling `proc.adb' might not be
     possible at high level of optimization because of a compiler issue.
      In such a case, the _Switches_   attribute (indexed on the file
     name) can be used and will override the   switches defined by
     _Default_Switches_. Our project file would   become:

            package Compiler is
               for Default_Switches ("Ada")
                   use ("-O2");
               for Switches ("proc.adb")
                   use ("-O0");
            end Compiler;

     `Switches' may take a pattern as an index, such as in:

            package Compiler is
              for Default_Switches ("Ada")
                  use ("-O2");
              for Switches ("pkg*")
                  use ("-O0");
            end Compiler;

     Sources `pkg.adb' and `pkg-child.adb' would be compiled with -O0,
     not -O2.

     `Switches' can also be given a language name as index instead of a
     file   name in which case it has the same semantics as
     _Default_Switches_.    However, indexes with wild cards are never
     valid for language name.

Local_Configuration_Pragmas:
     this attribute may specify the path   of a file containing
     configuration pragmas for use by the Ada compiler,   such as
     `pragma Restrictions (No_Tasking)'. These pragmas will be   used
     for all the sources of the project.


   The switches for the other tools are defined in a similar manner
through the Default_Switches and Switches attributes, respectively in
the _Builder_ package (for `gnatmake' and `gprbuild'), the _Binder_
package (binding Ada executables) and the _Linker_ package (for linking
executables).

1.2.6 Compiling with Project Files
----------------------------------

Now that our project files are written, let's build our executable.
Here is the command we would use from the command line:

        gnatmake -Pbuild

This will automatically build the executables specified through the
_Main_ 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.

   `gnatmake' only knows how to handle Ada files. By using `gprbuild'
as a builder, you could automatically manage C files the same way:
create the file `utils.c' in the `common' directory, set the attribute
_Languages_ to `"(Ada, C)"', and run

        gprbuild -Pbuild

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 `gprbuild' when building a
multi-language program:

     $ gprbuild -Pbuild
     gcc -c proc.adb
     gcc -c pack.adb
     gcc -c utils.c
     gprbind proc
     ...
     gcc proc.o -o proc

Notice the three steps described earlier:

   * The first three gcc commands correspond to the compilation phase.

   * The gprbind command corresponds to the post-compilation phase.

   * The last gcc command corresponds to the final link.


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 of the `gprbuild' command by
cut-and-pasting its output.  GPRbuild's option `-v' provides a much
more verbose output which includes, among other information, more
complete compilation, post-compilation and link commands.

1.2.7 Executable File Names
---------------------------

By default, the executable name corresponding to a main file is
computed from the main source file name. Through the attribute
Builder.Executable, it is possible to change this default.

   For instance, instead of building `proc' (or `proc.exe' on Windows),
we could configure our project file to build "proc1" (resp proc1.exe)
with the following addition:

        project Build is
           ...  --  same as before
           package Builder is
              for Executable ("proc.adb") use "proc1";
           end Builder
        end Build;

Attribute Executable_Suffix, when specified, may change the suffix of
the executable files, when no attribute `Executable' applies: its value
replace the platform-specific executable suffix.  The default
executable suffix is empty on UNIX and ".exe" on Windows.

   It is also possible to change the name of the produced executable by
using the command line switch `-o'. When several mains are defined in
the project, it is not possible to use the `-o' switch and the only way
to change the names of the executable is provided by Attributes
`Executable' and `Executable_Suffix'.

1.2.8 Avoid Duplication With Variables
--------------------------------------

To illustrate some other project capabilities, here is a slightly more
complex project using similar sources and a main program in C:

     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;

This project has many similarities with the previous one.  As expected,
its `Main' attribute now refers to a C source.  The attribute
_Exec_Dir_ is now omitted, thus the resulting executable will be put in
the directory `obj'.

   The most noticeable difference is the use of a variable in the
_Compiler_ 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 (*note Scenarios in
Projects::).

   In this example, we see how the file `main.c' can be compiled with
the switches used for all the other C files, plus `-g'.  In this
specific situation the use of a variable could have been replaced by a
reference to the `Default_Switches' attribute:

        for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");

Note the tick (_'_) used to refer to attributes defined in a package.

   Here is the output of the GPRbuild command using this project:

     $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

The default switches for Ada sources, the default switches for C
sources (in the compilation of `lib.c'), and the specific switches for
`main.c' have all been taken into account.

1.2.9 Naming Schemes
--------------------

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 Naming package of your project file.

   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.

   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.

   The following attributes can be defined in package `Naming':

Casing:
     Its value must be one of `"lowercase"' (the default if
     unspecified), `"uppercase"' or `"mixedcase"'. 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
     `my_unit.adb' (lowercase),   `MY_UNIT.ADB' (uppercase) or
     `My_Unit.adb' (mixedcase).    On Windows, file names are case
     insensitive, so this attribute is   irrelevant.

Dot_Replacement:
     This attribute specifies the string that should replace the "." in
     unit   names. Its default value is `"-"' so that a unit
     `Parent.Child' is expected to be found in the file
     `parent-child.adb'. The replacement string must satisfy the
     following   requirements to avoid ambiguities in the naming scheme:

        - It must not be empty

        - It cannot start or end with an alphanumeric character

        - It cannot be a single underscore

        - It cannot start with an underscore followed by an alphanumeric

        - It cannot contain a dot `'.'' except if the entire string
          is `"."'


Spec_Suffix and Specification_Suffix:
     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 the value of the attribute is the empty string, it indicates to
     the   Project Manager that the only specifications/header files
     for the language   are those specified with attributes `Spec' or
     `Specification_Exceptions'.

     If `Spec_Suffix ("Ada")' is not specified, then the default is
     `".ads"'.

     A non empty value must satisfy the following requirements:

        - It must include at least one dot

        - If `Dot_Replacement' is a single dot, then it cannot include
                more than one dot.

Body_Suffix and Implementation_Suffix:
     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.

     For each language of a project, one of these two attributes need
     to be   specified, either in the project itself or in the
     configuration project file.

     If the value of the attribute is the empty string, it indicates to
     the   Project Manager that the only source files for the language
     are those specified with attributes `Body' or
     `Implementation_Exceptions'.

     These attributes must satisfy the same requirements as
     `Spec_Suffix'.    In addition, they must be different from any of
     the values in   `Spec_Suffix'.    If `Body_Suffix ("Ada")' is not
     specified, then the default is   `".adb"'.

     If `Body_Suffix ("Ada")' and `Spec_Suffix ("Ada")' 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
     `Body_Suffix ("Ada")'   or a spec if the longest suffix is
     `Spec_Suffix ("Ada")'.

     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 `Makefile.in', a file
     called `Makefile.in' 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).

Separate_Suffix:
     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 `Body_Suffix ("Ada")'.

     The value of this attribute cannot be the empty string.

     Otherwise, the same rules apply as for the   `Body_Suffix'
     attribute. The only accepted index is "Ada".

Spec or Specification:
     This attribute `Spec' 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.

     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

             for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
             for Spec ("top") use "foo.a" at 1;
             for Spec ("foo") use "foo.a" at 2;

Body or Implementation:
     These attribute play the same role as _Spec_ for Ada bodies.

Specification_Exceptions and Implementation_Exceptions:
     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.


   For example, the following package models the Apex file naming rules:

       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;

1.2.10 Installation
-------------------

After building an application or a library it is often required to
install it into the development environment. For instance this step is
required if the library is to be used by another application.  The
`gprinstall' tool provides an easy way to install libraries, executable
or object code generated during the build. The Install package can be
used to change the default locations.

   The following attributes can be defined in package `Install':

Active
     Whether the project is to be installed, values are `true'
     (default) or `false'.

Artifacts
     An array attribute to declare a set of files not part of the
     sources to be installed. The array discriminant is the directory
     where the file is to be installed. If a relative directory then
     Prefix (see below) is prepended.

Prefix:
     Root directory for the installation.

Exec_Subdir
     Subdirectory of Prefix where executables are to be installed.
     Default is bin.

Lib_Subdir
     Subdirectory of Prefix where directory with the library or object
     files is to be installed. Default is lib.

Sources_Subdir
     Subdirectory of Prefix where directory with sources is to be
     installed. Default is include.

Project_Subdir
     Subdirectory of Prefix where the generated project file is to be
     installed. Default is share/gpr.

1.2.11 Distributed support
--------------------------

For large projects the compilation time can become a limitation in the
development cycle. To cope with that, GPRbuild supports distributed
compilation.

   The following attributes can be defined in package `Remote':

Root_Dir:
     Root directory of the project's sources. The default value is the
     project's directory.


1.3 Organizing Projects into Subsystems
=======================================

A subsystem 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.

   In this section, the previous example is being extended. Let's
assume some sources of our `Build' 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.

1.3.1 Project Dependencies
--------------------------

GtkAda comes with its own project file (appropriately called
`gtkada.gpr'), and we will assume we have already built a project
called `logging.gpr' for the logging module. With the information
provided so far in `build.gpr', 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.

   This is easily solved by adding the following with clauses at the
beginning of our project:

       with "gtkada.gpr";
       with "a/b/logging.gpr";
       project Build is
          ...  --  as before
       end Build;

When such a project is compiled, `gnatmake' will automatically check
the other projects and recompile their sources when needed. It will also
recompile the sources from `Build' 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
Externally_Built 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.

   The project's `with' clause has several effects. It provides source
visibility between projects during the compilation process. It also
guarantees that the necessary object files from `Logging' and `GtkAda'
are available when linking `Build'.

   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 `with'
clause identifies project files rather than packages.

   Each literal string after `with' is the path (absolute or relative)
to a project file. The `.gpr' extension is optional, although we
recommend adding it. If no extension is specified, and no project file
with the `.gpr' extension is found, then the file is searched for
exactly as written in the `with' clause, that is with no extension.

   As mentioned above, the path after a `with' has to be a literal
string, and you cannot use concatenation, or lookup the value of
external variables to change the directories from which a project is
loaded.  A solution if you need something like this is to use aggregate
projects (*note Aggregate Projects::).

   When a relative path or a base name is used, the project files are
searched relative to each of the directories in the project path. 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:

   * First, the file is searched relative to the directory that
     contains the   current project file.

   *   Then it is searched relative to all the directories specified in
     the   environment variables GPR_PROJECT_PATH_FILE,
     GPR_PROJECT_PATH and ADA_PROJECT_PATH (in that order) if they
     exist.    The value of GPR_PROJECT_PATH_FILE, when defined, is the
     path name of   a text file that contains project directory path
     names, one per line.    GPR_PROJECT_PATH and ADA_PROJECT_PATH,
     when defined, contain   project directory path names separated by
     directory separators.    ADA_PROJECT_PATH is used for
     compatibility, it is recommended to   use GPR_PROJECT_PATH_FILE or
     GPR_PROJECT_PATH.

   * Finally, it is searched relative to the default project
     directories.    Such directories depends on the tool used. The
     different locations searched   in the specified order are:

        * `<prefix>/<target>/lib/gnat'   (for `gnatmake' in all cases,
          and for `gprbuild' if option   `--target' is specified)

        * `<prefix>/<target>/share/gpr'   (for `gnatmake' in all cases,
          and for `gprbuild' if option   `--target' is specified)

        * `<prefix>/share/gpr/'   (for `gnatmake' and `gprbuild')

        * `<prefix>/lib/gnat/'   (for `gnatmake' and `gprbuild')

     In our example, `gtkada.gpr' is found in the predefined directory
     if   it was installed at the same root as GNAT.

Some tools also support extending the project path from the command
line, generally through the `-aP'. You can see the value of the project
path by using the `gnatls -v' command.

   Any symbolic link will be fully resolved in the directory of the
importing project file before the imported project file is examined.

   Any source file in the imported project can be used by the sources
of the importing project, transitively.  Thus if `A' imports `B', which
imports `C', the sources of `A' may depend on the sources of `C', even
if `A' does not import `C' explicitly. However, this is not
recommended, because if and when `B' ceases to import `C', some sources
in `A' will no longer compile. `gprbuild' has a switch
`--no-indirect-imports' that will report such indirect dependencies.

   One very important aspect of a project hierarchy is that a given
source can only belong to one project (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 `Source_Files' 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 between
source files and Ada units.

1.3.2 Cyclic Project Dependencies
---------------------------------

Cyclic dependencies are mostly forbidden: if `A' imports `B' (directly
or indirectly) then `B' is not allowed to import `A'. However, there
are cases when cyclic dependencies would be beneficial. For these
cases, another form of import between projects exists: the limited
with.  A project `A' that imports a project `B' with a straight `with'
may also be imported, directly or indirectly, by `B' through a `limited
with'.

   The difference between straight `with' and `limited with' is that
the name of a project imported with a `limited with' cannot be used in
the project importing it. In particular, its packages cannot be renamed
and its variables cannot be referred to.

     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;

1.3.3 Sharing Between Projects
------------------------------

When building an application, it is common to have similar needs in
several of the projects corresponding to the subsystems under
construction. For instance, they will all have the same compilation
switches.

   As seen before (*note Tools Options in Project Files::), setting
compilation switches for all sources of a subsystem is simple: it is
just a matter of adding a `Compiler.Default_Switches' 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.

   There are two main approaches to avoiding this duplication:

   * Since `build.gpr' imports `logging.gpr', 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:

            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;

     The solution used for `Compiler' 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.

     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:

            with "imported";
            project Main is
               Var1 := Imported.Var;
            end Main;

   * 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 `shared.gpr'.

            abstract project Shared is
               for Source_Files use ();   --  no sources
               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;

     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 `Shared' has no sources is so
     that it can be created   in any directory and we are sure it
     shares no sources with `Build'   or `Logging', which of course
     would be invalid.

     Note the additional use of the abstract qualifier in `shared.gpr'.
      This qualifier is optional, but helps convey the message that we
     do not   intend this project to have sources (*note Qualified
     Projects:: for   more qualifiers).

1.3.4 Global Attributes
-----------------------

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.

   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.

   Here is a list of commonly used global attributes:

Builder.Global_Configuration_Pragmas:
     This attribute points to a file that contains configuration pragmas
      to use when building executables. These pragmas apply for all
     executables built from this project hierarchy. As we have seen
     before,   additional pragmas can be specified on a per-project
     basis by setting the   `Compiler.Local_Configuration_Pragmas'
     attribute.

Builder.Global_Compilation_Switches:
     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
     `Compiler' package, which only apply to   the sources of the
     corresponding project. This attribute is indexed on   the name of
     the language.


   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.

1.4 Scenarios in Projects
=========================

Various aspects of the projects can be modified based on scenarios.
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).

   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
`-g' as compiler switches in debug mode and `-O2' 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.

   One naive approach is to create two different project files, say
`build_debug.gpr' and `build_release.gpr', 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.

   Instead, project files support the notion of scenarios controlled by
external values. Such values can come from several sources (in
decreasing order of priority):

Command line:
     When launching `gnatmake' or `gprbuild', the user can pass   extra
     `-X' switches to define the external value. In   our case, the
     command line might look like

                 gnatmake -Pbuild.gpr -Xmode=debug
             or  gnatmake -Pbuild.gpr -Xmode=release

Environment variables:
     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.

External function second parameter

   We now need to get that value in the project. The general form is to
use the predefined function external which returns the current value of
the external. For instance, we could setup the object directory to
point to either `obj/debug' or `obj/release' by changing our project to

        project Build is
            for Object_Dir use "obj/" & external ("mode", "debug");
            ... --  as before
        end Build;

The second parameter to `external' is optional, and is the default
value to use if "mode" is not set from the command line or the
environment.

   In order to set the switches according to the different scenarios,
other constructs have to be introduced such as typed variables and case
constructions.

   A typed variable 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 case construction and create conditional sections in the
project. The following example shows how this can be done:

        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;

The project has suddenly grown in size, but has become much more
flexible.  `Mode_Type' defines the only valid values for the `mode'
variable. If any other value is read from the environment, an error is
reported and the project is considered as invalid.

   The `Mode' variable is initialized with an external value defaulting
to `"debug"'. This default could be omitted and that would force the
user to define the value. Finally, we can use a case construction to
set the switches depending on the scenario the user has chosen.

   Most aspects of the projects can depend on scenarios. The notable
exception are project dependencies (`with' clauses), which may not
depend on a scenario.

   Scenarios work the same way with project hierarchies: you can either
duplicate a variable similar to `Mode' in each of the project (as long
as the first argument to `external' is always the same and the type is
the same), or simply set the variable in the `shared.gpr' project
(*note Sharing Between Projects::).

1.5 Library Projects
====================

So far, we have seen examples of projects that create executables.
However, it is also possible to create libraries instead. A library is
a specific type of subsystem where, for convenience, objects are
grouped together using system-specific means such as archives or
windows DLLs.

   Library projects provide a system- and language-independent way of
building both static and dynamic libraries. They also support the
concept of standalone libraries (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.

   There is a restriction on shared library projects: by default, they
are only allowed to import other shared library projects. They are not
allowed to import non library projects or static library projects.

   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 `ALI' files to the specified location).

1.5.1 Building Libraries
------------------------

Let's enhance our example and transform the `logging' subsystem into a
library.  In order to do so, a few changes need to be made to
`logging.gpr'.  A number of specific attributes needs to be defined: at
least `Library_Name' and `Library_Dir'; in addition, a number of other
attributes can be used to specify specific aspects of the library. For
readability, it is also recommended (although not mandatory), to use
the qualifier `library' in front of the `project' keyword.

Library_Name:
     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, except   for stand-alone libraries whose names must
     follow the syntax of Ada   identifiers; however, there may be
     system specific restrictions on the name.    In general, it is
     recommended to stick to alphanumeric characters (and   possibly
     single underscores) to help portability.

Library_Dir:
     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 `Object_Dir'
     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.


   Here is the new version of `logging.gpr' that makes it a library:

     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;

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:

Library_Kind:
     The value of this attribute must be either `"static"', `"dynamic"'
     or   `"relocatable"' (the latter is a synonym for dynamic). It
     indicates   which kind of library should be built (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 independently, 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   `.so'. Library project files, on the other hand, can
     be written in   a platform independent way so that the same
     project file can be used to build   a library on different
     operating systems.

     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 the various
     kinds of library to be built and their   corresponding object_dir.

Library_ALI_Dir:
     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   `Library_Dir' directory, but as for the
     executables where we have a   separate `Exec_Dir' attribute, you
     might want to put them in a separate   directory since there can
     be hundreds of them. The same restrictions as for   the
     `Library_Dir' attribute apply.

Library_Version:
     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 `"soname"'). If the library
     file name (built   from the `Library_Name') is different from the
     `Library_Version',   then the library file will be a symbolic link
     to the actual file whose name   will be `Library_Version'. This
     follows the usual installation schemes   for dynamic libraries on
     many Unix systems.

            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;

     After the compilation, the directory `lib' will contain both a
     `libdummy.so.1' library and a symbolic link to it called
     `libdummy.so'.

Library_GCC:
     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).

Library_Options:
     This attribute may be used to specify additional switches (last
     switches)   when linking a shared library.

Leading_Library_Options:
     This attribute, that is taken into account only by `gprbuild', may
     be   used to specified leading options (first switches) when
     linking a shared   library.

Linker.Linker_Options:
     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 `Linker.Switches'   defined in the main project.
     This is useful when a particular subsystem   depends on an
     external library: adding this dependency as a   `Linker_Options'
     in the project of the subsystem is more convenient than   adding
     it to all the `Linker.Switches' of the main projects that depend
     upon this subsystem.

1.5.2 Using Library Projects
----------------------------

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.

   It is also possible to build multi-language libraries. When using
`gprbuild' as a builder, multi-language library projects allow naturally
the creation of multi-language libraries . `gnatmake', does not 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.

   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:
`log1.ads', `log1.adb', `log2.ads' and `log2.adb'. If `log1.adb' has
been modified, then the library `liblogging' will be rebuilt when
compiling all the sources of `Build' only if `proc.ads', `pack.ads' or
`pack.adb' include a `"with Log1"'.

   To ensure that all the sources in the `Logging' library are up to
date, and that all the sources of `Build' are also up to date, the
following two commands needs to be used:

     gnatmake -Plogging.gpr
     gnatmake -Pbuild.gpr

All `ALI' files will also be copied from the object directory to the
library directory. To build executables, `gnatmake' will use the
library rather than the individual object files.

   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 `Externally_Built' attribute as
in the example below:

     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;

In the case of externally built libraries, the `Object_Dir' attribute
does not need to be specified because it will never be used.

   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 `Linker.Linker_Options' or
`Linker.Switches' 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 `Linker.Linker_Options' 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 `with' clause, which in turn will trigger the builder to find
the proper order of libraries in the final link command.

1.5.3 Stand-alone Library Projects
----------------------------------

A stand-alone library 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 & redeployment of complex systems when localized changes are
made.

   The name of a stand-alone library, specified with attribute
`Library_Name', must have the syntax of an Ada identifier.

   The most prominent 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,
usually Library_Interface, in addition to the two attributes that make
a project a Library Project (`Library_Name' and `Library_Dir'). This
third attribute may also be Interfaces. Library_Interface only works
when the interface is in Ada and takes a list of units as parameter.
Interfaces works for any supported language and takes a list of sources
as parameter.

Library_Interface:
     This attribute defines an explicit subset of the units of the
     project. Units   from projects importing this library project may
     only "with" units whose   sources are listed in the
     `Library_Interface'. Other sources are   considered implementation
     units.

               for Library_Dir use "lib";
               for Library_Name use "loggin";
               for Library_Interface use ("lib1", "lib2");  --  unit names

Interfaces
     This attribute defines an explicit subset of the source files of a
     project.    Sources from projects importing this project, can only
     depend on sources from   this subset. This attribute can be used
     on non library projects. It can also   be used as a replacement
     for attribute `Library_Interface', in which   case, units have to
     be replaced by source files. For multi-language library
     projects, it is the only way to make the project a Stand-Alone
     Library project   whose interface is not purely Ada.

Library_Standalone:
     This attribute defines the kind of standalone library to   build.
     Values are either `standard' (the default), `no' or
     `encapsulated'. When `standard' is used the code to elaborate and
     finalize the library is embedded, when `encapsulated' is used the
     library can furthermore only depends on static libraries (including
      the GNAT runtime). This attribute can be set to `no' to make it
     clear   that the library should not be standalone in which case the
      `Library_Interface' should not defined. Note that this attribute
     only applies to shared libraries, so `Library_Kind' must be set
     to `dynamic'.

               for Library_Dir use "lib";
               for Library_Name use "loggin";
               for Library_Kind use "dynamic";
               for Library_Interface use ("lib1", "lib2");  --  unit names
               for Library_Standalone use "encapsulated";


   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 initialization and
finalization procedures whose names depend on the library name
(`logginginit' and `loggingfinal' in the example). The object
corresponding to this package is included in the library.

Library_Auto_Init:
     A dynamic stand-alone Library is automatically initialized   if
     automatic initialization of Stand-alone Libraries is supported on
     the   platform and if attribute Library_Auto_Init 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.

     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.

Library_Dir:
     For a stand-alone library, only the `ALI' files of the interface
     units   (those that are listed in attribute `Library_Interface')
     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.

Binder.Default_Switches:
     When a stand-alone library is bound, the switches that are
     specified in   the attribute Binder.Default_Switches ("Ada") are
     used in the call to `gnatbind'.

Library_Src_Dir:
     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 `Inline' 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.

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

        - `"autonomous"' or `"default"': exported symbols are not
          controlled

        - `"compliant"': if attribute Library_Reference_Symbol_File
          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.

        - `"controlled"': the attribute Library_Reference_Symbol_File
          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.

        - `"restricted"': The attribute Library_Symbol_File 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.

        - `"direct"': The attribute Library_Symbol_File 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.


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

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

1.5.4 Installing a library with project files
---------------------------------------------

When using project files, a usable version of the library is created in
the directory specified by the `Library_Dir' attribute of the library
project file. Thus no further action is needed in order to make use of
the libraries that are built as part of the general application build.

   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 `externally_built'
attribute. *note Using Library Projects::

   Another option is to use `gprinstall' to install the library in a
different context than the build location. A project to use this
library is generated automatically by `gprinstall' which also copy, in
the install location, the minimum set of sources needed to use the
library.  *note Installation::

1.6 Project Extension
=====================

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 project extension
facility.

   Suppose for instance that our example `Build' project is built 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.

   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 _project extension_.  If one
project (the "child") _extends_ 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.

   A third example is that of using project extensions to provide
different versions of the same system. For instance, assume that a
`Common' 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 `Common'.  However, the other development branch still needs
evolution of `Common'.  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.

   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 `Build' from previous examples:

        project Work extends "../bld/build.gpr" is
        end Work;

The project after extends 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 (*note Project Dependencies::). 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 `Work' is placed). We can already compile that
project with

        gnatmake -Pwork

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 `Build', therefore all the object files in `Build' and
its dependencies are still valid and are reused automatically.

   Suppose we now want to supply an alternate version of `pack.adb' but
use the existing versions of `pack.ads' and `proc.adb'.  We can create
the new file Work's current directory  (likely by copying the one from
the `Build' 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.

   When we recompile, `gnatmake' will now automatically recompile this
file (thus creating `pack.o' in the current directory) and any file
that depends on it (thus creating `proc.o'). Finally, the executable is
also linked locally.

   Note that we could have obtained the desired behavior using project
import rather than project inheritance. A `base' project would contain
the sources for `pack.ads' and `proc.adb', and `Work' would import
`base' and add `pack.adb'. In this scenario,  `base' cannot contain the
original version of `pack.adb' 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.

   In a project file that extends another project, it is possible to
indicate that an inherited source is not part 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.

   For that purpose, the attribute Excluded_Source_Files is used.  Its
value is a list of file names.  It is also possible to use attribute
`Excluded_Source_List_File'.  Its value is the path of a text file
containing one file name per line.

     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;

All packages that are not declared in the extending project are
inherited from the project being extended, with their attributes, with
the exception of `Linker'Linker_Options' which is never inherited. In
particular, an extending project retains all the switches specified in
the project being extended.

   At the project level, if they are not declared in the extending
project, some attributes are inherited from the project being extended.
They are: `Languages', `Main' (for a root non library project) and
`Library_Name' (for a project extending a library project)

1.6.1 Project Hierarchy Extension
---------------------------------

One of the fundamental restrictions in project extension is the
following: A project is not allowed to import directly or indirectly at
the same time an extending project and one of its ancestors.

   By means of example, consider the following hierarchy of projects.

        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

If we want to locally extend the packages `A1' and `C1', we need to
create several extending projects:

        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


        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;

The extension `b_ext.gpr' is required, even though we are not overriding
any of the sources of `b.gpr' because otherwise `c_expr.gpr' would
import `b.gpr' which itself knows nothing about `a_ext.gpr'.

   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 implicit extension of entire hierarchy using
extends all relationship.

   When the project is extended using `extends all' 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.

   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.

   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.

   Thus, in our example we could create the following projects instead:

        a_ext.gpr, extends a.gpr and overrides A1
        c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1


        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;

When building project `c_ext.gpr', the entire modified project space is
considered for recompilation, including the sources of `b.gpr' that are
impacted by the changes in `A1' and `C1'.

1.7 Aggregate Projects
======================

Aggregate projects are an extension of the project paradigm, and are
meant to solve a few specific use cases that cannot be solved directly
using standard projects. This section will go over a few of these use
cases to try to explain what you can use aggregate projects for.

1.7.1 Building all main programs from a single project tree
-----------------------------------------------------------

Most often, an application is organized into modules and submodules,
which are very conveniently represented as a project tree or graph (the
root project A `with's the projects for each modules (say B and C),
which in turn `with' projects for submodules.

   Very often, modules will build their own executables (for testing
purposes for instance), or libraries (for easier reuse in various
contexts).

   However, if you build your project through `gnatmake' or `gprbuild',
using a syntax similar to

        gprbuild -PA.gpr

   this will only rebuild the main programs of project A, not those of
the imported projects B and C. Therefore you have to spawn several
`gnatmake' commands, one per project, to build all executables.  This
is a little inconvenient, but more importantly is inefficient because
`gnatmake' needs to do duplicate work to ensure that sources are
up-to-date, and cannot easily compile things in parallel when using the
-j switch.

   Also libraries are always rebuilt when building a project.

   You could therefore define an aggregate project Agg that groups A, B
and C. Then, when you build with

         gprbuild -PAgg.gpr

   this will build all mains from A, B and C.

        aggregate project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
        end Agg;

   If B or C do not define any main program (through their Main
attribute), all their sources are built. When you do not group them in
the aggregate project, only those sources that are needed by A will be
built.

   If you add a main to a project P not already explicitly referenced
in the aggregate project, you will need to add "p.gpr" in the list of
project files for the aggregate project, or the main will not be built
when building the aggregate project.

   Aggregate projects are only supported with `gprbuild', but not with
`gnatmake'.

1.7.2 Building a set of projects with a single command
------------------------------------------------------

One other case is when you have multiple applications and libraries
that are built independently from each other (but can be built in
parallel). For instance, you have a project tree rooted at A, and
another one (which might share some subprojects) rooted at B.

   Using only `gprbuild', you could do

       gprbuild -PA.gpr
       gprbuild -PB.gpr

   to build both. But again, `gprbuild' has to do some duplicate work
for those files that are shared between the two, and cannot truly build
things in parallel efficiently.

   If the two projects are really independent, share no sources other
than through a common subproject, and have no source files with a
common basename, you could create a project C that imports A and B. But
these restrictions are often too strong, and one has to build them
independently. An aggregate project does not have these limitations and
can aggregate two project trees that have common sources.

   This scenario is particularly useful in environments like VxWorks 653
where the applications running in the multiple partitions can be built
in parallel through a single `gprbuild' command. This also works nicely
with Annex E.

1.7.3 Define a build environment
--------------------------------

The environment variables at the time you launch `gprbuild' will
influence the view these tools have of the project (PATH to find the
compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the projects,
environment variables that are referenced in project files through the
"external" statement,...). Several command line switches can be used to
override those (-X or -aP), but on some systems and with some projects,
this might make the command line too long, and on all systems often
make it hard to read.

   An aggregate project can be used to set the environment for all
projects built through that aggregate. One of the nice aspects is that
you can put the aggregate project under configuration management, and
make sure all your user have a consistent environment when building.
The syntax looks like

        aggregate project Agg is
           for Project_Files use ("A.gpr", "B.gpr");
           for Project_Path use ("../dir1", "../dir1/dir2");
           for External ("BUILD") use "PRODUCTION";

           package Builder is
              for Switches ("Ada") use ("-q");
           end Builder;
        end Agg;

   One of the often requested features in projects is to be able to
reference external variables in `with' statements, as in

       with external("SETUP") & "path/prj.gpr";   --  ILLEGAL
       project MyProject is
          ...
       end MyProject;

   For various reasons, this isn't authorized. But using aggregate
projects provide an elegant solution. For instance, you could use a
project file like:

     aggregate project Agg is
         for Project_Path use (external("SETUP") & "path");
         for Project_Files use ("myproject.gpr");
     end Agg;

     with "prj.gpr";  --  searched on Agg'Project_Path
     project MyProject is
        ...
     end MyProject;

1.7.4 Performance improvements in builder
-----------------------------------------

The loading of aggregate projects is optimized in `gprbuild', so that
all files are searched for only once on the disk (thus reducing the
number of system calls and contributing to faster compilation times
especially on systems with sources on remote servers). As part of the
loading, `gprbuild' computes how and where a source file should be
compiled, and even if it is found several times in the aggregated
projects it will be compiled only once.

   Since there is no ambiguity as to which switches should be used,
files can be compiled in parallel (through the usual -j switch) and
this can be done while maximizing the use of CPUs (compared to launching
multiple `gprbuild' and `gnatmake' commands in parallel).

1.7.5 Syntax of aggregate projects
----------------------------------

An aggregate project follows the general syntax of project files. The
recommended extension is still `.gpr'. However, a special `aggregate'
qualifier must be put before the keyword `project'.

   An aggregate project cannot `with' any other project (standard or
aggregate), except an abstract project which can be used to share
attribute values. Also, aggregate projects cannot be extended or
imported though a `with' clause by any other project. Building other
aggregate projects from an aggregate project is done through the
Project_Files attribute (see below).

   An aggregate project does not have any source files directly (only
through other standard projects). Therefore a number of the standard
attributes and packages are forbidden in an aggregate project. Here is
the (non exhaustive) list:

   * Languages

   * Source_Files, Source_List_File and other attributes dealing with
     list of sources.

   * Source_Dirs, Exec_Dir and Object_Dir

   * Library_Dir, Library_Name and other library-related attributes

   * Main

   * Roots

   * Externally_Built

   * Inherit_Source_Path

   * Excluded_Source_Dirs

   * Locally_Removed_Files

   * Excluded_Source_Files

   * Excluded_Source_List_File

   * Interfaces

   The only package that is authorized (albeit optional) is Builder.
Other packages (in particular Compiler, Binder and Linker) are
forbidden. It is an error to have any of these (and such an error
prevents the proper loading of the aggregate project).

   Three new attributes have been created, which can only be used in the
context of aggregate projects:

Project_Files:
     This attribute is compulsory (or else we are not aggregating any
     project, and thus not doing anything). It specifies a list of
     `.gpr' files that are grouped in the aggregate. The list may be
     empty. The project files can be either other aggregate projects,
     or standard projects. When grouping standard projects, you can
     have both the root of a project tree (and you do not need to
     specify all its imported projects), and any project within the
     tree.

     Basically, the idea is to specify all those projects that have
     main programs you want to build and link, or libraries you want to
     build. You can even specify projects that do not use the Main
     attribute nor the `Library_*' attributes, and the result will be to
     build all their source files (not just the ones needed by other
     projects).

     The file can include paths (absolute or relative). Paths are
     relative to the location of the aggregate project file itself (if
     you use a base name, we expect to find the .gpr file in the same
     directory as the aggregate project file). The environment
     variables `ADA_PROJECT_PATH', `GPR_PROJECT_PATH' and
     `GPR_PROJECT_PATH_FILE' are not used to find the project files.
     The extension `.gpr' is mandatory, since this attribute contains
     file names, not project names.

     Paths can also include the `"*"' and `"**"' globbing patterns. The
     latter indicates that any subdirectory (recursively) will be
     searched for matching files. The latter (`"**"') can only occur at
     the last position in the directory part (ie `"a/**/*.gpr"' is
     supported, but not `"**/a/*.gpr"'). Starting the pattern with
     `"**"' is equivalent to starting with `"./**"'.

     For now, the pattern `"*"' is only allowed in the filename part,
     not in the directory part. This is mostly for efficiency reasons
     to limit the number of system calls that are needed.

     Here are a few valid examples:

              for Project_Files use ("a.gpr", "subdir/b.gpr");
              --  two specific projects relative to the directory of agg.gpr

              for Project_Files use ("**/*.gpr");
              --  all projects recursively

Project_Path:
     This attribute can be used to specify a list of directories in
     which to look for project files in `with' statements.

     When you specify a project in Project_Files say `"x/y/a.gpr"'),
     and this projects imports a project "b.gpr", only b.gpr is
     searched in the project path. a.gpr must be exactly at <dir of the
     aggregate>/x/y/a.gpr.

     This attribute, however, does not affect the search for the
     aggregated project files specified with `Project_Files'.

     Each aggregate project has its own (that is if agg1.gpr includes
     agg2.gpr, they can potentially both have a different project path).

     This project path is defined as the concatenation, in that order,
     of:

        * the current directory;

        * followed by the command line -aP switches;

        * then the directories from the GPR_PROJECT_PATH and
          ADA_PROJECT_PATH environment variables;

        * then the directories from the Project_Path attribute;

        * and finally the predefined directories.

     In the example above, agg2.gpr's project path is not influenced by
     the attribute agg1'Project_Path, nor is agg1 influenced by
     agg2'Project_Path.

     This can potentially lead to errors. In the following example:

               +---------------+                  +----------------+
               | Agg1.gpr      |-=--includes--=-->| Agg2.gpr       |
               |  'project_path|                  |  'project_path |
               |               |                  |                |
               +---------------+                  +----------------+
                     :                                   :
                     includes                        includes
                     :                                   :
                     v                                   v
                 +-------+                          +---------+
                 | P.gpr |<---------- withs --------|  Q.gpr  |
                 +-------+---------\                +---------+
                     |             |
                     withs         |
                     |             |
                     v             v
                 +-------+      +---------+
                 | R.gpr |      | R'.gpr  |
                 +-------+      +---------+

     When looking for p.gpr, both aggregates find the same physical
     file on the disk. However, it might happen that with their
     different project paths, both aggregate projects would in fact
     find a different r.gpr.  Since we have a common project (p.gpr)
     "with"ing two different r.gpr, this will be reported as an error
     by the builder.

     Directories are relative to the location of the aggregate project
     file.

     Here are a few valid examples:

             for Project_Path use ("/usr/local/gpr", "gpr/");

External:
     This attribute can be used to set the value of environment
     variables as retrieved through the `external' statement in
     projects. It does not affect the environment variables themselves
     (so for instance you cannot use it to change the value of your
     PATH as seen from the spawned compiler).

     This attribute affects the external values as seen in the rest of
     the aggreate projects, and in the aggregated projects.

     The exact value of external a variable comes from one of three
     sources (each level overrides the previous levels):

        * An External attribute in aggregate project, for instance
          `for External ("BUILD_MODE") use "DEBUG"';

        * Environment variables

          These override the value given by the attribute, so that
          users can override the value set in the (presumably shared
          with others in his team) aggregate project.

        * The -X command line switch to `gprbuild'

          This always takes precedence.


     This attribute is only taken into account in the main aggregate
     project (i.e. the one specified on the command line to `gprbuild'),
     and ignored in other aggregate projects. It is invalid in standard
     projects.  The goal is to have a consistent value in all projects
     that are built through the aggregate, which would not be the case
     in the diamond case: A groups the aggregate projects B and C,
     which both (either directly or indirectly) build the project P. If
     B and C could set different values for the environment variables,
     we would have two different views of P, which in particular might
     impact the list of source files in P.


1.7.6 package Builder in aggregate projects
-------------------------------------------

As we mentioned before, only the package Builder can be specified in an
aggregate project. In this package, only the following attributes are
valid:

Switches:
     This attribute gives the list of switches to use for `gprbuild'.
     Because no mains can be specified for aggregate projects, the only
     possible index for attribute `Switches' is `others'. All other
     indexes will be ignored.

     Example:

          for Switches (other) use ("-v", "-k", "-j8");

     These switches are only read from the main aggregate project (the
     one passed on the command line), and ignored in all other aggregate
     projects or projects.

     It can only contain builder switches, not compiler switches.

Global_Compilation_Switches
     This attribute gives the list of compiler switches for the various
     languages. For instance,

          for Global_Compilation_Switches ("Ada") use ("O1", "-g");
          for Global_Compilation_Switches ("C")   use ("-O2");

     This attribute is only taken into account in the aggregate project
     specified on the command line, not in other aggregate projects.

     In the projects grouped by that aggregate, the attribute
     Builder.Global_Compilation_Switches is also ignored. However, the
     attribute Compiler.Default_Switches will be taken into account (but
     that of the aggregate have higher priority). The attribute
     Compiler.Switches is also taken into account and can be used to
     override the switches for a specific file. As a result, it always
     has priority.

     The rules are meant to avoid ambiguities when compiling. For
     instance, aggregate project Agg groups the projects A and B, that
     both depend on C. Here is an extra for all of these projects:

                aggregate project Agg is
                    for Project_Files use ("a.gpr", "b.gpr");
                    package Builder is
                       for Global_Compilation_Switches ("Ada") use ("-O2");
                    end Builder;
                end Agg;

                with "c.gpr";
                project A is
                    package Builder is
                       for Global_Compilation_Switches ("Ada") use ("-O1");
                       --  ignored
                    end Builder;

                    package Compiler is
                       for Default_Switches ("Ada")
                           use ("-O1", "-g");
                       for Switches ("a_file1.adb")
                           use ("-O0");
                    end Compiler;
                end A;

                with "c.gpr";
                project B is
                    package Compiler is
                       for Default_Switches ("Ada") use ("-O0");
                    end Compiler;
                end B;

                project C is
                    package Compiler is
                       for Default_Switches ("Ada")
                           use ("-O3",
                                "-gnatn");
                       for Switches ("c_file1.adb")
                           use ("-O0", "-g");
                    end Compiler;
                end C;

     then the following switches are used:

        * all files from project A except a_file1.adb are compiled
          with "-O2 -g", since the aggregate project has priority.

        * the file a_file1.adb is compiled with       "-O0", since the
          Compiler.Switches has priority

        * all files from project B are compiled with       "-O2", since
          the aggregate project has priority

        * all files from C are compiled with "-O2 -gnatn", except for
             c_file1.adb which is compiled with "-O0 -g"

     Even though C is seen through two paths (through A and through B),
     the switches used by the compiler are unambiguous.

Global_Configuration_Pragmas
     This attribute can be used to specify a file containing
     configuration pragmas, to be passed to the Ada compiler.  Since we
     ignore the package Builder in other aggregate projects and
     projects, only those pragmas defined in the main aggregate project
     will be taken into account.

     Projects can locally add to those by using the
     `Compiler.Local_Configuration_Pragmas' attribute if they need.

Global_Config_File
     This attribute, indexed with a language name, can be used to
     specify a config when compiling sources of the language. For Ada,
     these files are configuration pragmas files.


   For projects that are built through the aggregate, the package
Builder is ignored, except for the Executable attribute which specifies
the name of the executables resulting from the link of the main
programs, and for the Executable_Suffix.

1.8 Aggregate Library Projects
==============================

Aggregate library projects make it possible to build a single library
using object files built using other standard or library projects. This
gives the flexibility to describe an application as having multiple
modules (a GUI, database access, ...) using different project files (so
possibly built with different compiler options) and yet create a single
library (static or relocatable) out of the corresponding object files.

1.8.1 Building aggregate library projects
-----------------------------------------

For example, we can define an aggregate project Agg that groups A, B
and C:

        aggregate library project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
           for Library_Name use ("agg");
           for Library_Dir use ("lagg");
        end Agg;

   Then, when you build with:

         gprbuild agg.gpr

   This will build all units from projects A, B and C and will create a
static library named `libagg.a' into the `lagg' directory. An aggregate
library project has the same set of restriction as a standard library
project.

   Note that a shared aggregate library project cannot aggregates a
static library project. In platforms where a compiler option is
required to create relocatable object files, a Builder package in the
aggregate library project may be used:

        aggregate library project Agg is
           for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
           for Library_Name use ("agg");
           for Library_Dir use ("lagg");
           for Library_Kind use "relocatable";

           package Builder is
              for Global_Compilation_Switches ("Ada") use ("-fPIC");
           end Builder;
        end Agg;

   With the above aggregate library Builder package, the `-fPIC' option
will be passed to the compiler when building any source code from
projects `a.gpr', `b.gpr' and `c.gpr'.

1.8.2 Syntax of aggregate library projects
------------------------------------------

An aggregate library project follows the general syntax of project
files. The recommended extension is still `.gpr'. However, a special
`aggregate library' qualifier must be put before the keyword `project'.

   An aggregate library project cannot `with' any other project
(standard or aggregate), except an abstract project which can be used
to share attribute values.

   An aggregate library project does not have any source files directly
(only through other standard projects). Therefore a number of the
standard attributes and packages are forbidden in an aggregate library
project. Here is the (non exhaustive) list:

   * Languages

   * Source_Files, Source_List_File and other attributes dealing with
     list of sources.

   * Source_Dirs, Exec_Dir and Object_Dir

   * Main

   * Roots

   * Externally_Built

   * Inherit_Source_Path

   * Excluded_Source_Dirs

   * Locally_Removed_Files

   * Excluded_Source_Files

   * Excluded_Source_List_File

   * Interfaces

   The only package that is authorized (albeit optional) is Builder.

   The Project_Files attribute (See *note Aggregate Projects::) is used
to described the aggregated projects whose object files have to be
included into the aggregate library. The environment variables
`ADA_PROJECT_PATH', `GPR_PROJECT_PATH' and `GPR_PROJECT_PATH_FILE' are
not used to find the project files.

1.9 Project File Reference
==========================

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.

1.9.1 Project Declaration
-------------------------

Project files have an Ada-like syntax. The minimal project file is:

     project Empty is
     end Empty;

The identifier `Empty' is the name of the project.  This project name
must be present after the reserved word `end' at the end of the project
file, followed by a semi-colon.

   Identifiers (i.e. 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").

     simple_name ::= identifier
     name        ::= simple_name { . simple_name }

Strings 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).

   Reserved words 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: `all, at, case, end, for, is,
limited, null, others, package, renames, type, use, when, with, extends,
external, project'.

   Comments in project files have the same syntax as in Ada, two
consecutive hyphens through the end of the line.

   A project may be an independent project, 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 with clauses, or by extending at most one other project. Both
types of dependency can be used in the same project.

   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.

   A given project name can appear only once in a context clause.

   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 limited with.

     with "other_project.gpr";
     project My_Project extends "extended.gpr" is
     end My_Project;

These dependencies form a directed graph, potentially cyclic when using
limited with. The subprogram reflecting the extends relations is a tree.

   A project's immediate sources 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.

   A project hierarchy can be created, where projects are children of
other projects. The name of such a child project must be `Parent.Child',
where `Parent' is the name of the parent project. In particular, this
makes all `with' clauses of the parent project automatically visible in
the child project.

     project        ::= context_clause project_declaration

     context_clause ::= {with_clause}
     with_clause    ::= with path_name { , path_name } ;
     path_name      ::= string_literal

     project_declaration ::= simple_project_declaration | project_extension
     simple_project_declaration ::=
       project <project_>name is
         {declarative_item}
       end <project_>simple_name;

1.9.2 Qualified Projects
------------------------

Before the reserved `project', there may be one or two qualifiers, that
is identifiers or reserved words, to qualify the project.  The current
list of qualifiers is:

abstract: qualifies a project with no sources. Such a
     project must either have no declaration of attributes
     `Source_Dirs',   `Source_Files', `Languages' or
     `Source_List_File', or one of   `Source_Dirs', `Source_Files', or
     `Languages' must be declared   as empty. If it extends another
     project, the project it extends must also be a   qualified
     abstract project.

standard: a standard project is a non library project with sources.
     This is the default (implicit) qualifier.

aggregate: a project whose sources are aggregated from other
     project files.

aggregate library: a library whose sources are aggregated
     from other project or library project files.

library: a library project must declare both attributes
     `Library_Name' and `Library_Dir'.

configuration: a configuration project cannot be in a project tree.
     It describes compilers and other tools to `gprbuild'.

1.9.3 Declarations
------------------

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.

     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 ::= null ;

An empty declaration is allowed anywhere a declaration is allowed. It
has no effect.

1.9.4 Packages
--------------

A project file may contain packages, that group attributes (typically
all the attributes that are used by one of the GNAT tools).

   A package with a given name may only appear once in a project file.
The following packages are currently supported in project files (See
*note Attributes:: for the list of attributes that each can contain).

`Binder'
     This package specifies characteristics useful when invoking the
     binder either   directly via the `gnat' driver or when using a
     builder such as   `gnatmake' or `gprbuild'. *Note Main
     Subprograms::.

`Builder'
     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 `Compiler', `Binder' or `Linker'
     packages,   but there are some general options that should be
     defined in this   package. *Note Main Subprograms::, and *note
     Executable File Names:: in   particular.

`Check'
     This package specifies the options used when calling the checking
     tool   `gnatcheck' via the `gnat' driver. Its attribute
     Default_Switches has the same semantics as for the package
     `Builder'. The first string should always be `-rules' to specify
     that all the other options belong to the `-rules' section of the
     parameters to `gnatcheck'.

`Clean'
     This package specifies the options used when cleaning a project or
     a project   tree using the tools `gnatclean' or `gprclean'.

`Compiler'
     This package specifies the compilation options used by the
     compiler for   each languages. *Note Tools Options in Project
     Files::.

`Cross_Reference'
     This package specifies the options used when calling the library
     tool   `gnatxref' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Eliminate'
     This package specifies the options used when calling the tool
     `gnatelim' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Finder'
     This package specifies the options used when calling the search
     tool   `gnatfind' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Gnatls'
     This package specifies the options to use when invoking `gnatls'
     via the `gnat' driver.

`Gnatstub'
     This package specifies the options used when calling the tool
     `gnatstub' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`IDE'
     This package specifies the options used when starting an integrated
      development environment, for instance `GPS' or `Gnatbench'.

`Install'
     This package specifies the options used when installing a project
     with `gprinstall'. *Note Installation::.

`Linker'
     This package specifies the options used by the linker.    *Note
     Main Subprograms::.

`Metrics'
     This package specifies the options used when calling the tool
     `gnatmetric' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Naming'
     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.    *Note Naming Schemes::.

`Pretty_Printer'
     This package specifies the options used when calling the
     formatting tool   `gnatpp' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Remote'
     This package is used by `gprbuild' to describe how distributed
     compilation should be done.

`Stack'
     This package specifies the options used when calling the tool
     `gnatstack' via the `gnat' driver. Its attributes
     Default_Switches and Switches have the same semantics as for the
     package `Builder'.

`Synchronize'
     This package specifies the options used when calling the tool
     `gnatsync' via the `gnat' driver.


   In its simplest form, a package may be empty:

     project Simple is
       package Builder is
       end Builder;
     end Simple;

A package may contain attribute declarations, variable declarations and
case constructions, as will be described below.

   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 `gnat'.

   A package can also be defined by a renaming declaration. 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 extending
declaration (see below).

   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.

   Finally, a package can also be defined by an extending declaration.
This is similar to a renaming declaration, except that it is possible
to add or override attributes.

     package_declaration ::= package_spec | package_renaming | package_extension
     package_spec ::=
       package <package_>simple_name is
         {simple_declarative_item}
       end package_identifier ;
     package_renaming ::==
       package <package_>simple_name renames <project_>simple_name.package_identifier ;
     package_extension ::==
       package <package_>simple_name extends <project_>simple_name.package_identifier is
         {simple_declarative_item}
       end package_identifier ;

1.9.5 Expressions
-----------------

An expression is any value that can be assigned to an attribute or a
variable. It is either a literal 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.

   A string value is one of:
   * A literal string, for instance `"comm/my_proj.gpr"'

   * The name of a variable that evaluates to a string (*note
     Variables::)

   * The name of an attribute that evaluates to a string (*note
     Attributes::)

   * An external reference (*note External Values::)

   * A concatenation of the above, as in `"prefix_" & Var'.


A list of strings is one of the following:

   * A parenthesized comma-separated list of zero or more string
     expressions, for   instance `(File_Name, "gnat.adc", File_Name &
     ".orig")' or `()'.

   * The name of a variable that evaluates to a list of strings

   * The name of an attribute that evaluates to a list of strings

   * A concatenation of a list of strings and a string (as defined
     above), for   instance `("A", "B") & "C"'

   * A concatenation of two lists of strings


The following is the grammar for expressions

     string_literal ::= "{string_element}"  --  Same as Ada
     string_expression ::= string_literal
         | variable_name
         | external_value
         | attribute_reference
         | ( string_expression { & string_expression } )
     string_list  ::= ( string_expression { , string_expression } )
        | string_variable_name
        | string_attribute_reference
     term ::= string_expression | string_list
     expression ::= term { & term }     --  Concatenation

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:

       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;

Here are some specific examples:

        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

1.9.6 External Values
---------------------

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

   There are two kinds of external values, one that returns a single
string, and one that returns a string list.

   The syntax of a single string external value is:

     external_value ::= external ( string_literal [, string_literal] )

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.

   Typically, the external value will either exist in the environment
variables or be specified on the command line through the
`-X_vbl_=_value_' switch. If both are specified, then the command line
value is used, so that a user can more easily override the value.

   The function `external' always returns a string. It is an error if
the value was not found in the environment and no default was specified
in the call to `external'.

   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.

   Most of the time, this construct is used to initialize typed
variables, which are then used in case statements to control the value
assigned to attributes in various scenarios. Thus such variables are
often called scenario variables.

   The syntax for a string list external value is:

     external_value ::= external_as_list ( string_literal , string_literal )

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 is the separator between each component of the string
list.

   If the external value does not exist in the environment or on the
command line, the result is an empty list. This is also the case, if
the separator is an empty string or if the external value is only one
separator.

   Any separator at the beginning or at the end of the external value is
discarded. Then, if there is no separator in the external value, the
result is a string list with only one string. Otherwise, any string
between the beginning and the first separator, between two consecutive
separators and between the last separator and the end are components of
the string list.

        external_as_list ("SWITCHES", ",")

If the external value is "-O2,-g", the result is ("-O2", "-g").

   If the external value is ",-O2,-g,", the result is also ("-O2",
"-g").

   if the external value is "-gnatv", the result is ("-gnatv").

   If the external value is ",,", the result is ("").

   If the external value is ",", the result is (), the empty string
list.

1.9.7 Typed String Declaration
------------------------------

A type declaration 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.

     typed_string_declaration ::=
       type <typed_string_>_simple_name is ( string_literal {, string_literal} );

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:

        type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");

Variables of a string type are called typed variables; all other
variables are called untyped variables. Typed variables are
particularly useful in `case' constructions, to support conditional
attribute declarations. (*note Case Constructions::).

   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.

1.9.8 Variables
---------------

Variables 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 ("").

   A typed variable can be used as part of a case expression to compute
the value, but it can only be declared once in the project file, so
that all case constructions 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.

   An untyped 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.

   A variable may be declared at the project file level, or within a
package.

     typed_variable_declaration ::=
       <typed_variable_>simple_name : <typed_string_>name := string_expression;
     variable_declaration ::= <variable_>simple_name := expression;

Here are some examples of variable declarations:

        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");

A variable reference may take several forms:

   * The simple variable name, for a variable in the current package
     (if any)   or in the current project

   * An expanded name, whose prefix is a context name.


A context may be one of the following:

   * The name of an existing package in the current project

   * The name of an imported project of the current project

   * The name of an ancestor project (i.e., a project extended by the
     current   project, either directly or indirectly)

   * An expanded name whose prefix is an imported/parent project name,
     and   whose selector is a package name in that project.

1.9.9 Case Constructions
------------------------

A case 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.

   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 `others' choice must appear last in the list of alternatives.

   The syntax of a `case' construction is based on the Ada case
statement (although the `null' statement for empty alternatives is
optional).

   The case expression must be a typed string variable, whose value is
often given by an external reference (*note External Values::).

   Each alternative starts with the reserved word `when', either a list
of literal strings separated by the `"|"' character or the reserved word
`others', and the `"=>"' token.  Each literal string must belong to the
string type that is the type of the case variable.  After each `=>',
there are zero or more statements.  The only statements allowed in a
case construction are other case constructions, 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.

     case_statement ::=
       case <typed_variable_>name is {case_item} end case ;

     case_item ::=
       when discrete_choice_list =>
         {case_statement
           | attribute_declaration
           | variable_declaration
           | empty_declaration}

     discrete_choice_list ::= string_literal {| string_literal} | others

Here is a typical example:

     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;

1.9.10 Attributes
-----------------

A project (and its packages) may have attributes that define the
project's properties.  Some attributes have values that are strings;
others have values that are string lists.

     attribute_declaration ::=
        simple_attribute_declaration | indexed_attribute_declaration
     simple_attribute_declaration ::= for attribute_designator use expression ;
     indexed_attribute_declaration ::=
       for <indexed_attribute_>simple_name ( string_literal) use expression ;
     attribute_designator ::=
       <simple_attribute_>simple_name
       | <indexed_attribute_>simple_name ( string_literal )

There are two categories of attributes: simple attributes and indexed
attributes.  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.

   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.

   Here are some examples of attribute declarations:

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

Attributes references may 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.

     attribute_reference ::= attribute_prefix ' <simple_attribute>_simple_name [ (string_literal) ]
     attribute_prefix ::= project
       | <project_>simple_name
       | package_identifier
       | <project_>simple_name . package_identifier

Examples are:

       project'Object_Dir
       Naming'Dot_Replacement
       Imported_Project'Source_Dirs
       Imported_Project.Naming'Casing
       Builder'Default_Switches ("Ada")

The prefix of an attribute may be:

   * `project' for an attribute of the current project

   * The name of an existing package of the current project

   * The name of an imported project

   * The name of a parent project that is extended by the current
     project

   * An expanded name whose prefix is imported/parent project name,
     and whose selector is a package name


In the following sections, all predefined attributes are succinctly
described, first the project level attributes, that is those attributes
that are not in a package, then the attributes in the different
packages.

   It is possible for different tools to create dynamically new
packages with attributes, or new attribute in predefined packages.
These attributes are not documented here.

   The attributes under Configuration headings are usually found only in
configuration project files.

   The characteristics of each attribute are indicated as follows:

   * Type of value

     The value of an attribute may be a single string, indicated by the
     word "single", or a string list, indicated by the word "list".

   * Read-only

     When the attribute is read-only, that is when it is not allowed to
     declare the attribute, this is indicated by the words "read-only".

   * Optional index

     If it is allowed in the value of the attribute (both single and
     list) to have an optional index, this is indicated by the words
     "optional index".

   * Indexed attribute

     When an it is an indexed attribute, this is indicated by the word
     "indexed".

   * Case-sensitivity of the index

     For an indexed attribute, if the index is case-insensitive, this
     is indicated by the words "case-insensitive index".

   * File name index

     For an indexed attribute, when the index is a file name, this is
     indicated by the words "file name index". The index may or may not
     be case-sensitive, depending on the platform.

   * others allowed in index

     For an indexed attribute, if it is allowed to use others as the
     index, this is indicated by the words "others allowed".

     When others is used as the index of an indexed attribute, the
     value of the attribute indexed by others is used when no other
     index would apply.


1.9.10.1 Project Level Attributes
.................................


   * General

        * Name: single, read-only

          The name of the project.

        * Project_Dir: single, read-only

          The path name of the project directory.

        * Main: list, optional index

          The list of main sources for the executables.

        * Languages: list

          The list of languages of the sources of the project.

        * Roots: list, indexed, file name index

          The index is the file name of an executable source. Indicates
          the list of units from the main project that need to be bound
          and linked with their closures with the executable. The index
          is either a file name, a language name or "*".  The roots for
          an executable source are those in Roots with an index that is
          the executable source file name, if declared. Otherwise, they
          are those in Roots with an index that is the language name of
          the executable source, if present. Otherwise, they are those
          in Roots ("*"), if declared. If none of these three
          possibilities are declared, then there are no roots for the
          executable source.

        * Externally_Built: single

          Indicates if the project is externally built.  Only
          case-insensitive values allowed are "true" and "false", the
          default.


   * Directories

        * Object_Dir: single

          Indicates the object directory for the project.

        * Exec_Dir: single

          Indicates the exec directory for the project, that is the
          directory where the executables are.

        * Source_Dirs: list

          The list of source directories of the project.

        * Inherit_Source_Path: list, indexed, case-insensitive index

          Index is a language name. Value is a list of language names.
          Indicates that in the source search path of the index
          language the source directories of the languages in the list
          should be included.

          Example:

          for Inherit_Source_Path ("C++") use ("C");

        * Exclude_Source_Dirs: list

          The list of directories that are included in Source_Dirs but
          are not source directories of the project.

        * Ignore_Source_Sub_Dirs: list

          Value is a list of simple names for subdirectories that are
          removed from the list of source directories, including theur
          subdirectories.


   * Source Files

        * Source_Files: list

          Value is a list of source file simple names.

        * Locally_Removed_Files: list

          Obsolescent. Equivalent to Excluded_Source_Files.

        * Excluded_Source_Files: list

          Value is a list of simple file names that are not sources of
          the project.  Allows to remove sources that are inherited or
          found in the source directories and that match the naming
          scheme.

        * Source_List_File: single

          Value is a text file name that contains a list of source file
          simple names, one on each line.

        * Excluded_Source_List_File: single

          Value is a text file name that contains a list of file simple
          names that are not sources of the project.

        * Interfaces: list

          Value is a list of file names that constitutes the interfaces
          of the project.


   * Aggregate Projects

        * Project_Files: list

          Value is the list of aggregated projects.

        * Project_Path: list

          Value is a list of directories that are added to the project
          search path when looking for the aggregated projects.

        * External: single, indexed

          Index is the name of an external reference. Value is the
          value of the external reference to be used when parsing the
          aggregated projects.


   * Libraries

        * Library_Dir: single

          Value is the name of the library directory. This attribute
          needs to be declared for each library project.

        * Library_Name: single

          Value is the name of the library. This attribute needs to be
          declared or inherited for each library project.

        * Library_Kind: single

          Specifies the kind of library: static library (archive) or
          shared library.  Case-insensitive values must be one of
          "static" for archives (the default) or "dynamic" or
          "relocatable" for shared libraries.

        * Library_Version: single

          Value is the name of the library file.

        * Library_Interface: list

          Value is the list of unit names that constitutes the
          interfaces of a Stand-Alone Library project.

        * Library_Standalone: single

          Specifies if a Stand-Alone Library (SAL) is encapsulated or
          not.  Only authorized case-insensitive values are "standard"
          for non encapsulated SALs, "encapsulated" for encapsulated
          SALs or "no" for non SAL library project.

        * Library_Encapsulated_Options: list

          Value is a list of options that need to be used when linking
          an encapsulated Stand-Alone Library.

        * Library_Encapsulated_Supported: single

          Indicates if encapsulated Stand-Alone Libraries are
          supported. Only authorized case-insensitive values are "true"
          and "false" (the default).

        * Library_Auto_Init: single

          Indicates if a Stand-Alone Library is auto-initialized. Only
          authorized case-insentive values are "true" and "false".

        * Leading_Library_Options: list

          Value is a list of options that are to be used at the
          beginning of the command line when linking a shared library.

        * Library_Options: list

          Value is a list of options that are to be used when linking a
          shared library.

        * Library_Rpath_Options: list, indexed, case-insensitive index

          Index is a language name. Value is a list of options for an
          invocation of the compiler of the language. This invocation
          is done for a shared library project with sources of the
          language. The output of the invocation is the path name of a
          shared library file. The directory name is to be put in the
          run path option switch when linking the shared library for
          the project.

        * Library_Src_Dir: single

          Value is the name of the directory where copies of the
          sources of the interfaces of a Stand-Alone Library are to be
          copied.

        * Library_ALI_Dir: single

          Value is the name of the directory where the ALI files of the
          interfaces of a Stand-Alone Library are to be copied. When
          this attribute is not declared, the directory is the library
          directory.

        * Library_gcc: single

          Obsolescent attribute. Specify the linker driver used to link
          a shared library.  Use instead attribute Linker'Driver.

        * Library_Symbol_File: single

          Value is the name of the library symbol file.

        * Library_Symbol_Policy: single

          Indicates the symbol policy kind. Only authorized
          case-insensitive values are "autonomous", "default",
          "compliant", "controlled" or "direct".

        * Library_Reference_Symbol_File: single

          Value is the name of the reference symbol file.


   * Configuration - General

        * Default_Language: single

          Value is the case-insensitive name of the language of a
          project when attribute Languages is not specified.

        * Run_Path_Option: list

          Value is the list of switches to be used when specifying the
          run path option in an executable.

        * Run_Path_Origin: single

          Value is the the string that may replace the path name of the
          executable directory in the run path options.

        * Separate_Run_Path_Options: single

          Indicates if there may be or not several run path options
          specified when linking an executable. Only authorized
          case-insensitive b=values are "true" or "false" (the default).

        * Toolchain_Version: single, indexed, case-insensitive index

          Index is a language name. Specify the version of a toolchain
          for a language.

        * Toolchain_Description: single, indexed, case-insensitive index

          Obsolescent. No longer used.

        * Object_Generated: single, indexed, case-insensitive index

          Index is a language name. Indicates if invoking the compiler
          for a language produces an object file. Only authorized
          case-insensitive values are "false" and "true" (the default).

        * Objects_Linked: single, indexed, case-insensitive index

          Index is a language name. Indicates if the object files
          created by the compiler for a language need to be linked in
          the executable. Only authorized case-insensitive values are
          "false" and "true" (the default).

        * Target: single

          Value is the name of the target platform.


   * Configuration - Libraries

        * Library_Builder: single

          Value is the path name of the application that is to be used
          to build libraries. Usually the path name of "gprlib".

        * Library_Support: single

          Indicates the level of support of libraries. Only authorized
          case-insensitive values are "static_only", "full" or "none"
          (the default).


   * Configuration - Archives

        * Archive_Builder: list

          Value is the name of the application to be used to create a
          static library (archive), followed by the options to be used.

        * Archive_Builder_Append_Option: list

          Value is the list of options to be used when invoking the
          archive builder to add project files into an archive.

        * Archive_Indexer: list

          Value is the name of the archive indexer, followed by the
          required options.

        * Archive_Suffix: single

          Value is the extension of archives. When not declared, the
          extension is ".a".

        * Library_Partial_Linker: list

          Value is the name of the partial linker executable, followed
          by the required options.


   * Configuration - Shared Libraries

        * Shared_Library_Prefix: single

          Value is the prefix in the name of shared library files. When
          not declared, the prefix is "lib".

        * Shared_Library_Suffix: single

          Value is the the extension of the name of shared library
          files. When not declared, the extension is ".so".

        * Symbolic_Link_Supported: single

          Indicates if symbolic links are supported on the platform.
          Only authorized case-insensitive values are "true" and
          "false" (the default).

        * Library_Major_Minor_Id_Supported: single

          Indicates if major and minor ids for shared library names are
          supported on the platform. Only authorized case-insensitive
          values are "true" and "false" (the default).

        * Library_Auto_Init_Supported: single

          Indicates if auto-initialization of Stand-Alone Libraries is
          supported. Only authorized case-insensitive values are "true"
          and "false" (the default).

        * Shared_Library_Minimum_Switches: list

          Value is the list of required switches when linking a shared
          library.

        * Library_Version_Switches: list

          Value is the list of switches to specify a internal name for
          a shared library.

        * Library_Install_Name_Option: single

          Value is the name of the option that needs to be used,
          concatenated with the path name of the library file, when
          linking a shared library.

        * Runtime_Library_Dir: single, indexed, case-insensitive index

          Index is a language name. Value is the path name of the
          directory where the runtime libraries are located.

        * Runtime_Source_Dir: single, indexed, case-insensitive index

          Index is a language name. Value is the path name of the
          directory where the sources of runtime libraries are located.



1.9.10.2 Package Binder Attributes
..................................

   * General

        * Default_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used when binding code of the language, if there is no
          applicable attribute Switches.

        * Switches: list, optional index, indexed,
          case-insensitive index, others allowed

          Index is either a language name or a source file name. Value
          is the list of switches to be used when binding code. Index
          is either the source file name of the executable to be bound
          or the language name of the code to be bound.


   * Configuration - Binding

        * Driver: single, indexed, case-insensitive index

          Index is a language name. Value is the name of the
          application to be used when binding code of the language.

        * Required_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of the required
          switches to be used when binding code of the language.

        * Prefix: single, indexed, case-insensitive index

          Index is a language name. Value is a prefix to be used for
          the binder exchange file name for the language. Used to have
          different binder exchange file names when binding different
          languages.

        * Objects_Path: single,indexed, case-insensitive index

          Index is a language name. Value is the name of the
          environment variable that contains the path for the object
          directories.

        * Object_Path_File: single,indexed, case-insensitive index

          Index is a language name. Value is the name of the
          environment variable. The value of the environment variable
          is the path name of a text file that contains the list of
          object directories.



1.9.10.3 Package Builder Attributes
...................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is the list of builder switches to
     be used when building an executable of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is either a language name or a source file name. Value is
     the list of builder switches to be used when building an
     executable. Index is either the source file name of the executable
     to be built or its language name.

   * Global_Compilation_Switches: list, optional index, indexed,
                                    case-insensitive index

     Index is either a language name or a source file name. Value is
     the list of compilation switches to be used when building an
     executable. Index is either the source file name of the executable
     to be built or its language name.

   * Executable: single, indexed, case-insensitive index

     Index is an executable source file name. Value is the simple file
     name of the executable to be built.

   * Executable_Suffix: single

     Value is the extension of the file names of executable. When not
     specified, the extension is the default extension of executables
     on the platform.

   * Global_Configuration_Pragmas: single

     Value is the file name of a configuration pragmas file that is
     specified to the Ada compiler when compiling any Ada source in the
     project tree.

   * Global_Config_File: single, indexed, case-insensitive index

     Index is a language name. Value is the file name of a
     configuration file that is specified to the compiler when
     compiling any source of the language in the project tree.


1.9.10.4 Package Check Attributes
.................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatcheck' for a source of the language, if there
     is no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatcheck' for the source.


1.9.10.5 Package Clean Attributes
.................................

   * Switches: list

     Value is a list of switches to be used by the cleaning application.

   * Source_Artifact_Extensions: list, indexed, case-insensitive index

     Index is a language names. Value is the list of extensions for
     file names derived from object file names that need to be cleaned
     in the object directory of the project.

   * Object_Artifact_Extensions: list, indexed, case-insensitive index

     Index is a language names. Value is the list of extensions for
     file names derived from source file names that need to be cleaned
     in the object directory of the project.

   * Artifacts_In_Object_Dir: single

     Value is a list of file names expressed as regular expressions
     that are to be deleted by gprclean in the object directory of the
     project.

   * Artifacts_In_Exec_Dir: single

     Value is list of file names expressed as regular expressions that
     are to be deleted by gprclean in the exec directory of the main
     project.


1.9.10.6 Package Compiler Attributes
....................................

   * General

        * Default_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is a list of switches to be
          used when invoking the compiler for the language for a source
          of the project, if there is no applicable attribute Switches.

        * Switches: list, optional index, indexed, case-insensitive
          index,                     others allowed

          Index is a source file name or a language name. Value is the
          list of switches to be used when invoking the compiler for
          the source or for its language.

        * Local_Configuration_Pragmas: single

          Value is the file name of a configuration pragmas file that
          is specified to the Ada compiler when compiling any Ada
          source in the project.

        * Local_Config_File: single, indexed, case-insensitive index

          Index is a language name. Value is the file name of a
          configuration file that is specified to the compiler when
          compiling any source of the language in the project.


   * Configuration - Compiling

        * Driver: single, indexed, case-insensitive index

          Index is a language name. Value is the name of the executable
          for the compiler of the language.

        * Language_Kind: single, indexed, case-insensitive index

          Index is a language name. Indicates the kind of the language,
          either file based or unit based. Only authorized
          case-insensitive values are "unit_based" and "file_based"
          (the default).

        * Dependency_Kind: single, indexed, case-insensitive index

          Index is a language name. Indicates how the dependencies are
          handled for the language. Only authorized case-insensitive
          values are "makefile", "ali_file", "ali_closure" or "none"
          (the default).

        * Required_Switches: list, indexed, case-insensitive index

          Equivalent to attribute Leading_Required_Switches.

        * Leading_Required_Switches: list, indexed, case-insensitive
          index

          Index is a language name. Value is the list of the minimum
          switches to be used at the beginning of the command line when
          invoking the compiler for the language.

        * Trailing_Required_Switches: list, indexed, case-insensitive
          index

          Index is a language name. Value is the list of the minimum
          switches to be used at the end of the command line when
          invoking the compiler for the language.

        * PIC_Option: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used when compiling a source of the language when the project
          is a shared library project.

        * Path_Syntax: single, indexed, case-insensitive index

          Index is a language name. Value is the kind of path syntax to
          be used when invoking the compiler for the language. Only
          authorized case-insensitive values are "canonical" and "host"
          (the default).

        * Source_File_Switches: single, indexed, case-insensitive index

          Index is a language name. Value is a list of switches to be
          used just before the path name of the source to compile when
          invoking the compiler for a source of the language.

        * Object_File_Suffix: single, indexed, case-insensitive index

          Index is a language name. Value is the extension of the
          object files created by the compiler of the language. When
          not specified, the extension is the default one for the
          platform.

        * Object_File_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used by the compiler of the language to specify the path name
          of the object file. When not specified, the switch used is
          "-o".

        * Multi_Unit_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used to compile a unit in a multi unit source of the
          language. The index of the unit in the source is concatenated
          with the last switches in the list.

        * Multi_Unit_Object_Separator: single, indexed,
          case-insensitive index

          Index is a language name. Value is the string to be used in
          the object file name before the index of the unit, when
          compiling a unit in a multi unit source of the language.


   * Configuration - Mapping Files

        * Mapping_File_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used to specify a mapping file when invoking the compiler for
          a source of the language.

        * Mapping_Spec_Suffix: single, indexed, case-insensitive index

          Index is a language name. Value is the suffix to be used in a
          mapping file to indicate that the source is a spec.

        * Mapping_Body_Suffix: single, indexed, case-insensitive index

          Index is a language name. Value is the suffix to be used in a
          mapping file to indicate that the source is a body.


   * Configuration - Config Files

        * Config_File_Switches: list: single, indexed, case-insensitive
          index

          Index is a language name. Value is the list of switches to
          specify to the compiler of the language a configuration file.

        * Config_Body_File_Name: single, indexed, case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration specific to a body of the language
          in a configuration file.

        * Config_Body_File_Name_Index: single, indexed,
          case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration specific to the body a unit in a
          multi unit source of the language in a configuration file.

        * Config_Body_File_Name_Pattern: single, indexed,
                                    case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration for all bodies of the languages in a
          configuration file.

        * Config_Spec_File_Name: single, indexed, case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration specific to a spec of the language
          in a configuration file.

        * Config_Spec_File_Name_Index: single, indexed,
          case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration specific to the spec a unit in a
          multi unit source of the language in a configuration file.

        * Config_Spec_File_Name_Pattern: single, indexed,
                                    case-insensitive index

          Index is a language name. Value is the template to be used to
          indicate a configuration for all specs of the languages in a
          configuration file.

        * Config_File_Unique: single, indexed, case-insensitive index

          Index is a language name. Indicates if there should be only
          one configuration file specified to the compiler of the
          language. Only authorized case-insensitive values are "true"
          and "false" (the default).


   * Configuration - Dependencies

        * Dependency_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to be
          used to specify to the compiler the dependency file when the
          dependency kind of the language is file based, and when
          Dependency_Driver is not specified for the language.

        * Dependency_Driver: list, indexed, case-insensitive index

          Index is a language name. Value is the name of the executable
          to be used to create the dependency file for a source of the
          language, followed by the required switches.


   * Configuration - Search Paths

        * Include_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to
          specify to the compiler of the language to indicate a
          directory to look for sources.

        * Include_Path: single, indexed, case-insensitive index

          Index is a language name. Value is the name of an environment
          variable that contains the path of all the directories that
          the compiler of the language may search for sources.

        * Include_Path_File: single, indexed, case-insensitive index

          Index is a language name. Value is the name of an environment
          variable the value of which is the path name of a text file
          that contains the directories that the compiler of the
          language may search for sources.

        * Object_Path_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is the list of switches to
          specify to the compiler of the language the name of a text
          file that contains the list of object directories. When this
          attribute is not declared, the text file is not created.



1.9.10.7 Package Cross_Reference Attributes
...........................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatxref' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatxref' for the source.


1.9.10.8 Package Eliminate Attributes
.....................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatelim' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatelim' for the source.


1.9.10.9 Package Finder Attributes
..................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatfind' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatfind' for the source.


1.9.10.10 Package gnatls Attributes
...................................

   * Switches: list

     Value is a list of switches to be used when invoking `gnatls'.


1.9.10.11 Package gnatstub Attributes
.....................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatstub' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatstub' for the source.


1.9.10.12 Package IDE Attributes
................................

   * Default_Switches: list, indexed

     Index is the name of an external tool that the GNAT Programming
     System (GPS) is supporting. Value is a list of switches to use
     when invoking that tool.

   * Remote_Host: single

     Value is a string that designates the remote host in a
     cross-compilation environment, to be used for remote compilation
     and debugging. This attribute should not be specified when running
     on the local machine.

   * Program_Host: single

     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.

   * Communication_Protocol: single

     Value is the name of the protocol to use to communicate with the
     target in a cross-compilation environment, for example `"wtx"' or
     `"vxworks"'.

   * Compiler_Command: single, indexed, case-insensitive index

     Index is a language Name. Value is a string that denotes the
     command to be used to invoke the compiler. The value of
     `Compiler_Command ("Ada")' is expected to be compatible with
     `gnatmake', in particular in the handling of switches.

   * Debugger_Command: single

     Value is a string that specifies the name of the debugger to be
     used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.

   * gnatlist: single

     Value is a string that specifies the name of the `gnatls' utility
     to be used to retrieve information about the predefined path; for
     example, `"gnatls"', `"powerpc-wrs-vxworks-gnatls"'.

   * VCS_Kind: single

     Value is a string used to specify the Version Control System (VCS)
     to be used for this project, for example "Subversion",
     "ClearCase". If the value is set to "Auto", the IDE will try to
     detect the actual VCS used on the list of supported ones.

   * VCS_File_Check: single

     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.

   * VCS_Log_Check: single

     Value is a string that specifies the command used by the VCS to
     check the validity of a log file.

   * Documentation_Dir: single

     Value is the directory used to generate the documentation of
     source code.


1.9.10.13 Package Install Attributes
....................................

   * Prefix: single

     Value is the install destination directory.

   * Sources_Subdir: single

     Value is the sources directory or subdirectory of Prefix.

   * Exec_Subdir: single

     Value is the executables directory or subdirectory of Prefix.

   * Lib_Subdir: single

     Value is library directory or subdirectory of Prefix.

   * Project_Subdir: single

     Value is the project directory or subdirectory of Prefix.

   * Active: single

     Indicates that the project is to be installed or not.
     Case-insensitive value "false" means that the project is not to be
     installed, all other values mean that the project is to be
     installed.


1.9.10.14 Package Linker Attributes
...................................

   * General

        * Required_Switches: list

          Value is a list of switches that are required when invoking
          the linker to link an executable.

        * Default_Switches: list, indexed, case-insensitive index

          Index is a language name. Value is a list of switches for the
          linker when linking an executable for a main source of the
          language, when there is no applicable Switches.

        * Leading_Switches: list, optional index, indexed,
                        case-insensitive index, others allowed

          Index is a source file name or a language name. Value is the
          list of switches to be used at the beginning of the command
          line when invoking the linker to build an executable for the
          source or for its language.

        * Switches: list, optional index, indexed, case-insensitive
          index,                     others allowed

          Index is a source file name or a language name. Value is the
          list of switches to be used when invoking the linker to build
          an executable for the source or for its language.

        * Trailing_Switches: list, optional index, indexed,
                          case-insensitive index, others allowed

          Index is a source file name or a language name. Value is the
          list of switches to be used at the end of the command line
          when invoking the linker to build an executable for the
          source or for its language. These switches may override the
          Required_Switches.

        * Linker_Options: list

          Value is a list of switches/options that are to be added when
          linking an executable from a project importing the current
          project directly or indirectly.  Linker_Options are not used
          when linking an executable from the current project.

        * Map_File_Option: single

          Value is the switch to specify the map file name that the
          linker needs to create.


   * Configuration - Linking

        * Driver: single

          Value is the name of the linker executable.


   * Configuration - Response Files

        * Max_Command_Line_Length: single

          Value is the maximum number of character in the command line
          when invoking the linker to link an executable.

        * Response_File_Format: single

          Indicates the kind of response file to create when the length
          of the linking command line is too large. Only authorized
          case-insensitive values are "none", "gnu", "object_list",
          "gcc_gnu", "gcc_option_list" and "gcc_object_list".

        * Response_File_Switches: list

          Value is the list of switches to specify a response file to
          the linker.



1.9.10.15 Package Metrics Attribute
...................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatmetric' for a source of the language, if there
     is no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatmetric' for the source.


1.9.10.16 Package Naming Attributes
...................................

   * Specification_Suffix: single, indexed, case-insensitive index

     Equivalent to attribute Spec_Suffix.

   * Spec_Suffix: single, indexed, case-insensitive index

     Index is a language name. Value is the extension of file names for
     specs of the language.

   * Implementation_Suffix: single, indexed, case-insensitive index

     Equivalent to attribute Body_Suffix.

   * Body_Suffix: single, indexed, case-insensitive index

     Index is a language name. Value is the extension of file names for
     bodies of the language.

   * Separate_Suffix: single

     Value is the extension of file names for subunits of Ada.

   * Casing: single

     Indicates the casing of sources of the Ada language. Only
     authorized case-insensitive values are "lowercase", "uppercase"
     and "mixedcase".

   * Dot_Replacement: single

     Value is the string that replace the dot of unit names in the
     source file names of the Ada language.

   * Specification: single, optional index, indexed,
          case-insensitive index

     Equivalent to attribute Spec.

   * Spec: single, optional index, indexed, case-insensitive index

     Index is a unit name. Value is the file name of the spec of the
     unit.

   * Implementation: single, optional index, indexed,
            case-insensitive index

     Equivalent to attribute Body.

   * Body: single, optional index, indexed, case-insensitive index

     Index is a unit name. Value is the file name of the body of the
     unit.

   * Specification_Exceptions: list, indexed, case-insensitive index

     Index is a language name. Value is a list of specs for the
     language that do not necessarily follow the naming scheme for the
     language and that may or may not be found in the source
     directories of the project.

   * Implementation_Exceptions: list, indexed, case-insensitive index

     Index is a language name. Value is a list of bodies for the
     language that do not necessarily follow the naming scheme for the
     language and that may or may not be found in the source
     directories of the project.


1.9.10.17 Package Pretty_Printer Attributes
...........................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatpp' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatpp' for the source.


1.9.10.18 Package Remote Attributes
...................................

   * Included_Patterns: list

     If this attribute is defined it sets the patterns to synchronized
     from the master to the slaves. It is exclusive with
     Excluded_Patterns, that is it is an error to define both.

   * Included_Artifact_Patterns: list

     If this attribute is defined it sets the patterns of compilation
     artifacts to synchronized from the slaves to the build master.
     This attribute replace the default hard-coded patterns.

   * Excluded_Patterns: list

     Set of patterns to ignore when synchronizing sources from the build
     master to the slaves. A set of predefined patterns are supported
     (e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to
     add some more patterns.

   * Root_Dir: single

     Value is the root directory used by the slave machines.


1.9.10.19 Package Stack Attributes
..................................

   * Switches: list

     Value is the list of switches to be used when invoking `gnatstack'.


1.9.10.20 Package Synchronize Attributes
........................................

   * Default_Switches: list, indexed, case-insensitive index

     Index is a language name. Value is a list of switches to be used
     when invoking `gnatsync' for a source of the language, if there is
     no applicable attribute Switches.

   * Switches: list, optional index, indexed, case-insensitive index,
                      others allowed

     Index is a source file name. Value is the list of switches to be
     used when invoking `gnatsync' for the source.


2 Gprbuild
**********

`GPRbuild' 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.

   `GPRbuild' manages a three step build process.

   * compilation phase:

     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.

   * post-compilation phase (or binding):

     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.

   * linking phase:

     All units or libraries from all subsystems are passed to a linker
     tool   specific to the set of toolchains being used.


The tool is generic in that it provides, when possible, equivalent
build capabilities for all supported languages. For this, it uses a
configuration file `<file>.cgpr' 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:

   * the default source naming conventions for each language,

   * the compiler name, location and required options,

   * how to compute inter-unit dependencies,

   * how to build static or dynamic libraries,

   * which post-compilation actions are needed,

   * how to link together units from different languages.


On the other hand, `GPRbuild' is not a replacement for general-purpose
build tools such as `make' or `ant' 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, `GPRbuild' might not be sufficient.  In such
situations, `GPRbuild' can still be used to manage the appropriate part
of the build. For instance it can be called from within a Makefile.

2.1 Building with GPRbuild
==========================



2.1.1 Command Line
------------------

Three elements can optionally be specified on GPRbuild's command line:

   * the main project file,

   * the switches for GPRbuild itself or for the tools it   drives, and

   * the main source files.

The general syntax is thus:

     gprbuild [<proj>.gpr] [switches] [names]
       {[-cargs opts] [-cargs:lang opts] [-largs opts] [-gargs opts]}

GPRbuild requires a project file, which may be specified on the command
line either directly or through the `-P' switch. If not specified,
GPRbuild uses the project file `default.gpr' 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.

   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 `Main' attribute in the project
file. If none exists, then no executable will be built.  It is also
possible to specify absolute file names, or file names relative to the
current directory.

   When source files are specified along with the option `-c', 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.

   If invoked without the `--config=' or `--autoconf=' options, then
GPRbuild will look for a configuration project file. The file name or
path name of this configuration project file depends on the target, the
runtime and environment variable `GPR_CONFIG' See *note Configuring
with GPRconfig::. 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 `auto.cgpr' in the
object directory of the main project. The project `auto.cgpr' will be
rebuilt at each GPRbuild invocation unless you use the switch
`--autoconf=path/auto.cgpr', which will use the configuration project
file if it exists and create it otherwise.

   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:

   * `-cargs'

     The arguments that follow up to the next command line separator are
      options for all compilers for all languages.    Example: `-cargs
     -g'

   * `-cargs:<language name>'

     The arguments that follow up to the next command line separator are
      options for the compiler of the specific language.

     Examples:

        - `-cargs:Ada -gnatf'

        - `-cargs:C -E'

   * `-bargs'

     The arguments that follow up to the next command line separator are
      options for all binder drivers.

   * `-bargs:<language name>'

     The arguments that follow up to the next command line separators
     are   options for the binder driver of the specific language.

     Examples:

        - `-bargs:Ada binder_prefix=ppc-elf'

        - `-bargs:C++ c_compiler_name=ccppc'

   * `-largs'

     The arguments that follow up to the next command line separator are
      options for the linker, when linking an executable.

   * `-gargs'

     The arguments that follow up to the next command line separator are
      options for GPRbuild itself. Usually `-gargs' is specified after
     one or   several other command line separators.

   * `-margs'

     Equivalent to `-gargs', provided for compatibility with
     `gnatmake'.

2.1.2 Switches
--------------

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.

   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.

   When there are several mains, if there are sources of the same
language, then Switches (<language of main>) is taken into account, if
specified.

   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.

The switches that are interpreted directly by GPRbuild are listed below.

   First, the switches that may be specified only on the command line,
but not in package Builder of the main project:

   * `--distributed=slave1[,slave2]'

     Activate the distributed compilation on the listed slaves nodes
     (IP or name).

   * `--slave-env=name'

     Use name as the slave's environment directory instead of the
     default one.  This options is only used in distributed mode.

   * `--version'

     Display information about GPRbuild: version, origin and legal
     status, then   exit successfully, ignoring other options.

   * `--help'

     Display GPRbuild usage, then exit successfully, ignoring other
     options.

   * `--display-paths'

     Display two lines: the configuration project file search path and
     the user   project file search path, then exit successfully,
     ignoring other options.

   * `--config=<config project file name>'

     This specifies the configuration project file name. By default, the
      configuration project file name is `default.cgpr'. Option
     `--config='   cannot be specified more than once. The
     configuration project file specified   with `--config=' must exist.

   * `--autoconf=<config project file name>'

     This specifies a configuration project file name that already
     exists   or will be created automatically. Option `--autoconf='
     cannot   be specified more than once. If the configuration project
     file   specified with `--autoconf=' exists, then it is   used.
     Otherwise, GPRconfig is invoked to create it automatically.

   * `--target=<targetname>'

     This specifies that the default configuration project file is
     `<targetname>.cgpr'. If no configuration project file with this
     name   is found, then GPRconfig is invoked with option
     `--target=<targetname>'to create a configuration project file
     `auto.cgpr'.

     Note: only one of `--config', `--autoconf' or `--target='   can be
     specified.

   * `--subdirs=<subdir>'

     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.

   * `--unchecked-shared-lib-imports'

     Allow shared library projects to import projects that are not
     shared   library projects.

   * `--source-info=<source info file>'

     Specify a source info file. If the source info file is specified
     as a   relative path, then it is relative to the object directory
     of the main   project. If the source info file does not exist,
     then after the Project   Manager has successfully parsed and
     processed the project files and found   the sources, it creates
     the source info file. If the source info file   already exists and
     can be read successfully, then the Project Manager will   get all
     the needed information about the sources from the source info file
      and will not look for them. This reduces the time to process the
     project   files, especially when looking for sources that take a
     long time. If the   source info file exists but cannot be parsed
     successfully, the Project   Manager will attempt to recreate it.
     If the Project Manager fails to create   the source info file, a
     message is issued, but GPRbuild does not fail.

   * `--restricted-to-languages=<list of language names>'

     Restrict the sources to be compiled to one or several languages.
     Each   language name in the list is separated from the next by a
     comma, without any   space.

     Example: `--restricted-to-languages=Ada,C'

     When this switch is used, switches `-c', `-b' and   `-l' are
     ignored. Only the compilation phase is performed and the   sources
     that are not in the list of restricted languages are not compiled,
      including mains specified in package Builder of the main project.

   * `-aP dir' (Add directory `dir' to project search path)

     Specify to GPRbuild to add directory `dir' to the user project
     file search   path, before the default directory.

   * `-d' (Display progress)

     Display progress for each source, up to date or not, as a single
     line _completed x out of y (zz%)..._. 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
     `-q').

   * `-Inn' (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.

   * `-eL' (Follow symbolic links when processing project files)

     By default, symbolic links on project files are not taken into
     account   when processing project files. Switch `-eL' changes this
     default   behavior.

   * `-eS' (no effect)

     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.

   * `-F' (Full project path name in brief error messages)

     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 `-F' is
     used, the full path of the project   file is used. This switch has
     no effect when switch `-v' is used.

   * `-o name' (Choose an alternate executable name)

     Specify the file name of the executable. Switch `-o' 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
     `Main' of the main project.

   * `-P proj' (use Project file _proj_)

     Specify the path name of the main project file. The space between
     `-P'   and the project file name is optional. Specifying a project
     file name (with   suffix `.gpr') may be used in place of option
     `-P'. Exactly one main   project file can be specified.

   * `-r' (Recursive)

     This switch has an effect only when `-c' or `-u' is also
     specified and there are no mains: it means that all sources of all
     projects   need to be compiled or recompiled.

   * `-u' (Unique compilation, only compile the given files)

     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.

     In both cases, do not attempt the binding and the linking phases.

   * `-U' (Compile all sources of all projects)

     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.

     In both cases, do not attempt the binding and the linking phases.

   * `-vPx' (Specify verbosity when parsing Project Files)

     By default, GPRbuild does not display anything when processing
     project files,   except when there are errors. This default
     behavior is obtained with switch   `-vP0'. Switches `-vP1' and
     `-vP2' yield increasingly   detailed output.

   * `-Xnm=val' (Specify an external reference for Project Files)

     Specify an external reference that may be queried inside the
     project files   using built-in function `external'. For example,
     with   `-XBUILD=DEBUG',   `external("BUILD")' inside a project
     file will have the value   `"DEBUG"'.


Then, the switches that may be specified on the command line as well as
in package Builder of the main project (attribute Switches):

   * `--create-map-file'

     When linking an executable, if supported by the platform, create a
     map file   with the same name as the executable, but with suffix
     `.map'.

   * `--create-map-file=<map file>'

     When linking an executable, if supported by the platform, create a
     map file   with file name `<map file>'.

   * `--no-indirect-imports'

     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.

   * `--indirect-imports'

     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   `--no-indirect-imports' on the command line.

   * `--no-object-check'

     Do not check if an object has been created after compilation.

   * `--no-split-units'

     Forbid the sources of the same Ada unit to be in different
     projects.

   * `--single-compile-per-obj-dir'

     Disallow several simultaneous compilations for the same object
     directory.

   * `-b' (Bind only)

     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.

   * `-c' (Compile only)

     Specify to GPRbuild that the compilation phase is to be performed,
     but not   the other phases unless they are specified by
     appropriate switches.

   * `-f' (Force recompilations)

     Force the complete processing of all phases (or of those
     explicitly specified)   even when up to date.

   * `-j<num>' (use _num_ simultaneous compilation jobs)

     By default, GPRbuild invokes one compiler at a time. With switch
     `-j',   it is possible to instruct GPRbuild to spawn several
     simultaneous compilation   jobs if needed. For example, `-j2' for
     two simultaneous compilation   jobs or `-j4' for four. On a
     multi-processor system,   `-j<num>' can greatly speed up the build
     process. If `-j0' is   used, then the maximum number of
     simultaneous compilation jobs is the number   of core processors
     on the platform.

     Switch `-j<num>' is also used to spawned several simultaneous
     binding   processes and several simultaneous linking processes
     when there are several   mains to be bound and/or linked.

   * `-k' (Keep going after compilation errors)

     By default, GPRbuild stops spawning new compilation jobs at the
     first   compilation failure. Using switch `-k', 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 `-k' is   used.

   * `-l' (Link only)

     Specify to GPRbuild that the linking phase is to be performed, but
     not   the other phases unless they are specified by appropriate
     switches.

   * `-m' (Minimum Ada recompilation)

     Do not recompile Ada code if timestamps are different but
     checksums are the   same.

   * `-p' or `--create-missing-dirs' (Create missing object, library
     and exec directories)

     By default, GPRbuild checks that the object, library and exec
     directories   specified in project files exist. Switch `-p'
     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.

   * `-q' (Quiet output)

     Do not display anything except errors and progress (switch `-d').
      Cancel any previous switch `-v'.

   * `-R' (no run path option)

     Do not use a run path option to link executables or shared
     libraries,   even when attribute Run_Path_Option is specified.

   * `-s' (recompile if compilation switches have changed)

     By default, GPRbuild will not recompile a source if all
     dependencies are   satisfied. Switch `-s' 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   `-s' is used later.

   * `-v' (Verbose output)

     Display full paths, all options used in spawned processes, and
     reasons why   these processes are spawned. Cancel any previous
     switch `-q'.

   * `-vl' (Verbose output, low level)

     Verbose output. Some verbose messages are not displayed.

   * `-vm' (Verbose output, medium level)

     Verbose output. Some verbose messages may not be displayed.

   * `-vh' (Verbose output, high level)

     Equivalent to `-v'.

   * `-we' (Treat all warnings as errors)

     When `-we' is used, any warning during the processing of the
     project   files becomes an error and GPRbuild does not attempt any
     of the phases.

   * `-wn' (Treat warnings as warnings)

     Switch `-wn' may be used to restore the default after `-we' or
     `-ws'.

   * `-ws' (Suppress all warnings)

     Do not generate any warnings while processing the project files.


Switches that are accepted for compatibility with gnatmake, either on
the command line or in the Builder Ada switches in the main project
file:

   * `-nostdinc'

   * `-nostdlib'

   * `-fstack-check'

   * `-fno-inline'

   * `-g*' Any switch starting with `-g'

   * `-O*' Any switch starting with `-O'


These switches are passed to the Ada compiler.

2.1.3 Initialization
--------------------

Before performing one or several of its three phases, GPRbuild has to
read the command line, obtain its configuration, and process the
project files.

   If GPRbuild is invoked with an invalid switch or without any project
file on the command line, it will fail immediately.

   Examples:

     $ gprbuild -P
     gprbuild: project file name missing after -P

     $ gprbuild -P c_main.gpr -WW
     gprbuild: illegal option "-WW"

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 `<prefix>/bin',
then the default configuration project directory is
`<prefix>/share/gpr', otherwise there is no default configuration
project directory.

   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 `default.cgpr'. This default may be modified
using the switch `--config=...'

   Example:

     $ gprbuild --config=my_standard.cgpr -P my_project.gpr

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 `auto.cgpr' that is located in the
object directory of the main project file.

   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.

   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:

     $ gprbuild -P my_project.gpr
     ada_main.gpr:3:26: "src" is not a valid directory
     gprbuild: "my_project.gpr" processing failed

Once the user project files have been dealt with successfully, GPRbuild
will start its processing.

2.1.4 Compilation of one or several sources
-------------------------------------------

If GPRbuild is invoked with `-u' or `-U' 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 `-f' is
also specified. Then GPRbuild will stop its execution.

   The options/switches used to compile these sources are described in
section *note Compilation Phase::.

   If GPRbuild is invoked with `-u' and no source file name is specified
on the command line, GPRbuild will compile or recompile all the sources
of the _main_ project and then stop.

   In contrast, if GPRbuild is invoked with `-U', and again no source
file name is specified on the command line, GPRbuild will compile or
recompile all the sources of _all the projects in the project tree_ and
then stop.

2.1.5 Compilation Phase
-----------------------

When switch `-c' is used or when switches `-b' or `-l' 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:

   * all the sources in languages other than Ada

   * if there are no main specified, all the Ada sources

   * if there is a non Ada main, but no attribute `Roots' specified for
      this main, all the Ada sources

   * if there is a main with an attribute `Roots' specified, all   the
     Ada sources in the closures of these Roots.

   * if there is an Ada main specified, all the Ada sources in the
     closure   of the main


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.

   Example:

        for Roots ("main.c") use ("pkga", "pkgb");

Package PkgA and PkgB will be considered, and all the Ada units in their
closure will also be considered.

   GPRbuild will first consider each source and decide if it needs to be
(re)compiled.

   A source needs to be compiled in the following cases:

   * Switch `-f' (force recompilations) is used

   * The object file does not exist

   * The source is more recent than the object file

   * The dependency file does not exist

   * The source is more recent than the dependency file

   * When `-s' is used: the switch file does not exist

   * When `-s' is used: the source is more recent than the switch file

   * The dependency file cannot be read

   * The dependency file is empty

   * The dependency file has a wrong format

   * A source listed in the dependency file does not exist

   * A source listed in the dependency file has an incompatible time
     stamp

   * A source listed in the dependency file has been replaced

   * Switch `-s' is used and the source has been compiled with
     different switches or with the same switches in a different order


When a source is successfully compiled, the following files are normally
created in the object directory of the project of the source:

   * An object file

   * A dependency file, except when the dependency kind for the language
      is `none'

   * A switch file if switch `-s' is used


The compiler for the language corresponding to the source file name is
invoked with the following switches/options:

   * The required compilation switches for the language

   * The compilation switches coming from package `Compiler' of the
     project of the source

   * The compilation switches specified on the command line for all
     compilers,   after `-cargs'

   * The compilation switches for the language of the source, specified
      after `-cargs:<language>'

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


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 `.cswi'. For example, the switch file for
source `main.adb' is `main.cswi' and for `toto.c' it is `toto.cswi'.

   If the compilation is successful, then if the creation of the
dependency file is not done during compilation but after (see
configuration attribute `Compute_Dependency'), then the process to
create the dependency file is invoked.

   If GPRbuild is invoked with a switch `-j' specifying more than one
compilation process, then several compilation processes for several
sources of possibly different languages are spawned concurrently.

   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.

   Example:

        project Prj is
           for Languages use ("Ada", "C");
           for Interfaces use ("pkg.ads", "toto.h");
        end Prj;

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.

2.1.6 Post-Compilation Phase
----------------------------

The post-compilation phase has two parts: library building and program
binding.

   If there are libraries that need to be built or rebuilt, _gprbuild_
will call the library builder, specified by attribute `Library_Builder'.
This is generally the tool _gprlib_, provided with GPRbuild. If gprbuild
can determine that a library is already up to date, then the library
builder will not be called.

   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.

   For Ada, the binder driver is normally _gprbind_, which will call
the appropriate version of _gnatbind_, 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 _gprbind_
the full path of _gnatbind_, using the Binder switch `--gnatbind_path='.

   Example:

        package Binder is
           for Switches ("Ada") use ("--gnatbind_path=/toto/gnatbind");
        end Binder;

If GPRbuild can determine that the artifacts from a previous
post-compilation phase are already up to date, the binder driver is not
called.

   If there are no libraries and no binder drivers, then the
post-compilation phase is empty.

2.1.7 Linking Phase
-------------------

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.

   If switch -jnnn is used, with nnn other than 1, gprbuild will
attempt to link simultaneously up to nnn executables.

2.1.8 Incompatibilities with gnatmake
-------------------------------------

Here is a list of incompatibilities between gnatmake invoked with a
project file and gprbuild:

   * gprbuild never recompiles the runtime sources.

   * gnatmake switches that are not recognized by gprbuild:

        - -a (Consider all files, even readonly ali files)

        - -M (List object file dependences for Makefile)

        - -n (Check objects up to date, output next file to compile if
          not)

        - -x (Allow compilation of needed units external to the
          projects)

        - -z No main subprogram (zero main)

        - -GCC=command

        - -GNATBIND=command

        - -GNATLINK=command

        - -aLdir (Skip missing library sources if ali in dir)

        - -Adir (like -aLdir -aIdir)

        - -aOdir (Specify library/object files search path)

        - -aIdir (Specify source files search path)

        - -Idir (Like -aIdir -aOdir)

        - -I- (Don't look for sources & library files in the default
          directory)

        - -Ldir (Look for program libraries also in dir)


   * The switches that are not directly recognized by gprbuild and
     passed to   the Ada compiler are only:

        - -nostdlib

        - -nostdinc

        - -fstack-check

        - -fno-inline

        - -Oxxx (any switch starting with -O)

        - -gxxx (any switch starting with -g)


2.2 Configuring with GPRconfig
==============================



2.2.1 Configuration
-------------------

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 `GPRbuild' 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 *note Configuring with GPRconfig::), offers this
capability. In this chapter most of the examples can use
autoconfiguration.

   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.

   * If a file has a base names that matches `<target>-<rts>.cgpr',
     `<target.cgpr', `<rts>.cgpr' or `default.cgpr' is found in   the
     default configuration files directory, this file is used. The
     target   and rts parameters are specified via the `--target' and
     `--RTS'   switches of `gprbuild'. The default directory is is
     `share/gpr'   in the installation directory of `gprbuild'

   * If not found, the environment variable `GPR_CONFIG' 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.

   * If still not found and you used the `--autoconf' switch, then   a
     new configuration file is automatically generated based on the
     specified   target and on the list of languages specified in your
     projects.

     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:

        - using cross compilers (in which case you need to use
          gprconfig's     `--target=') option,

        - using a specific Ada runtime (e.g. `--RTS=sjlj'),

        - working with compilers not in the path or not first in the
          path, or

        - autoconfiguration does not give the expected results.


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:

   * The following command triggers interactive mode. The configuration
     will be   generated in GPRbuild's default location,
     `./default.cgpr)', unless   `-o' is used.

            gprconfig

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

            gprconfig -o path/my_config.cgpr
            gprbuild --config=path/my_config.cgpr

   * The following command again triggers interactive mode, and only the
      relevant cross compilers for target ppc-elf will be proposed.

            gprconfig --target=ppc-elf

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

            gprconfig --config=Ada --config=C --batch

   * The next command, a combination of the previous examples, creates
     in   batch mode a configuration file named `x.cgpr' for
     cross-compiling   Ada with a run-time called `hi' and using C for
     the LEON   processor.

            gprconfig --target=leon-elf --config=Ada,,hi --config=C --batch -o x.cgpr

2.2.2 Using GPRconfig
---------------------



2.2.3 Description
-----------------

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.

     explicitly. Instead, it is used implicitly by GPRbuild through the
     use of `--config' and `--autoconf' switches.

2.2.4 Command line arguments
----------------------------

GPRconfig supports the following command line switches:

`--target=platform'
     This switch indicates the target computer on which your
     application will   be run. It is mostly useful for cross
     configurations. Examples include   `ppc-elf', `ppc-vx6-windows'.
     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 `x86-linux' as
      an alias for `i686-pc-linux-gnu'.    The default target is the
     machine on which GPRconfig is run.

     If you enter the special target `all', then all compilers found on
     the   `PATH' will be displayed.

`--show-targets'
     As mentioned above, GPRconfig knows which targets are compatible.
     You   can use this switch to find the list of targets that are
     compatible   with `--target'.

`--config=language[,version[,runtime[,path[,name]]]]'
     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.

     In general, only `language' needs to be specified, and the first
     compiler on the `PATH' 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:

          --config=Ada --config=C

     `path' is the directory that contains the compiler executable, for
      instance `/usr/bin' (and not the installation prefix `/usr').

     `name' should be one of the compiler names defined in the GPRconfig
      knowledge base. The list of supported names includes `GNAT',
     `GCC',.... This name is   generally not needed, but can be used to
     distinguish among several compilers   that could match the other
     arguments of `--config'.

     Another possible more frequent use of `name' is to specify the base
      name of an executable. For instance, if you prefer to use a diab
     C compiler   (executable is called `dcc') instead of `gcc', even
     if the latter   appears first in the path, you could specify `dcc'
     as the name parameter.

          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

     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 `.gpr' extension will be shown in the editor, although they of
     course   play no role for gprbuild itself.

`--batch'
     If this switch is specified, GPRconfig automatically selects the
     first   compiler matching each of the `--config' switches, and
     generates the   configuration file immediately. It will not
     display an interactive menu.

`-o file'
     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.

`--db directory'
`--db-'
     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.

`-h'
     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,...


2.2.5 Interactive use
---------------------

When you launch GPRconfig, it first searches for all compilers it can
find on your `PATH', that match the target specified by `--target'. It
is recommended, although not required, that you place the compilers
that you expect to use for your application in your `PATH' before you
launch `gprconfig', since that simplifies the setup.

   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),.... It then waits for you to select one of the compilers.
This list is sorted by language, then by order in the `PATH'
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.

   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.

   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.

   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.

   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.

   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.

2.2.6 The GPRconfig knowledge base
----------------------------------

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.

     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.

   All knowledge of compilers is embedded in a set of XML files called
the _knowledge base_.  Users can easily contribute to this general
knowledge base, and have GPRconfig immediately take advantage of any
new data.

   The knowledge base contains various kinds of information:

   * Compiler description

     When it is run interactively, GPRconfig searches the user's
     `PATH' for known compilers, and tries to deduce their
     configuration (version, supported languages, supported targets,
     run-times,   ...). From the knowledge base GPRconfig knows how to
     extract the   relevant information about a compiler.

     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.

   * Specific compilation switches

     When a compiler is used, depending on its version, target,
     run-time,...,   some specific command line switches might have to
     be supplied. The   knowledge base is a good place to store such
     information.

     For instance, with the GNAT compiler, using the soft-float runtime
     should   force _gprbuild_ to use the `-msoft-float' compilation
     switch.

   * Linker options

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

   * Unsupported compiler mix

     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.

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.

2.2.6.1 General file format
...........................

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.

   The location of the knowledge base is `$prefix/share/gprconfig',
where `$prefix' is the directory in which GPRconfig was installed. Any
file with extension `.xml' in this directory will be parsed
automatically by GPRconfig at startup.

   All files must have the following format:

     <?xml version="1.0" ?>
     <gprconfig>
        ...
     </gprconfig>

The root tag must be `<gprconfig>'.

   The remaining sections in this chapter will list the valid XML tags
that can be used to replace the "..." code above. These tags can either
all be placed in a single XML file, or split across several files.

2.2.6.2 Compiler description
............................

One of the XML tags that can be specified as a child of `<gprconfig>' is
`<compiler_description>'. 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 `PATH' environment variable.

   This is optional information, but simplifies the use of GPRconfig,
since the user is then able to omit some parameters from the `--config'
command line argument, and have them automatically computed.

   The `<compiler_description>' 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.

`<name>'
     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 `compiler_description' node.

          <compiler_description>
              <name>GNAT</name>
            </compiler_description>

`<executable>'
     This tag contains a string, which is the name of an executable
     to search for on the PATH. Examples are `gnatls', `gcc',...

     In some cases, the tools have a common suffix, but a prefix that
     might depend   on the target. For instance, GNAT uses `gnatmake'
     for native platforms,   but `powerpc-wrs-vxworks-gnatmake' for
     cross-compilers to VxWorks.    Most of the compiler description is
     the same, however.    For such cases, the value of the
     `executable' node is considered as   beginning a regular
     expression. The tag also accepts an optional   attribute `prefix',
      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 `gnatls' or
     `powerpc-wrs-vxworks-gnatls', depending on   the name of the
     executable that was found.

     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 `.*gnatmake' as the
     regexp, it will not match   `gnatmake-debug'.

     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 (*note Configurations::),   you can test
     whether that language was specified on the command line by   using
     a filter such as

           <compilers>
            <compiler language="name"/>
           </compilers>


            <executable prefix="1">(powerpc-wrs-vxworks-)?gnatmake</executable>
            <version><external>${PREFIX}gnatls -v</external></version>

     GPRconfig searches in all directories listed on the PATH for such
     an executable. When one is found, the rest of the
     `<compiler_description>'   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.

`<target>'
     This node indicates how to query the target architecture for the
     compiler.    See *note GPRconfig external values:: for valid
     children.

     If this isn't specified, the compiler will always be considered as
     matching   on the current target.

`<version>'
     This tag contains any of the nodes defined in *note GPRconfig
     external values:: 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.

`<variable name="varname">'
     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 *note
     GPRconfig external values::   below for valid children of   this
     node.  If the evaluation of this variable is empty then the
     compiler   is considered as invalid.

`<languages>'
     This node indicates how to query the list of languages. See
     *note GPRconfig external values::   below for valid children of
     this node.

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

     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.

`<runtimes>'
     This node indicates how to query the list of supported runtimes
     for the   compiler. See *note GPRconfig external values::   below
     for valid children. The returned value   is split into words as
     for `<languages>'.

     This node accepts one attribute, `"default"', which contains a list
      of comma-separated names of runtimes. It is used to sort the
     runtimes when   listing which compilers were found on the PATH.

     As a special case, gprconfig will merge two runtimes if the XML
     nodes   refer to the same directories after normalization and
     resolution of   links. As such, on Unix systems, the "adalib" link
     to "rts-native/adalib"   (or similar) will be ignored and only the
     "native" runtime will be   displayed.


2.2.6.3 GPRconfig external values
.................................

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 `<directory>' and
`<external>' children can be repeated multiple times, and the
`<filter>' and `<must_match>' 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 `<directory>' and `<external>' nodes.

   * A simple string

     A simple string given in the node indicates a constant. For
     instance, the list of supported languages might be defined as:

          <compiler_description>
            <name>GNAT</name>
            <executable>gnatmake</executable>
            <languages>Ada</languages>
            </compiler_description>

     for the GNAT compiler, since this is an Ada-only compiler.

     Variables can be referenced in simple strings.

   * `<getenv name="variable" />'

     If the contents of the node is a `<getenv>' child, the value of
     the environment variable `variable' is returned. If the variable is
      not defined, this is an error and the compiler is ignored.

          <compiler_description>
            <name>GCC-WRS</name>
            <executable prefix="1">cc(arm|pentium)</executable>
            <version>
            <getenv name="WIND_BASE" />
            </version>
            </compile_description>

   * `<external>command</external>'

     If the contents of the node is an `<external>' 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 `<executable>' node),
     is placed first   on the `PATH'. 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.

     For instance, extracting the target processor from `gcc' can be
     done   with:

          <version>
            <external>gcc -dumpmachine</external>
            </version>

     Since the `PATH' has been modified, we know that the `gcc' command
      that is executed is the one from the same directory as the
     `<external>'   node.

     Variables are substituted in COMMAND.

   * `<grep regexp="regexp" group="0" />'

     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 REGEXP and the
     parenthesis group specified by   GROUP is returned. By default,
     group is 0, which indicates the   whole output of the command.

     For instance, extracting the version number from `gcc' can be done
      with:

          <version>
            <external>gcc -v</external>
            <grep regexp="^gcc version (S+)" group="1" />
            </version>

   * `<directory group="0" contents="">regexp</directory>'

     If the contents of the node is a `<directory'> 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 `<executable>' 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.

     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.

     REGEXP can be any valid regular expression. This will only match
     a directory or file name, not a subdirectory. Remember to quote
     special   characters, including ".", if you do not mean to use a
     regexp.

     The optional attribute CONTENTS can be used to indicate that the
     contents of the file should be read. The first line that matches
     the regular   expression given by CONTENTS will be used as a file
     path instead of   the file matched by REGEXP. This is in general
     used on platforms that   do not have symbolic links, and a file is
     used instead of a symbolic link.    In general, this will work
     better than GROUP specifies a string rather   than a parenthesis
     group, since the latter will match the path matched by   REGEXP,
     not the one read in the file.

     For instance, finding the list of supported runtimes for the GNAT
     compiler   is done with:

          <runtimes>
            <directory group="1">
            ../lib/gcc/${TARGET}/.*/rts-(.*)/adainclude
            </directory>
            <directory group="default">
            ../lib/gcc/${TARGET}/.*/adainclude
            </directory>
            </runtimes>

     Note the second node, which matches the default run-time, and
     displays it as   such.

   * `<filter>value1,value2,...</filter>'

     This node must come after one of 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
     `value1', `value2',... are kept.

     For instance, the `gcc' 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:

          <languages>
            <external regexp="languages=(S+)" group="1">gcc -v</external>
            <filter>c,c++,fortran</filter>
            </languages>

   * `<must_match>regexp</must_match>'

     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.

     For instance, if you want to have a `<compiler_description>' tag
     specific to an older version of GCC, you could write:

          <version>
            <external regexp="gcc version (S+)"
            group="1">gcc -v </external>
            <must_match>2.8.1</must_match>
            </version>

     Other versions of gcc will not match this `<compiler_description>'
      node.

2.2.6.4 GPRconfig variable substitution
.......................................

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 `<directory>'),
and in the configurations (*note Configuration::).

   A variable is referenced by `${name}' where NAME is either a user
variable or a predefined variable.  An alternate reference is `$name'
where NAME is a sequence of alpha numeric characters or underscores.
Finally `$$' is replaced by a simple `$'.

   User variables are defined by `<variable>' nodes and may override
predefined variables.  To avoid a possible override use lower case
names.

   The variables are used in two contexts: either in a
`<compiler_description>' node, in which case the variable refers to the
compiler we are describing, or within a `<configuration>' node.  In the
latter case, and since there might be several compilers selected, you
need to further specify the variable by adding in parenthesis the
language of the compiler you are interested in.

   For instance, the following is invalid:

     <configuration>
       <compilers>
        <compiler name="GNAT" />
       </compilers>
       <targets negate="true">
         <target name="^powerpc-elf$"/>
       </targets>
       <config>
         package Compiler is
            for Driver ("Ada") use "${PATH}gcc";   --  Invalid !
         end Compiler;
       </config>
      </configuration>

   The trouble with the above is that if you are using multiple
languages like C and Ada, both compilers will match the "negate" part,
and therefore there is an ambiguity for the value of `${PATH}'. To
prevent such issues, you need to use the following syntax instead when
inside a `<configuration>' node:

     for Driver ("Ada") use "${PATH(ada)}gcc";   --  Correct

   Predefined variables are always in upper case.  Here is the list of
predefined variables

EXEC
     is the name of the executable that was found through
     `<executable>'. It only contains the basename, not the directory
     information.

HOST
     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 `configure' when GPRconfig was built.

TARGET
     is replaced by the target architecture of the compiler, as
     returned by the `<target>' node. This is of course not available
     when computing the target itself.

     This variable takes the language of the compiler as an optional
     index when in a `<configuration>' block: if the language is
     specified, the target returned by that specific compiler is used;
     otherwise, the normalized target common to all the selected
     compilers will be returned (target normalization is also described
     in the knowledge base's XML files).

VERSION
     is replaced by the version of the compiler. This is not available
     when computing the target or, of course, the version itself.

PREFIX
     is replaced by the prefix to the executable name, as defined by the
     `<executable>' node.

PATH
     is the current directory, i.e. the one containing the executable
     found through `<executable>'. It always ends with a directory
     separator.

LANGUAGE
     is the language supported by the compiler, always folded to
     lower-case

RUNTIME
RUNTIME_DIR
     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.

     RUNTIME_DIR always end with a directory separator.

GPRCONFIG_PREFIX
     is the directory in which GPRconfig was installed (e.g
     `"/usr/local/"' if the executable is `"/usr/local/bin/gprconfig"'.
     This directory always ends with a directory separator.  This
     variable never takes a language in parameter, even within a
     `<configuration>' node.


   If a variable is not defined, an error message is issued and the
variable is substituted by an empty string.

2.2.6.5 Configurations
......................

The second type of information stored in the knowledge base are the
chunks of _gprbuild_ configuration files.

   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.

   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 `-msoft-float' command line switch.

   GPRconfig does not perform sophisticated merging of chunks. It simply
groups packages together. For example, if the two chunks are:

     chunk1:
        package Language_Processing is
          for Attr1 use ("foo");
        end Language_Processing;
     chunk2:
        package Language_Processing is
          for Attr1 use ("bar");
        end Language_Processing;

Then the final configuration file will look like:

     package Language_Processing is
       for Attr1 use ("foo");
       for Attr1 use ("bar");
     end Language_Processing;

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

     package Language_Processing is
       for Attr1 use ("foo", "bar");
     end Language_Processing;

the two chunks above should be written as:

     chunk1:
       package Language_Processing is
         for Attr1 use Language_Processing'Attr1 & ("foo");
       end Language_Processing;
     chunk2:
       package Language_Processing is
         for Attr1 use Language_Processing'Attr1 & ("bar");
       end Language_Processing;

The chunks are described in a `<configuration>' XML node. The most
important child of such a node is `<config>', which contains the chunk
itself. For instance, you would write:

     <configuration>
       ...  list of filters, see below
       <config>
        package Language_Processing is
           for Attr1 use Language_Processing'Attr1 & ("foo");
        end Language_Processing;
       </config>
     </configuration>

If `<config>' is an empty node (i.e., `<config/>' or
`<config></config>') 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.

   The special variables (*note GPRconfig variable substitution::) are
also substituted in the chunk. That allows you to compute some
attributes of the compiler (its path, the runtime,...), and use them
when generating the chunks.

   The filters themselves are of course defined through XML tags, and
can be any of:

`<compilers negate="false">'
     This filter contains a list of `<compiler>' children. The
     `<compilers>' filter matches if any of its children match.
     However, you can have several `<compilers>' 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:

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

     If the attribute NEGATE is `true', then the meaning of this filter
     is inverted, and it will match if none of its children matches.

     The format of the `<compiler>' is the following:

          <compiler name="name" version="..."
             runtime="..." language="..." />

     The name and language attributes, when specified, match the
     corresponding attributes used in the `<compiler_description>'
     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.

     For instance, to check a GNAT compiler in the 5.x family, use:

          <compiler name="GNAT" version="5.d+" />

`<hosts negate="false">'
     This filter contains a list of `<host>' children. It matches when
     any of its children matches. You can specify only one `<hosts>'
     node.  The format of `<host>' is a node with a single mandatory
     attribute NAME, which is a regexp matched against the architecture
     on which GPRconfig is running. The name of the architecture was
     computed by `configure' 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).

     If the NEGATE attribute is `true', then the meaning of this filter
     is inverted, and it will match when none of its children matches.

     For instance, to active a chunk only if the compiler is running on
     an intel linux machine, use:

          <hosts>
            <host name="i.86-.*-linux(-gnu)?" />
          </hosts>

`<targets negate="false">'
     This filter contains a list of `<target>' children. It behaves
     exactly like `<hosts>', 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:

     If the NEGATE attribute is `true', then the meaning of this filter
     is inverted, and it will match when none of its children matches.

          <targets>
            <target name="i.86-.*-linux(-gnu)?" />
          </targets>


2.3 Configuration File Reference
================================

  A text file using the project file syntax. It defines languages and
their characteristics as well as toolchains for those languages and
their   characteristics.

   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.

   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.

   The default name of the configuration file, when not specified to
GPRbuild by switches `--config=' or `--autoconf=' is `default.cgpr'.
Although the name of the configuration file can be any valid file name,
it is recommended that its suffix be `.cgpr' (for Configuration GNAT
Project), so that it cannot be confused with a standard project file
which has the suffix `.gpr'.

   When `default.cgpr' cannot be found in the configuration project
path, GPRbuild invokes GPRconfig to create a configuration file.

   In the following description of the attributes, when an attribute is
an indexed attribute and its index is a language name, for example
`Spec_Suffix (<language>)', then the name of the language is case
insensitive.  For example, both `C' and `c' are allowed.

   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.

2.3.1 Project Level Configuration Attributes
--------------------------------------------



2.3.1.1 General Attributes
..........................


   * Default_Language

     Specifies the name of the language of the immediate sources of a
     project when   attribute `Languages' is not declared in the
     project. If attribute   `Default_Language' is not declared in the
     configuration file, then each user   project file in the project
     tree must have an attribute `Languages' declared,   unless it
     extends another project. Example:

             for Default_Language use "ada";

   * Run_Path_Option

     Specifies a "run path option"; i.e., an option to use when linking
     an   executable or a shared library to indicate the path (Rpath)
     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:

              for Run_Path_Option  use ("-Wl,-rpath,");

   * Run_Path_Origin

     Specifies the string to be used in an Rpath to indicate the
     directory   of the executable, allowing then to have Rpaths
     specified as relative paths.

     Example:

              for Run_Path_Origin use "$ORIGIN";

   * Toolchain_Version (<language>)

     Specifies a version for a toolchain, as a single string. This
     toolchain   version is passed to the library builder. Example:

              for Toolchain_Version ("Ada") use "GNAT 6.1";

     This attribute is used by GPRbind to decide on the names of the
     shared GNAT   runtime libraries.

   * Toolchain_Description (<language>)

     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:

              for Toolchain_Description ("C") use "gcc version 4.1.3 20070425";

2.3.1.2 General Library Related Attributes
..........................................


   * Library_Support

     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
     `none', `static_only' and `full'. Example:

             for Library_Support use "full";

   * Library_Builder

     Specifies the name of the executable for the library builder.
     Example:

             for Library_Builder use "/.../gprlib";

2.3.1.3 Archive Related Attributes
..................................


   * Archive_Builder

     Specifies the name of the executable of the archive builder with
     the minimum   options, if any. Example:

             for Archive_Builder use ("ar", "cr");

   * Archive_Indexer

     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:

              for Archive_Indexer use ("ranlib");

   * Archive_Suffix

     Specifies the suffix of the archives. If this attribute is not
     specified, then   the suffix of the archives is defaulted to `.a'.
     Example:

             for Archive_Suffix use ".olb"; --  for VMS

   * Library_Partial_Linker

     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:

             for Library_Partial_Linker use ("gcc", "-nostdlib", "-Wl,-r", "-o");

2.3.1.4 Shared Library Related Attributes
.........................................


   * Shared_Library_Prefix

     Specifies the prefix of the file names of shared libraries. When
     this attribute   is not specified, the prefix is `lib'. Example:

             for Shared_Library_Prefix use ""; --  for Windows, if needed

   * Shared_Library_Suffix

     Specifies the suffix of the file names of shared libraries. When
     this attribute   is not specified, the suffix is `.so'. Example:

             for Shared_Library_Suffix use ".dll"; --  for Windows

   * Symbolic_Link_Supported

     Specifies if symbolic links are supported by the platforms. The
     possible values   of this attribute are `"false"' (the default)
     and `"true"'. When this attribute is   not specified, symbolic
     links are not supported.

             for Symbolic_Link_Supported use "true";

   * Library_Major_Minor_ID_Supported

     Specifies if major and minor IDs are supported for shared
     libraries.    The possible values of this attribute are `"false"'
     (the default) and `"true"'.    When this attribute is not
     specified, major and minor IDs are not supported.

             for Library_Major_Minor_ID_Supported use "True";

   * Library_Auto_Init_Supported

     Specifies if library auto initialization is supported. The
     possible values of   this attribute are `"false"' (the default)
     and `"true"'. When this attribute is not   specified, library auto
     initialization is not supported.

             for Library_Auto_Init_Supported use "true";

   * Shared_Library_Minimum_Switches

     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:

             for Shared_Library_Minimum_Switches use  ("-shared");

   * Library_Version_Switches

     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:

             for Library_Version_Switches use ("-Wl,-soname,");

   * Runtime_Library_Dir (<language>)

     Specifies the directory for the runtime libraries for the language.
      Example:

             for Runtime_Library_Dir ("Ada") use "/path/to/adalib";

     This attribute is used by GPRlib to link shared libraries with Ada
     code.

2.3.2 Package Naming
--------------------

Attributes in package `Naming' of a configuration file specify
defaults. These attributes may be used in user project files to replace
these defaults.

   The following attributes usually appear in package `Naming' of a
configuration file:

   * Spec_Suffix (<language>)

     Specifies the default suffix for a "spec" or header file. Examples:

             for Spec_Suffix ("Ada") use ".ads";
             for Spec_Suffix ("C")   use ".h";
             for Spec_Suffix ("C++") use ".hh";

   * Body_Suffix (<language>)

     Specifies the default suffix for a "body" or a source file.
     Examples:

             for Body_Suffix ("Ada") use ".adb";
             for Body_Suffix ("C")   use ".c";
             for Body_Suffix ("C++") use ".cpp";

   * Separate_Suffix

     Specifies the suffix for a subunit source file (separate) in Ada.
     If attribute   `Separate_Suffix' is not specified, then the
     default suffix of subunit source   files is the same as the
     default suffix for body source files. Example:

             for Separate_Suffix use ".sep";

   * Casing

     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
     `"lowercase"', `"UPPERCASE"' and `"Mixedcase"'.    The default,
     when attribute `Casing' 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.

   * Dot_Replacement

     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
     `Dot_Replacement' must be declared.    Example:

             for Dot_Replacement use "-";

2.3.3 Package Builder
---------------------


   * Executable_Suffix

     Specifies the default executable suffix. If no attribute
     `Executable_Suffix' is   declared, then the default executable
     suffix for the host platform is used.    Example:

             for Executable_Suffix use ".exe";

2.3.4 Package Compiler
----------------------



2.3.4.1 General Compilation Attributes
......................................


   * Driver (<language>)

     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.

     Examples:

             for Driver ("C++") use "g++";
             for Driver ("Ada") use "/.../bin/gcc";
             for Driver ("Project file") use "";

   * Required_Switches (<language>)

     Specifies the minimum options that must be used when invoking the
     compiler   of a language. Examples:

             for Required_Switches ("C")   use ("-c", "-x", "c");
             for Required_Switches ("Ada") use ("-c", "-x", "ada", "-gnatA");

   * PIC_Option (<language>)

     Specifies the option or options that must be used when compiling a
     source of   a language to be put in a shared library. Example:

             for PIC_Option ("C") use ("-fPIC");

2.3.4.2 Mapping File Related Attributes
.......................................


   * Mapping_File_Switches (<language>)

     Specifies the switch or switches to be used to specify a mapping
     file to the   compiler. When attribute `Mapping_File_Switches' 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:

             for Mapping_File_Switches ("Ada") use ("-gnatem=");

   * Mapping_Spec_Suffix (<language>)

     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:

              for Mapping_Spec_Suffix ("Ada") use "%s";

   * Mapping_Body_Suffix (<language>)

     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:

              for Mapping_Spec_Suffix ("Ada") use "%b";

2.3.4.3 Config File Related Attributes
......................................

In the value of config file attributes defined below, there are some
placeholders that GPRbuild will replace. These placeholders are:

   * %u : the unit name

   * %f : the file name of the source

   * %s : the spec suffix

   * %b : the body suffix

   * %c : the casing

   * %d : the dot replacement string


Attributes:

   * Config_File_Switches (<language>)

     Specifies the switch or switches to be used to specify a
     configuration file to   the compiler. When attribute
     `Config_File_Switches' 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:

             for Config_File_Switches ("Ada") use ("-gnatec=");

   * Config_Body_File_Name (<language>)

     Specifies the line to be put in a config file to indicate the file
     name of a   body. Example:

             for Config_Body_File_Name ("Ada") use
                 "pragma Source_File_Name_Project (%u, Body_File_Name => ""%f"");";

   * Config_Spec_File_Name (<language>)

     Specifies the line to be put in a config file to indicate the file
     name of a   spec. Example:

             for Config_Spec_File_Name ("Ada") use
                 "pragma Source_File_Name_Project (%u, Spec_File_Name => ""%f"");";

   * Config_Body_File_Name_Pattern (<language>)

     Specifies the line to be put in a config file to indicate a body
     file name   pattern. Example:

             for Config_Body_File_Name_Pattern ("Ada") use
                 "pragma Source_File_Name_Project " &
                 "  (Body_File_Name  => ""*%b""," &
                 "   Casing          => %c," &
                 "   Dot_Replacement => ""%d"");";

   * Config_Spec_File_Name_Pattern (<language>)

     Specifies the line to be put in a config file to indicate a spec
     file name   pattern. Example:

             for Config_Spec_File_Name_Pattern ("Ada") use
                 "pragma Source_File_Name_Project " &
                 "  (Spec_File_Name  => ""*%s""," &
                 "   Casing          => %c," &
                 "   Dot_Replacement => ""%d"");";

   * Config_File_Unique (<language>)

     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: `"true"' or `"false"' (case
     insensitive). The default, when this attribute   is not specified,
     is `"false"'. When the value `"true"' is specified for this
     attribute, GPRbuild will concatenate the config files, if there
     are more than   one. Example:

             for Config_File_Unique ("Ada") use "True";

2.3.4.4 Dependency Related Attributes
.....................................

There are two dependency-related attributes: `Dependency_Switches' and
`Dependency_Driver'. 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.

   * Dependency_Switches (<language>)

     For languages other than Ada, attribute `Dependency_Switches'
     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 `Dependency_Option'   is a string
     list. The name of the dependency file is added to the last string
     in the list, which may be empty. Example:

             for Dependency_Switches ("C") use ("-Wp,-MD,");

     With these `Dependency_Switches', when compiling `file.c' the
     compiler will be   invoked with the option `-Wp,-MD,file.d'.

   * Dependency_Driver (<language>)

     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:

             for Dependency_Driver ("C") use ("gcc", "-E", "-Wp,-M", "");

     Usually, attributes `Dependency_Switches' and `Dependency_Driver'
     are not both   specified.

2.3.4.5 Search Path Related Attributes
......................................


   * Include_Switches (<language>)

     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:

             for Include_Switches ("C") use ("-I");

     Attribute `Include_Switches' is ignored if either one of the
     attributes   `Include_Path' or `Include_Path_File' are specified.

   * Include_Path (<language>)

     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:

             for Include_Path ("C")   use "CPATH";
             for Include_Path ("Ada") use "ADA_INCLUDE_PATH";

     Attribute `Include_Path' is ignored if attribute
     `Include_Path_File' is declared   for the language.

   * Include_Path_File (<language>)

     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:

             for Include_Path_File ("Ada") use "ADA_PRJ_INCLUDE_FILE";

2.3.5 Package Binder
--------------------


   * Driver (<language>)

     Specifies the name of the executable of the binder driver. When
     this attribute   is not specified, there is no binder for the
     language. Example:

             for Driver ("Ada") use "/.../gprbind";

   * Required_Switches (<language>)

     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:

             for Required_Switches ("Ada") use ("--prefix=<prefix>");

   * Prefix (<language>)

     Specifies the prefix to be used in the name of the binder exchange
     file.    Example:

             for Prefix ("C++") use ("c__");

   * Objects_Path (<language>)

     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:

             for Objects_Path ("Ada") use "ADA_OBJECTS_PATH";

   * Objects_Path_File (<language>)

     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:

             for Objects_Path_File ("Ada") use "ADA_PRJ_OBJECTS_FILE";

2.3.6 Package Linker
--------------------


   * Driver

     Specifies the name of the executable of the linker. Example:

             for Driver use "g++";

   * Required_Switches

     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.

   * Map_File_Option

     Specifies the option to be used when the linker is asked to produce
      a map file.

             for Map_File_Option use "-Wl,-Map,";

   * Max_Command_Line_Length

     Specifies the maximum length of the command line to invoke the
     linker.    If this maximum length is reached, a response file will
     be used to shorten   the length of the command line. This is only
     taken into account when   attribute Response_File_Format is
     specified.

             for Max_Command_Line_Length use "8000";

   * Response_File_Format

     Specifies the format of the response file to be generated when the
     maximum   length of the command line to invoke the linker is
     reached. This is only   taken into account when attribute
     Max_Command_Line_Length is specified.

     The allowed case-insensitive values are:

        * "GNU"      Used when the underlying linker is gnu ld.

        * "Object_List"      Used when the response file is a list of
          object files, one per line.

        * "GCC_GNU"      Used with recent version of gcc when the
          underlined linker is gnu ld.

        * "GCC_Object_List"      Used with recent version of gcc when
          the underlying linker is not gnu ld.

             for Response_File_Format use "GCC_GNU";

   * Response_File_Switches   Specifies the option(s) that must precede
     the response file name when   when invoking the linker. This is
     only taken into account when both   attributes
     Max_Command_Line_Length and Response_File_Format are specified.

              for Response_File_Switches  use ("-Wl,-f,");

2.4 Cleaning up with GPRclean
=============================

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 `gprclean proj.gpr' or `gprclean -P proj.gpr'.

   Examples of invocation of GPRclean:

        gprclean -r prj1.gpr
        gprclean -c -P prj2.gpr

2.4.1 Switches for GPRclean
---------------------------

The switches for GPRclean are:

   * `--distributed' : Also clean-up the sources on build slaves, *note
     Distributed compilation::.

   * `--slave-env=name'

     Use name as the slave's environment directory instead of the
     default one.  This options is only used in distributed mode.

   * `--config=<config project file name>' : Specify the
     configuration project file name.

   * `--autoconf=<config project file name>'

     This specifies a configuration project file name that already
     exists or will   be created automatically. Option `--autoconf='
     cannot be specified more than once. If the configuration project
     file   specified with `--autoconf=' exists, then it is used.
     Otherwise,   GPRconfig is invoked to create it automatically.

   * `--target=targetname' : Specify a target for cross platforms.

   * `--db dir' : Parse dir as an additional knowledge base.

   * `--db-' : Do not parse the standard knowledge base.

   * `--RTS=<runtime>' : Use runtime <runtime> for language Ada.

   * `--RTS:<lang>=<runtime>' : Use runtime <runtime>   for language
     <lang>.

   * `--subdirs=<dir>' : Real object, library or exec directories are
     subdirectories <dir> of the specified ones.

   * `--unchecked-shared-lib-imports' : Shared library projects may
     import any project.

   * `-aP<dir>' : Add directory <dir> to the project search path.

   * `-c' : Only delete compiler-generated files. Do not delete
     executables and libraries.

   * `-eL' : Follow symbolic links when processing project files.

   * `-f' : Force deletions of unwritable files.

   * `-F' : Display full project path name in brief error messages.

   * `-h' : Display the usage.

   * `-n' : Do not delete files, only list files that would be deleted.

   * `-P<proj>' : Use Project File _<proj>_.

   * `-q' : Be quiet/terse. There is no output, except to report
     problems.

   * `-r' : (recursive) Clean all projects referenced by the main
     project directly or indirectly. Without this switch, GPRclean only
      cleans the main project.

   * `-v' : Verbose mode.

   * `-vPx' : Specify verbosity when parsing Project Files.    x = 0
     (default), 1 or 2.

   * `-Xnm=val' : Specify an external reference for Project Files.


2.5 Installing with GPRinstall
==============================

The GPRinstall tool installs projects. With GPRinstall it is not needed
to create complex `makefiles' to install the components. This also
removes the need for OS specific commands (like `cp', `mkdir' on UNIXs)
and so makes the installation process easier on all supported platforms.

   After building a project it is often needed to install the project to
make it accessible to other projects. GPRinstall installs only what is
necessary and nothing more. That is for a library projects the library
itself is installed with the corresponding ALI files for Ada sources.
But the object code is not installed as not needed. Also if the Ada
specs are installed the bodies are not as not needed in most cases. The
cases where the bodies are required (if the spec has inline routines or
is a generic) are properly detected by GPRinstall.

   Furthermore, we can note that GPRinstall handles the pre-processed
sources. So it installs the correct variant of the source after
resolving the pre-processing directives.

   The parts of a project that can be installed are:

   * sources of a project

   * a static or shared library built from a library project

   * objects built from a standard project

   * executables built from a standard project


   Moreover, GPRinstall will create, when needed, a project to use the
installed sources, objects or library. By default, this project file is
installed in the GPRbuild's default path location so that it can be
"with"ed easily without further configuration. The installation process
keeps record of every file installed for easy and safe removal.

   At a minimum, to invoke GPRinstall you must specify a main project
file in a command such as `gprinstall proj.gpr' or `gprinstall -P
proj.gpr'.

   Examples of invocation of GPRinstall:

        gprinstall prj1.gpr
        gprinstall -r --prefix=/my/root/install -P prj2.gpr

   GPRinstall will record the installation under the _install name_
which is by default the name of the project without the extension. That
is above the project install names are `prj1' and `prj2'.

   The installation name can be specified with the option
`--install-name'. This makes it possible to record the installation of
multiple projects under the same name. This is handy if an application
comes with a library and a set of tools built with multiple projects.
In this case we may want to record the installation under the same name.

   Examples of installation under the same name:

        gprinstall --install-name=myapp lib.gpr
        gprinstall --install-name=myapp --mode=usage tools/tools.gpr

   Note the `--mode=usage' option above. This tells GPRinstall to only
install the executable built as part of the project.

   It is possible to uninstall a project by using the `--uninstall'
option. In this case we just pass the install name to GPRinstall:

        gprinstall --uninstall prj1
        gprinstall --uninstall prj2

   And both `lib.gpr' and `tools.gpr' above will be uninstalled with:

        gprinstall --uninstall myapp

   Note that GPRinstall does not deal with dependencies between
projects.

2.5.1 Switches for GPRinstall
-----------------------------

The switches for GPRinstall are:

   * `--config=<main config project file name>' : Specify the
     configuration project file name

   * `--autoconf=<config project file name>' :

     This specifies a configuration project file name that already
     exists or will   be created automatically. Option `--autoconf='
     cannot be specified more than once. If the configuration project
     file   specified with `--autoconf=' exists, then it is used.
     Otherwise,   GPRconfig is invoked to create it automatically.

   * `--build-name' : Specify under which name the current project
     build must be installed. The default value is `default'. Using
     this option it is possible to install different builds (using
     different configuration, options, etc...) of the same project. The
     given name will be used by client to select which build they want
     to use (link against).

   * `--build-var' : Specify the name of the build variable in the
     installed project. The default value being `<PROJECT_NAME>_BUILD'.

   * `--dry-run' : Install nothing, just display the actions that would
     have been done.

   * `-a' : Install all sources and not only the interface sources

   * `-f' : Force overwriting of existing files

   * `-h' : Display this message

   * `--mode=[dev/usage]' : Specify the installation mode.

    `dev'
          For this mode the binaries (built libraries and executable)
          are installed together with the sources to use them.

    `usage'
          For this mode only the binaries are installed and no project
          are created.


   * `-p, --create-missing-dirs' : Create missing directories in the
     installation location.

   * `-P<proj>' : Specify the project file to install.

   * `--prefix=path' : Specify the location of the installation. If not
     specified, the default location for the current compiler is used.
     That is, `path' corresponds to parent directory where `gprinstall'
     is found.

   * `--install-name=name' : Specify the name to use for recording the
     installation. The default is the project name without the
     extension.

   * `--sources-subdir=path' : Specify the value for the sources
     installation directory if an absolute path. Otherwise it is
     appended to the prefix above. The default is
     `include/<projet_name>[.<build-name>]'

   * `--lib-subdir=path' : Specify the value for the library and object
     installation directory if an absolute path. Otherwise it is
     appended to the prefix above. The default is
     `lib/<projet_name>[.<build-name>]'

   * `--link-lib-subdir=path' : Specify the value for the library
     symlink directory if an absolute path. Otherwise it is appended to
     the prefix above.

   * `---exec-subdir=path' : Specify the value for the executables
     installation directory if an absolute path. Otherwise it is
     appended to the prefix above. The default is `bin'.

   * `--project-subdir=path' : Specify the value for the project
     installation directory if an absolute path. Otherwise it is
     appended to the prefix above. The default is `share/gpr'.

   * `--target=targetname' : Specify a target for cross platforms.

   * `--no-lib-link' : Disable copy of shared libraries into the
     executable directory on Windows or creation of symlink in the lib
     directory on UNIX. This is done by default to place the shared
     libraries into a directory where application will look for them.

   * `--subdirs=<subdir>'

     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. It is
     expected that the sub-dir option value here is the one used with
     gprbuild.

   * `-q' : Be quiet/terse. There is no output, except to report
     problems.

   * `-r' : (recursive) Install all projects referenced by the main
     project directly or indirectly. Without this switch, GPRinstall
     only   installs the main project.

   * `--uninstall' : Uninstall mode, files installed for a given
     project or install name will be removed. A check is done that no
     manual changes have been applied to the files before removing.
     Deletion of the files can be forced in this case by using the `-f'
     option.

   * `--list' : List mode, displays all the installed packaged.

   * `--stat' : Apply to list mode above, displays also some statistics
     about the installed packages : number of files, total size used on
     disk, and whether there is some files missing.

   * `-v'  : Verbose mode

   * `-Xnm=val' : Specify an external reference for Project Files.


2.6 Distributed compilation
===========================

2.6.1 Introduction to distributed compilation
---------------------------------------------

For large projects the compilation time can become a limitation in the
development cycle. To cope with that, GPRbuild supports distributed
compilation.

   In the distributed mode, the local machine (called the build master)
compile locally but also sends compilation requests to some remote
machines (called the build slaves). The compilation process can use one
or more build slaves. Once the compilation phase is done, the build
master will conduct the binding and linking phases locally.

2.6.2 Setup build environments
------------------------------

The configuration process to be able to use the distributed compilation
support is the following:

   * Setup sources sharing

     There is two ways for the slaves to get access to the sources of
     the project:

        * rsync

          This is the default protocol use. In this case the build
          slaves must have the rsync tool installed. It is also
          required that the user building have a password-less access
          to the machine by installing the proper RSA public key on the
          build slaves. This is also a way to control who can access
          such or such build slaves.

          In this mode, the build slaves will get a copy of the project
          sources locally.  At the end of the compilation the
          compilation artifacts (object code) will be synchronized back
          to the build master for the binding and linking phases.

          Note that the local copy of the sources is kept after the
          compilation is over. This means that the second time a
          project is compiled only the new or changed sources are
          copied. This incremental synchronization done by `rsync' is
          really welcome on large project.

        * gpr

          There is no external tools to install. This is using the
          GPRbuild internal protocol which communicates directly with
          the slaves.


     Note that different slaves can use different protocols.

     An optional port number can be specified at the end of the slave,
     for example: `gpr://comp2.mydomain.com:9876'. The same port number
     must then be specified on the command line of `gprslave'.

   * Optionaly add a Remote package in the main project file

     This Remote package is to be placed into the project file that is
     passed to GPRbuild to build the application.

     The Root_Dir default value is the project's directory. This
     attribute designates the sources root directory. That is, the
     directory from which all the sources are to be found to build the
     application. If the project passed to GPRbuild to build the
     application is not at the top-level directory but in a direct
     sub-directory the Remote package should be:

            package Remote is
               for Root_Dir use "..";
            end Remote;

   * Launch a slave driver on each build slave

     The build master will communicate with each build slave with a
     specific driver in charge of running the compilation process and
     returning statuses. This driver is `gprslave', *note GPRslave::.

     The requirement for the slaves are:

        * The same build environment must be setup (same compiler
          version).

        * The same libraries must be installed. That is, if the GNAT
          project makes use of external libraries the corresponding C
          headers or Ada units must be installed on the remote slaves.

     When all the requirement are set, just launch the slave driver:

            $ gprslave


   When all this is done, the remote compilation can be used simply by
running GPRbuild in distributed mode from the build master:

       $ gprbuild --distributed=gpr://comp1.xyz.com,comp2.xyz.com prj.gpr

   The build slaves are specified as URL with the following form:

     [protocol://]<machine_name>[:port]

   Where protocol is `rsync' or `gpr' as described above. And the
default protocol is `rsync'.

2.6.3 GPRslave
--------------

This is the slave driver in charge of running the compilation jobs as
request by the build master. One instance of this tool must be launched
in each build slaves referenced in the project file.

   Compilations for a specific project is conducted under a
sub-directory from where the slave is launched by default. This can be
overriden with the `-d' option below.

   The current options are:

   * `-v, --verbose' : Activate the verbose mode

   * `-vv, --debug' : Activate the debug mode (very verbose)

   * `-h, --help' : Display the usage

   * `-d, --directory=' : Set the work directory for the slave. This is
     where the sources will be copied and where the compilation will
     take place. A sub-directory will be created for each root project
     built.

   * `-jN, --jobs=N' : set the maximum simultaneous compilation

     The default for N is the number of cores.

   * `-p, --port=N' : Set the port the slave will listen to

     The default value is 8484. The same port must be specified for the
     build slaves on `GPRbuild' command line.


Appendix A GNU Free Documentation License
*****************************************

Version 1.1, March 2000

Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

0. PREAMBLE
===========

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.

   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.

   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.

1. APPLICABILITY AND DEFINITIONS
================================

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

   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.

   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.

   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.

   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.

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

   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.

   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.

2. VERBATIM COPYING
===================

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.

   You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

3. COPYING IN QUANTITY
======================

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.

   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.

   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.

   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.

4. MODIFICATIONS
================

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:
  A. 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.

  B. 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).

  C. State on the Title page the name of the publisher of the
     Modified Version, as the publisher.

  D. Preserve all the copyright notices of the Document.

  E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.

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

  G. Preserve in that license notice the full lists of Invariant
     Sections    and required Cover Texts given in the Document's
     license notice.

  H. Include an unaltered copy of this License.

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

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

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

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

  M. Delete any section entitled "Endorsements".  Such a section    may
     not be included in the Modified Version.

  N. Do not retitle any existing section as "Endorsements"    or to
     conflict in title with any Invariant Section.

   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.

   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.

   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.

   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.

5. COMBINING DOCUMENTS
======================

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.

   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.

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

   Heading 6. COLLECTIONS OF DOCUMENTS

   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.

   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.

7. AGGREGATION WITH INDEPENDENT WORKS
=====================================

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.

   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.

8. TRANSLATION
==============

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.

9. TERMINATION
==============

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.

10. FUTURE REVISIONS OF THIS LICENSE
====================================

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

   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.

ADDENDUM: How to use this License for your documents
====================================================

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:

     Copyright (c)  YEAR  YOUR NAME.
     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".

   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.

   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.

Index
*****



--batch for gprconfig:                         See 2.2.4.    (line 5573)
--config for gprconfig:                        See 2.2.4.    (line 5532)
--db for gprconfig:                            See 2.2.4.    (line 5588)
--show-target for gprconfig:                   See 2.2.4.    (line 5527)
--target for gprconfig:                        See 2.2.4.    (line 5511)
-h for gprconfig:                              See 2.2.4.    (line 5595)
-o for gprconfig:                              See 2.2.4.    (line 5579)
-v option (for GPRbuild):                      See 1.2.6.    (line  659)
-X:                                            See 1.4.      (line 1290)
ADA_PROJECT_PATH:                              See 1.3.1.    (line 1039)
Artifacts:                                     See 1.2.10.   (line  921)
Body:                                          See 1.2.9.    (line  886)
Body_Suffix:                                   See 1.2.9.    (line  823)
case construction:                             See 1.4.      (line 1323)
Casing:                                        See 1.2.9.    (line  773)
command line length:                           See 1.2.5.    (line  494)
Default_Switches:                              See 1.2.5.    (line  553)
Dot_Replacement:                               See 1.2.9.    (line  782)
Excluded_Source_Dirs:                          See 1.2.1.    (line  247)
Excluded_Source_Files <1>:                     See 1.6.      (line 1879)
Excluded_Source_Files:                         See 1.2.1.    (line  339)
Excluded_Source_List_File <1>:                 See 1.6.      (line 1879)
Excluded_Source_List_File:                     See 1.2.1.    (line  339)
Exec_Dir:                                      See 1.2.3.    (line  423)
Executable:                                    See 1.2.7.    (line  670)
Executable_Suffix:                             See 1.2.7.    (line  685)
extends all:                                   See 1.6.1.    (line 1939)
External:                                      See 1.7.5.    (line 2303)
external:                                      See 1.4.      (line 1305)
Externally_Built:                              See 1.3.1.    (line  997)
Free Documentation License, GNU:               See Appendix A.
                                                             (line 7337)
Global_Compilation_Switches <1>:               See 1.7.6.    (line 2365)
Global_Compilation_Switches:                   See 1.3.4.    (line 1246)
Global_Config_File:                            See 1.7.6.    (line 2453)
Global_Configuration_Pragmas <1>:              See 1.7.6.    (line 2443)
Global_Configuration_Pragmas:                  See 1.3.4.    (line 1238)
GNU Free Documentation License:                See Appendix A.
                                                             (line 7337)
GPR_PROJECT_PATH:                              See 1.3.1.    (line 1039)
GPR_PROJECT_PATH_FILE:                         See 1.3.1.    (line 1039)
gprconfig, external values:                    See 2.2.6.3.  (line 5866)
Ignore_Source_Sub_Dirs:                        See 1.2.1.    (line  253)
Implementation:                                See 1.2.9.    (line  886)
Implementation_Exceptions:                     See 1.2.9.    (line  889)
Implementation_Suffix:                         See 1.2.9.    (line  823)
Languages:                                     See 1.2.1.    (line  293)
Leading_Library_Options:                       See 1.5.1.    (line 1503)
Library_ALI_Dir:                               See 1.5.1.    (line 1460)
Library_Auto_Init:                             See 1.5.3.    (line 1670)
Library_Dir <1>:                               See 1.5.3.    (line 1684)
Library_Dir:                                   See 1.5.1.    (line 1413)
Library_GCC:                                   See 1.5.1.    (line 1491)
Library_Interface:                             See 1.5.3.    (line 1622)
Library_Kind:                                  See 1.5.1.    (line 1438)
Library_Name:                                  See 1.5.1.    (line 1404)
Library_Options:                               See 1.5.1.    (line 1499)
Library_Reference_Symbol_File:                 See 1.5.3.    (line 1747)
Library_Src_Dir:                               See 1.5.3.    (line 1697)
Library_Standalone:                            See 1.5.3.    (line 1643)
Library_Symbol_File:                           See 1.5.3.    (line 1754)
Library_Symbol_Policy:                         See 1.5.3.    (line 1709)
Library_Version:                               See 1.5.1.    (line 1469)
License, GNU Free Documentation:               See Appendix A.
                                                             (line 7337)
Linker_Options:                                See 1.5.1.    (line 1507)
Local_Configuration_Pragmas:                   See 1.2.5.    (line  602)
Locally_Removed_Files:                         See 1.2.1.    (line  339)
Main:                                          See 1.2.4.    (line  458)
Naming scheme:                                 See 1.2.1.    (line  301)
Object_Dir:                                    See 1.2.3.    (line  394)
portability:                                   See 1.2.1.    (line  233)
Prefix:                                        See 1.2.10.   (line  927)
project file packages:                         See 1.2.5.    (line  512)
project path:                                  See 1.3.1.    (line 1031)
project qualifier:                             See 1.3.3.    (line 1216)
Project_Files:                                 See 1.7.5.    (line 2189)
Project_Path:                                  See 1.7.5.    (line 2234)
Root_Dir:                                      See 1.2.11.   (line  955)
scenarios:                                     See 1.4.      (line 1285)
Separate_Suffix:                               See 1.2.9.    (line  858)
Source directories:                            See 1.2.1.    (line  213)
Source directories, recursive:                 See 1.2.1.    (line  245)
Source_Dirs:                                   See 1.2.1.    (line  217)
Source_Files:                                  See 1.2.1.    (line  310)
Source_List_File:                              See 1.2.1.    (line  327)
Spec:                                          See 1.2.9.    (line  868)
Spec_Suffix:                                   See 1.2.9.    (line  801)
Specification:                                 See 1.2.9.    (line  868)
Specification_Exceptions:                      See 1.2.9.    (line  889)
Specification_Suffix:                          See 1.2.9.    (line  801)
standalone libraries:                          See 1.5.3.    (line 1598)
Switches <1>:                                  See 1.7.6.    (line 2349)
Switches:                                      See 1.2.5.    (line  570)
typed variable:                                See 1.4.      (line 1323)
Table of Contents
*****************

GPRBUILD User's Guide
1 GNAT Project Manager
  1.1 Introduction
  1.2 Building With Projects
    1.2.1 Source Files and Directories
    1.2.2 Duplicate Sources in Projects
    1.2.3 Object and Exec Directory
    1.2.4 Main Subprograms
    1.2.5 Tools Options in Project Files
    1.2.6 Compiling with Project Files
    1.2.7 Executable File Names
    1.2.8 Avoid Duplication With Variables
    1.2.9 Naming Schemes
    1.2.10 Installation
    1.2.11 Distributed support
  1.3 Organizing Projects into Subsystems
    1.3.1 Project Dependencies
    1.3.2 Cyclic Project Dependencies
    1.3.3 Sharing Between Projects
    1.3.4 Global Attributes
  1.4 Scenarios in Projects
  1.5 Library Projects
    1.5.1 Building Libraries
    1.5.2 Using Library Projects
    1.5.3 Stand-alone Library Projects
    1.5.4 Installing a library with project files
  1.6 Project Extension
    1.6.1 Project Hierarchy Extension
  1.7 Aggregate Projects
    1.7.1 Building all main programs from a single project tree
    1.7.2 Building a set of projects with a single command
    1.7.3 Define a build environment
    1.7.4 Performance improvements in builder
    1.7.5 Syntax of aggregate projects
    1.7.6 package Builder in aggregate projects
  1.8 Aggregate Library Projects
    1.8.1 Building aggregate library projects
    1.8.2 Syntax of aggregate library projects
  1.9 Project File Reference
    1.9.1 Project Declaration
    1.9.2 Qualified Projects
    1.9.3 Declarations
    1.9.4 Packages
    1.9.5 Expressions
    1.9.6 External Values
    1.9.7 Typed String Declaration
    1.9.8 Variables
    1.9.9 Case Constructions
    1.9.10 Attributes
      1.9.10.1 Project Level Attributes
      1.9.10.2 Package Binder Attributes
      1.9.10.3 Package Builder Attributes
      1.9.10.4 Package Check Attributes
      1.9.10.5 Package Clean Attributes
      1.9.10.6 Package Compiler Attributes
      1.9.10.7 Package Cross_Reference Attributes
      1.9.10.8 Package Eliminate Attributes
      1.9.10.9 Package Finder Attributes
      1.9.10.10 Package gnatls Attributes
      1.9.10.11 Package gnatstub Attributes
      1.9.10.12 Package IDE Attributes
      1.9.10.13 Package Install Attributes
      1.9.10.14 Package Linker Attributes
      1.9.10.15 Package Metrics Attribute
      1.9.10.16 Package Naming Attributes
      1.9.10.17 Package Pretty_Printer Attributes
      1.9.10.18 Package Remote Attributes
      1.9.10.19 Package Stack Attributes
      1.9.10.20 Package Synchronize Attributes
2 Gprbuild
  2.1 Building with GPRbuild
    2.1.1 Command Line
    2.1.2 Switches
    2.1.3 Initialization
    2.1.4 Compilation of one or several sources
    2.1.5 Compilation Phase
    2.1.6 Post-Compilation Phase
    2.1.7 Linking Phase
    2.1.8 Incompatibilities with gnatmake
  2.2 Configuring with GPRconfig
    2.2.1 Configuration
    2.2.2 Using GPRconfig
    2.2.3 Description
    2.2.4 Command line arguments
    2.2.5 Interactive use
    2.2.6 The GPRconfig knowledge base
      2.2.6.1 General file format
      2.2.6.2 Compiler description
      2.2.6.3 GPRconfig external values
      2.2.6.4 GPRconfig variable substitution
      2.2.6.5 Configurations
  2.3 Configuration File Reference
    2.3.1 Project Level Configuration Attributes
      2.3.1.1 General Attributes
      2.3.1.2 General Library Related Attributes
      2.3.1.3 Archive Related Attributes
      2.3.1.4 Shared Library Related Attributes
    2.3.2 Package Naming
    2.3.3 Package Builder
    2.3.4 Package Compiler
      2.3.4.1 General Compilation Attributes
      2.3.4.2 Mapping File Related Attributes
      2.3.4.3 Config File Related Attributes
      2.3.4.4 Dependency Related Attributes
      2.3.4.5 Search Path Related Attributes
    2.3.5 Package Binder
    2.3.6 Package Linker
  2.4 Cleaning up with GPRclean
    2.4.1 Switches for GPRclean
  2.5 Installing with GPRinstall
    2.5.1 Switches for GPRinstall
  2.6 Distributed compilation
    2.6.1 Introduction to distributed compilation
    2.6.2 Setup build environments
    2.6.3 GPRslave
Appendix A GNU Free Documentation License
Index


