aboutsummaryrefslogtreecommitdiffstats
path: root/gcc-4.9/gcc/ada/projects.texi
diff options
context:
space:
mode:
Diffstat (limited to 'gcc-4.9/gcc/ada/projects.texi')
-rw-r--r--gcc-4.9/gcc/ada/projects.texi5086
1 files changed, 5086 insertions, 0 deletions
diff --git a/gcc-4.9/gcc/ada/projects.texi b/gcc-4.9/gcc/ada/projects.texi
new file mode 100644
index 000000000..e23f9fadd
--- /dev/null
+++ b/gcc-4.9/gcc/ada/projects.texi
@@ -0,0 +1,5086 @@
+@set gprconfig GPRconfig
+
+@c ------ projects.texi
+@c Copyright (C) 2002-2013, Free Software Foundation, Inc.
+@c This file is shared between the GNAT user's guide and gprbuild. It is not
+@c compilable on its own, you should instead compile the other two manuals.
+@c For that reason, there is no toplevel @menu
+
+@c ---------------------------------------------
+@node GNAT Project Manager
+@chapter GNAT Project Manager
+@c ---------------------------------------------
+
+@noindent
+@menu
+* Introduction::
+* Building With Projects::
+* Organizing Projects into Subsystems::
+* Scenarios in Projects::
+* Library Projects::
+* Project Extension::
+* Aggregate Projects::
+* Aggregate Library Projects::
+* Project File Reference::
+@end menu
+
+@c ---------------------------------------------
+@node Introduction
+@section Introduction
+@c ---------------------------------------------
+
+@noindent
+This chapter describes GNAT's @emph{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:
+
+@itemize @bullet
+@item The directory or set of directories containing the source files, and/or the
+ names of the specific source files themselves
+@item The directory in which the compiler's output
+ (@file{ALI} files, object files, tree files, etc.) is to be placed
+@item The directory in which the executable programs are to be placed
+@item ^Switch^Switch^ settings for any of the project-enabled tools;
+ you can apply these settings either globally or to individual compilation units.
+@item The source files containing the main subprogram(s) to be built
+@item The source programming language(s)
+@item Source file naming conventions; you can specify these either globally or for
+ individual compilation units (@pxref{Naming Schemes}).
+@item Change any of the above settings depending on external values, thus enabling
+ the reuse of the projects in various @b{scenarios} (@pxref{Scenarios in Projects}).
+@item Automatically build libraries as part of the build process
+ (@pxref{Library Projects}).
+
+@end itemize
+
+@noindent
+Project files are written in a syntax close to that of Ada, using familiar
+notions such as packages, context clauses, declarations, default values,
+assignments, and inheritance (@pxref{Project File Reference}).
+
+Project files can be built hierarchically from other project files, simplifying
+complex system integration and project reuse (@pxref{Organizing Projects into
+Subsystems}).
+
+@itemize @bullet
+@item 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^switch^ settings) used for different subsystems.
+@item 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
+ (@pxref{Project Extension}).
+
+@end itemize
+
+@noindent
+Several tools support project files, generally in addition to specifying
+the information on the command line itself). They share common switches
+to control the loading of the project (in particular
+@option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
+@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{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:
+
+@itemize @bullet
+@item Using a common set of source files and generating object files in different
+ directories via different ^switch^switch^ settings. It can be used for instance, for
+ generating separate sets of object files for debugging and for production.
+@item 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
+@end itemize
+
+@noindent
+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.
+
+@c ---------------------------------------------
+@node Building With Projects
+@section Building With Projects
+@c ---------------------------------------------
+
+@noindent
+In its simplest form, a unique project is used to build a single executable.
+This section concentrates on such a simple setup. Later sections will extend
+this basic model to more complex setups.
+
+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.
+
+@table @asis
+@item @b{Project file}:
+ A text file using an Ada-like syntax, generally using the @file{.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.
+
+@item @b{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. @xref{Attributes}.
+
+@item @b{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 @code{Builder}, @code{Compiler}, @code{Binder},
+ and @code{Linker}. @xref{Packages}.
+
+@item @b{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.
+ @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
+
+@item @b{Source files} and @b{source directories}:
+ A source file is associated with a language through a naming convention. For
+ instance, @code{foo.c} is typically the name of a C source file;
+ @code{bar.ads} or @code{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 @xref{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 @b{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 @b{Source_Files} or
+ @b{Source_List_File} attributes. Note that those last two attributes only
+ accept basenames with no directory information.
+
+@item @b{Object files} and @b{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
+ @b{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
+
+@end table
+
+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 @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
+the @file{common/} directory. The file @file{proc.adb} contains an Ada main
+subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
+these source files with the ^switch^switch^
+@option{^-O2^-O2^}, and put the resulting files in
+the directory @file{obj/}.
+
+@smallexample
+@group
+^common/^[COMMON]^
+ pack.ads
+ pack.adb
+ proc.adb
+@end group
+@group
+^common/release/^[COMMON.RELEASE]^
+ proc.ali, proc.o pack.ali, pack.o
+@end group
+@end smallexample
+
+@noindent
+Our project is to be called @emph{Build}. The name of the
+file is the name of the project (case-insensitive) with the
+@file{.gpr} extension, therefore the project file name is @file{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:
+
+@smallexample
+@b{project} Build @b{is}
+@b{end} Build;
+@end smallexample
+
+@menu
+* Source Files and Directories::
+* Duplicate Sources in Projects::
+* Object and Exec Directory::
+* Main Subprograms::
+* Tools Options in Project Files::
+* Compiling with Project Files::
+* Executable File Names::
+* Avoid Duplication With Variables::
+* Naming Schemes::
+* Installation::
+* Distributed support::
+@end menu
+
+@c ---------------------------------------------
+@node Source Files and Directories
+@subsection Source Files and Directories
+@c ---------------------------------------------
+
+@noindent
+When you create a new project, the first thing to describe is how to find the
+corresponding source files. This is the only settings that are needed by all
+the tools that will use this project (builder, compiler, binder and linker for
+the compilation, IDEs to edit the source files,@dots{}).
+
+@cindex Source directories
+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 @file{common} directory is the only source directory.
+
+@cindex @code{Source_Dirs}
+There are several ways of defining source directories:
+
+@itemize @bullet
+@item When the attribute @b{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 @file{build.gpr} is placed in the @file{common}
+ directory, the project has the needed implicit source directory.
+
+@item The attribute @b{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 @file{"/usr/local/common/"} on UNIX), or relative to the
+ directory in which the project file resides (for instance "." if
+ @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
+ Each of the source directories must exist and be readable.
+
+@cindex portability
+ 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 "\".
+
+@item The attribute @b{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 @emph{"**"}, then that path and all its subdirectories
+ (recursively) are included in the list of source directories. For instance,
+ @file{**} and @file{./**} represent the complete directory tree rooted at ".".
+@cindex Source directories, recursive
+
+@cindex @code{Excluded_Source_Dirs}
+ When using that construct, it can sometimes be convenient to also use the
+ attribute @b{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.
+
+@cindex @code{Ignore_Source_Sub_Dirs}
+ 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
+ @b{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple
+ file names for the roots of these undesirable directory subtrees.
+
+@smallexample
+ @b{for} Source_Dirs @b{use} ("./**");
+ @b{for} Ignore_Source_Sub_Dirs @b{use} (".svn");
+@end smallexample
+
+@end itemize
+
+@noindent
+When applied to the simple example, and because we generally prefer to have
+the project file at the toplevel directory rather than mixed with the sources,
+we will create the following file
+
+@smallexample
+ build.gpr
+ @b{project} Build @b{is}
+ @b{for} Source_Dirs @b{use} ("common"); -- <<<<
+ @b{end} Build;
+@end smallexample
+
+@noindent
+Once source directories have been specified, one may need to indicate
+source files of interest. By default, all source files present in the source
+directories are considered by the project manager. When this is not desired,
+it is possible to specify the list of sources to consider explicitly.
+In such a case, only source file base names are indicated and not
+their absolute or relative path names. The project manager is in charge of
+locating the specified source files in the specified source directories.
+
+@itemize @bullet
+@item 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.
+
+@cindex @code{Languages}
+ However, when compiling a multi-language application, or a pure C
+ application, the project manager must be told which languages are of
+ interest, which is done by setting the @b{Languages} attribute to a list of
+ strings, each of which is the name of a language. Tools like
+ @command{gnatmake} only know about Ada, while other tools like
+ @command{gprbuild} know about many more languages such as C, C++, Fortran,
+ assembly and others can be added dynamically.
+
+@cindex Naming scheme
+ 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 (@pxref{Naming Schemes}). The default is the
+ standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
+ specs), which is what is used in our example, explaining why no naming scheme
+ is explicitly specified.
+ @xref{Naming Schemes}.
+
+@item @code{Source_Files}
+@cindex @code{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 @b{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.
+
+@item 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
+ @pxref{Organizing Projects into Subsystems}. To do this, the attribute
+ @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
+ @emph{Source_Dirs} can be set to the empty list, with the same
+ result.
+
+@item @code{Source_List_File}
+@cindex @code{Source_List_File}
+ If there is a great number of files, it might be more convenient to use
+ the attribute @b{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 @emph{Source_Files}. Such a file can easily be created through
+ external tools.
+
+ A warning is issued if both attributes @code{Source_Files} and
+ @code{Source_List_File} are given explicit values. In this case, the
+ attribute @code{Source_Files} prevails.
+
+@item @code{Excluded_Source_Files}
+@cindex @code{Excluded_Source_Files}
+@cindex @code{Locally_Removed_Files}
+@cindex @code{Excluded_Source_List_File}
+ Specifying an explicit list of files is not always convenient.It might be
+ more convenient to use the default search rules with specific exceptions.
+ This can be done thanks to the attribute @b{Excluded_Source_Files}
+ (or its synonym @b{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,
+ @xref{Project Extension}. A similar attribute
+ @b{Excluded_Source_List_File} plays the same
+ role but takes the name of file containing file names similarly to
+ @code{Source_List_File}.
+
+@end itemize
+
+@noindent
+In most simple cases, such as the above example, the default source file search
+behavior provides the expected result, and we do not need to add anything after
+setting @code{Source_Dirs}. The project manager automatically finds
+@file{pack.ads}, @file{pack.adb} and @file{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.
+
+@c ---------------------------------------------
+@node Duplicate Sources in Projects
+@subsection Duplicate Sources in Projects
+@c ---------------------------------------------
+
+@noindent
+If the order of the source directories is known statically, that is if
+@code{"/**"} is not used in the string list @code{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
+@code{"/**"} is used in the string list @code{Source_Dirs}, it is an error
+to have several files with the same source file name in the same directory
+@code{"/**"} subtree, since there would be an ambiguity as to which one should
+be used. However, two files with the same source file name may 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 @code{"/**"}
+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.
+
+@c ---------------------------------------------
+@node Object and Exec Directory
+@subsection Object and Exec Directory
+@c ---------------------------------------------
+
+@noindent
+The next step when writing a project is to indicate where the compiler should
+put the object files. In fact, the compiler and other tools might create
+several different kind of files (for GNAT, there is the object file and the ALI
+file for instance). One of the important concepts in projects is that most
+tools may consider source directories as read-only and do not attempt to create
+new or temporary files there. Instead, all files are created in the object
+directory. It is of course not true for project-aware IDEs, whose purpose it is
+to create the source files.
+
+@cindex @code{Object_Dir}
+The object directory is specified through the @b{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 @code{^-p^/CREATE_MISSING_DIRS^} for @command{gnatmake}
+and @command{gprbuild}).
+
+If the attribute @code{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:
+
+@smallexample
+ @b{project} Build @b{is}
+ @b{for} Source_Dirs @b{use} ("common");
+ @b{for} Object_Dir @b{use} "obj"; -- <<<<
+ @b{end} Build;
+@end smallexample
+
+@noindent
+As mentioned earlier, there is a single object directory per project. As a
+result, if you have an existing system where the object files are spread in
+several directories, you can either move all of them into the same directory if
+you want to build it with a single project file, or study the section on
+subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
+separate object directory can be associated with one of the subsystem
+constituting the application.
+
+When the @command{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.
+
+@cindex @code{Exec_Dir}
+This can be done through the @code{Exec_Dir} attribute, which, like
+@emph{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 @emph{Object_Dir} nor
+@emph{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 @file{build.gpr}. Hence
+the project file is now
+
+@smallexample
+ @b{project} Build @b{is}
+ @b{for} Source_Dirs @b{use} ("common");
+ @b{for} Object_Dir @b{use} "obj";
+ @b{for} Exec_Dir @b{use} "."; -- <<<<
+ @b{end} Build;
+@end smallexample
+
+@c ---------------------------------------------
+@node Main Subprograms
+@subsection Main Subprograms
+@c ---------------------------------------------
+
+@noindent
+In the previous section, executables were mentioned. The project manager needs
+to be taught what they are. In a project file, an executable is indicated by
+pointing to source file of the main subprogram. In C this is the file that
+contains the @code{main} 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 @command{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.
+
+@cindex @code{Main}
+The list of main files is specified via the @b{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
+@command{GPS} will be able to create extra menus to spawn or debug the
+corresponding executables.
+
+@smallexample
+ @b{project} Build @b{is}
+ @b{for} Source_Dirs @b{use} ("common");
+ @b{for} Object_Dir @b{use} "obj";
+ @b{for} Exec_Dir @b{use} ".";
+ @b{for} Main @b{use} ("proc.adb"); -- <<<<
+ @b{end} Build;
+@end smallexample
+
+@noindent
+If this attribute is defined in the project, then spawning the builder
+with a command such as
+
+@smallexample
+ gnatmake ^-Pbuild^/PROJECT_FILE=build^
+@end smallexample
+
+@noindent
+automatically builds all the executables corresponding to the files
+listed in the @emph{Main} attribute. It is possible to specify one
+or more executables on the command line to build a subset of them.
+
+@c ---------------------------------------------
+@node Tools Options in Project Files
+@subsection Tools Options in Project Files
+@c ---------------------------------------------
+
+@noindent
+We now have a project file that fully describes our environment, and can be
+used to build the application with a simple @command{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 @file{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.
+
+@cindex command line length
+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.
+
+@cindex project file packages
+A project file is subdivided into zero or more @b{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 (@pxref{Packages}), and the contents
+of packages are limited to a small set of constructs and attributes
+(@pxref{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.
+
+@smallexample
+ @b{project} Build @b{is}
+ @b{for} Source_Dirs @b{use} ("common");
+ @b{for} Object_Dir @b{use} "obj";
+ @b{for} Exec_Dir @b{use} ".";
+ @b{for} Main @b{use} ("proc.adb");
+
+ @b{package} Builder @b{is} --<<< for gnatmake and gprbuild
+ @b{end} Builder;
+
+ @b{package} Compiler @b{is} --<<< for the compiler
+ @b{end} Compiler;
+
+ @b{package} Binder @b{is} --<<< for the binder
+ @b{end} Binder;
+
+ @b{package} Linker @b{is} --<<< for the linker
+ @b{end} Linker;
+ @b{end} Build;
+@end smallexample
+
+@noindent
+Let's first examine the compiler switches. As stated in the initial description
+of the example, we want to compile all files with @option{^-O2^-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^switches^:
+
+@table @asis
+@item @b{Default_Switches}:
+@cindex @code{Default_Switches}
+ This is the first mention in this manual of an @b{indexed attribute}. When
+ this attribute is defined, one must supply an @emph{index} in the form of a
+ literal string.
+ In the case of @emph{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^switch^
+ @option{^-O2^-O2^}, and the resulting project file is as follows
+ (only the @code{Compiler} package is shown):
+
+ @smallexample
+ @b{package} Compiler @b{is}
+ @b{for} Default_Switches ("Ada") @b{use} ("^-O2^-O2^");
+ @b{end} Compiler;
+ @end smallexample
+
+@item @b{^Switches^Switches^}:
+@cindex @code{^Switches^Switches^}
+ in some cases, we might want to use specific ^switches^switches^
+ for one or more files. For instance, compiling @file{proc.adb} might not be
+ possible at high level of optimization because of a compiler issue.
+ In such a case, the @emph{^Switches^Switches^}
+ attribute (indexed on the file name) can be used and will override the
+ switches defined by @emph{Default_Switches}. Our project file would
+ become:
+
+ @smallexample
+ package Compiler is
+ for Default_Switches ("Ada")
+ use ("^-O2^-O2^");
+ for ^Switches^Switches^ ("proc.adb")
+ use ("^-O0^-O0^");
+ end Compiler;
+ @end smallexample
+
+ @noindent
+ @code{^Switches^Switches^} may take a pattern as an index, such as in:
+
+ @smallexample
+ package Compiler is
+ for Default_Switches ("Ada")
+ use ("^-O2^-O2^");
+ for ^Switches^Switches^ ("pkg*")
+ use ("^-O0^-O0^");
+ end Compiler;
+ @end smallexample
+
+ @noindent
+ Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with ^-O0^-O0^,
+ not ^-O2^-O2^.
+
+ @noindent
+ @code{^Switches^Switches^} can also be given a language name as index instead of a file
+ name in which case it has the same semantics as @emph{Default_Switches}.
+ However, indexes with wild cards are never valid for language name.
+
+@item @b{Local_Configuration_Pragmas}:
+@cindex @code{Local_Configuration_Pragmas}
+ this attribute may specify the path
+ of a file containing configuration pragmas for use by the Ada compiler,
+ such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
+ used for all the sources of the project.
+
+@end table
+
+The switches for the other tools are defined in a similar manner through the
+@b{Default_Switches} and @b{^Switches^Switches^} attributes, respectively in the
+@emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
+the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
+package (for linking executables).
+
+@c ---------------------------------------------
+@node Compiling with Project Files
+@subsection Compiling with Project Files
+@c ---------------------------------------------
+
+@noindent
+Now that our project files are written, let's build our executable.
+Here is the command we would use from the command line:
+
+@smallexample
+ gnatmake ^-Pbuild^/PROJECT_FILE=build^
+@end smallexample
+
+@noindent
+This will automatically build the executables specified through the
+@emph{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.
+
+@command{gnatmake} only knows how to handle Ada files. By using
+@command{gprbuild} as a builder, you could automatically manage C files the
+same way: create the file @file{utils.c} in the @file{common} directory,
+set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
+
+@smallexample
+ gprbuild ^-Pbuild^/PROJECT_FILE=build^
+@end smallexample
+
+@noindent
+Gprbuild knows how to recompile the C files and will
+recompile them only if one of their dependencies has changed. No direct
+indication on how to build the various elements is given in the
+project file, which describes the project properties rather than a
+set of actions to be executed. Here is the invocation of
+@command{gprbuild} when building a multi-language program:
+
+@smallexample
+$ gprbuild -Pbuild
+gcc -c proc.adb
+gcc -c pack.adb
+gcc -c utils.c
+gprbind proc
+...
+gcc proc.o -o proc
+@end smallexample
+
+@noindent
+Notice the three steps described earlier:
+
+@itemize @bullet
+@item The first three gcc commands correspond to the compilation phase.
+@item The gprbind command corresponds to the post-compilation phase.
+@item The last gcc command corresponds to the final link.
+
+@end itemize
+
+@noindent
+@cindex @option{-v} option (for GPRbuild)
+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 @command{gprbuild} command by cut-and-pasting its output.
+GPRbuild's option @code{-v} provides a much more verbose output which includes,
+among other information, more complete compilation, post-compilation and link
+commands.
+
+@c ---------------------------------------------
+@node Executable File Names
+@subsection Executable File Names
+@c ---------------------------------------------
+
+@noindent
+@cindex @code{Executable}
+By default, the executable name corresponding to a main file is
+computed from the main source file name. Through the attribute
+@b{Builder.Executable}, it is possible to change this default.
+
+For instance, instead of building @command{proc} (or @command{proc.exe}
+on Windows), we could configure our project file to build "proc1"
+(resp proc1.exe) with the following addition:
+
+@smallexample @c projectfile
+ project Build is
+ ... -- same as before
+ package Builder is
+ for Executable ("proc.adb") use "proc1";
+ end Builder
+ end Build;
+@end smallexample
+
+@noindent
+@cindex @code{Executable_Suffix}
+Attribute @b{Executable_Suffix}, when specified, may change the suffix
+of the executable files, when no attribute @code{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 @option{-o}. When several mains are defined in the project,
+it is not possible to use the @option{-o} switch and the only way to change the
+names of the executable is provided by Attributes @code{Executable} and
+@code{Executable_Suffix}.
+
+@c ---------------------------------------------
+@node Avoid Duplication With Variables
+@subsection Avoid Duplication With Variables
+@c ---------------------------------------------
+
+@noindent
+To illustrate some other project capabilities, here is a slightly more complex
+project using similar sources and a main program in C:
+
+@smallexample @c projectfile
+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^-gnaty^");
+ for ^Switches^Switches^ ("main.c") use C_Switches & ("-g");
+ end Compiler;
+end C_Main;
+@end smallexample
+
+@noindent
+This project has many similarities with the previous one.
+As expected, its @code{Main} attribute now refers to a C source.
+The attribute @emph{Exec_Dir} is now omitted, thus the resulting
+executable will be put in the directory @file{obj}.
+
+The most noticeable difference is the use of a variable in the
+@emph{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 (@pxref{Scenarios in
+Projects}).
+
+In this example, we see how the file @file{main.c} can be compiled with
+the switches used for all the other C files, plus @option{-g}.
+In this specific situation the use of a variable could have been
+replaced by a reference to the @code{Default_Switches} attribute:
+
+@smallexample @c projectfile
+ for ^Switches^Switches^ ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
+@end smallexample
+
+@noindent
+Note the tick (@emph{'}) used to refer to attributes defined in a package.
+
+Here is the output of the GPRbuild command using this project:
+
+@smallexample
+$gprbuild -Pc_main
+gcc -c -pedantic -g main.c
+gcc -c -gnaty proc.adb
+gcc -c -gnaty pack.adb
+gcc -c -pedantic utils.c
+gprbind main.bexch
+...
+gcc main.o -o main
+@end smallexample
+
+@noindent
+The default switches for Ada sources,
+the default switches for C sources (in the compilation of @file{lib.c}),
+and the specific switches for @file{main.c} have all been taken into
+account.
+
+@c ---------------------------------------------
+@node Naming Schemes
+@subsection Naming Schemes
+@c ---------------------------------------------
+
+@noindent
+Sometimes an Ada software system is ported from one compilation environment to
+another (say GNAT), and the file are not named using the default GNAT
+conventions. Instead of changing all the file names, which for a variety of
+reasons might not be possible, you can define the relevant file naming scheme
+in the @b{Naming} 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 @code{Naming}:
+
+@table @asis
+@item @b{Casing}:
+@cindex @code{Casing}
+ Its value must be one of @code{"lowercase"} (the default if
+ unspecified), @code{"uppercase"} or @code{"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 @file{my_unit.adb} (lowercase),
+ @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
+ On Windows, file names are case insensitive, so this attribute is
+ irrelevant.
+
+@item @b{Dot_Replacement}:
+@cindex @code{Dot_Replacement}
+ This attribute specifies the string that should replace the "." in unit
+ names. Its default value is @code{"-"} so that a unit
+ @code{Parent.Child} is expected to be found in the file
+ @file{parent-child.adb}. The replacement string must satisfy the following
+ requirements to avoid ambiguities in the naming scheme:
+
+ @itemize -
+ @item It must not be empty
+ @item It cannot start or end with an alphanumeric character
+ @item It cannot be a single underscore
+ @item It cannot start with an underscore followed by an alphanumeric
+ @item It cannot contain a dot @code{'.'} except if the entire string
+ is @code{"."}
+
+ @end itemize
+
+@item @b{Spec_Suffix} and @b{Specification_Suffix}:
+@cindex @code{Spec_Suffix}
+@cindex @code{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 @code{Spec} or
+ @code{Specification_Exceptions}.
+
+ If @code{Spec_Suffix ("Ada")} is not specified, then the default is
+ @code{"^.ads^.ADS^"}.
+
+ A non empty value must satisfy the following requirements:
+
+ @itemize -
+ @item It must include at least one dot
+ @item If @code{Dot_Replacement} is a single dot, then it cannot include
+ more than one dot.
+ @end itemize
+
+@item @b{Body_Suffix} and @b{Implementation_Suffix}:
+@cindex @code{Body_Suffix}
+@cindex @code{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 @code{Body} or
+ @code{Implementation_Exceptions}.
+
+ These attributes must satisfy the same requirements as @code{Spec_Suffix}.
+ In addition, they must be different from any of the values in
+ @code{Spec_Suffix}.
+ If @code{Body_Suffix ("Ada")} is not specified, then the default is
+ @code{"^.adb^.ADB^"}.
+
+ If @code{Body_Suffix ("Ada")} and @code{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 @code{Body_Suffix ("Ada")}
+ or a spec if the longest suffix is @code{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 @code{Makefile.in}, a file called @file{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).
+
+@item @b{Separate_Suffix}:
+@cindex @code{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 @code{Body_Suffix ("Ada")}.
+
+ The value of this attribute cannot be the empty string.
+
+ Otherwise, the same rules apply as for the
+ @code{Body_Suffix} attribute. The only accepted index is "Ada".
+
+@item @b{Spec} or @b{Specification}:
+@cindex @code{Spec}
+@cindex @code{Specification}
+ This attribute @code{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
+
+ @smallexample @c projectfile
+ for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
+ for Spec ("top") use "foo.a" at 1;
+ for Spec ("foo") use "foo.a" at 2;
+ @end smallexample
+
+@item @b{Body} or @b{Implementation}:
+@cindex @code{Body}
+@cindex @code{Implementation}
+ These attribute play the same role as @emph{Spec} for Ada bodies.
+
+@item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
+@cindex @code{Specification_Exceptions}
+@cindex @code{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.
+
+@end table
+
+@ifclear vms
+For example, the following package models the Apex file naming rules:
+
+@smallexample @c projectfile
+@group
+ 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;
+@end group
+@end smallexample
+@end ifclear
+
+@ifset vms
+For example, the following package models the DEC Ada file naming rules:
+
+@smallexample @c projectfile
+@group
+ package Naming is
+ for Casing use "lowercase";
+ for Dot_Replacement use "__";
+ for Spec_Suffix ("Ada") use "_.ada";
+ for Body_Suffix ("Ada") use ".ada";
+ end Naming;
+@end group
+@end smallexample
+
+@noindent
+(Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
+names in lower case)
+@end ifset
+
+@c ---------------------------------------------
+@node Installation
+@subsection Installation
+@c ---------------------------------------------
+
+@noindent
+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 @command{gprinstall} tool provides an easy way to install
+libraries, executable or object code generated during the build. The
+@b{Install} package can be used to change the default locations.
+
+The following attributes can be defined in package @code{Install}:
+
+@table @asis
+
+@item @b{Active}
+
+Whether the project is to be installed, values are @code{true}
+(default) or @code{false}.
+
+@item @b{Artifacts}
+@cindex @code{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.
+
+@item @b{Prefix}:
+@cindex @code{Prefix}
+
+Root directory for the installation.
+
+@item @b{Exec_Subdir}
+
+Subdirectory of @b{Prefix} where executables are to be
+installed. Default is @b{bin}.
+
+@item @b{Lib_Subdir}
+
+Subdirectory of @b{Prefix} where directory with the library or object
+files is to be installed. Default is @b{lib}.
+
+@item @b{Sources_Subdir}
+
+Subdirectory of @b{Prefix} where directory with sources is to be
+installed. Default is @b{include}.
+
+@item @b{Project_Subdir}
+
+Subdirectory of @b{Prefix} where the generated project file is to be
+installed. Default is @b{share/gpr}.
+@end table
+
+@c ---------------------------------------------
+@node Distributed support
+@subsection Distributed support
+@c ---------------------------------------------
+
+@noindent
+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 @code{Remote}:
+
+@table @asis
+
+@item @b{Root_Dir}:
+@cindex @code{Root_Dir}
+
+Root directory of the project's sources. The default value is the
+project's directory.
+
+@end table
+
+@c ---------------------------------------------
+@node Organizing Projects into Subsystems
+@section Organizing Projects into Subsystems
+@c ---------------------------------------------
+
+@noindent
+A @b{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 @code{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.
+
+@menu
+* Project Dependencies::
+* Cyclic Project Dependencies::
+* Sharing Between Projects::
+* Global Attributes::
+@end menu
+
+@c ---------------------------------------------
+@node Project Dependencies
+@subsection Project Dependencies
+@c ---------------------------------------------
+
+@noindent
+GtkAda comes with its own project file (appropriately called
+@file{gtkada.gpr}), and we will assume we have already built a project
+called @file{logging.gpr} for the logging module. With the information provided
+so far in @file{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 @b{with} clauses at the beginning
+of our project:
+
+@smallexample @c projectfile
+ with "gtkada.gpr";
+ with "a/b/logging.gpr";
+ project Build is
+ ... -- as before
+ end Build;
+@end smallexample
+
+@noindent
+@cindex @code{Externally_Built}
+When such a project is compiled, @command{gnatmake} will automatically
+check the other projects and recompile their sources when needed. It will also
+recompile the sources from @code{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 @b{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 @code{with} clause has several effects. It provides source
+visibility between projects during the compilation process. It also guarantees
+that the necessary object files from @code{Logging} and @code{GtkAda} are
+available when linking @code{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 @code{with} clause identifies
+project files rather than packages.
+
+Each literal string after @code{with} is the path
+(absolute or relative) to a project file. The @code{.gpr} extension is
+optional, although we recommend adding it. If no extension is specified,
+and no project file with the @file{^.gpr^.GPR^} extension is found, then
+the file is searched for exactly as written in the @code{with} clause,
+that is with no extension.
+
+As mentioned above, the path after a @code{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
+(@pxref{Aggregate Projects}).
+
+@cindex project path
+When a relative path or a base name is used, the
+project files are searched relative to each of the directories in the
+@b{project path}. 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:
+
+@itemize @bullet
+@item First, the file is searched relative to the directory that contains the
+ current project file.
+
+@item
+@cindex @code{GPR_PROJECT_PATH_FILE}
+@cindex @code{GPR_PROJECT_PATH}
+@cindex @code{ADA_PROJECT_PATH}
+ Then it is searched relative to all the directories specified in the
+ ^environment variables^logical names^ @b{GPR_PROJECT_PATH_FILE},
+ @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH} (in that order) if they exist.
+ The value of @b{GPR_PROJECT_PATH_FILE}, when defined, is the path name of
+ a text file that contains project directory path names, one per line.
+ @b{GPR_PROJECT_PATH} and @b{ADA_PROJECT_PATH}, when defined, contain
+ project directory path names separated by directory separators.
+ @b{ADA_PROJECT_PATH} is used for compatibility, it is recommended to
+ use @b{GPR_PROJECT_PATH_FILE} or @b{GPR_PROJECT_PATH}.
+
+@item 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:
+
+ @itemize @bullet
+ @item @file{<prefix>/<target>/lib/gnat}
+ (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
+ @option{--target} is specified)
+ @item @file{<prefix>/<target>/share/gpr}
+ (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
+ @option{--target} is specified)
+ @item @file{<prefix>/share/gpr/}
+ (for @command{gnatmake} and @command{gprbuild})
+ @item @file{<prefix>/lib/gnat/}
+ (for @command{gnatmake} and @command{gprbuild})
+ @end itemize
+
+ In our example, @file{gtkada.gpr} is found in the predefined directory if
+ it was installed at the same root as GNAT.
+@end itemize
+
+@noindent
+Some tools also support extending the project path from the command line,
+generally through the @option{-aP}. You can see the value of the project
+path by using the @command{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 @code{A} imports @code{B}, which imports @code{C}, the sources of
+@code{A} may depend on the sources of @code{C}, even if @code{A} does not
+import @code{C} explicitly. However, this is not recommended, because if
+and when @code{B} ceases to import @code{C}, some sources in @code{A} will
+no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
+that will report such indirect dependencies.
+
+One very important aspect of a project hierarchy is that
+@b{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 @code{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.
+
+@c ---------------------------------------------
+@node Cyclic Project Dependencies
+@subsection Cyclic Project Dependencies
+@c ---------------------------------------------
+
+@noindent
+Cyclic dependencies are mostly forbidden:
+if @code{A} imports @code{B} (directly or indirectly) then @code{B}
+is not allowed to import @code{A}. However, there are cases when cyclic
+dependencies would be beneficial. For these cases, another form of import
+between projects exists: the @b{limited with}. A project @code{A} that
+imports a project @code{B} with a straight @code{with} may also be imported,
+directly or indirectly, by @code{B} through a @code{limited with}.
+
+The difference between straight @code{with} and @code{limited with} is that
+the name of a project imported with a @code{limited with} cannot be used in the
+project importing it. In particular, its packages cannot be renamed and
+its variables cannot be referred to.
+
+@smallexample @c 0projectfile
+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;
+@end smallexample
+
+@c ---------------------------------------------
+@node Sharing Between Projects
+@subsection Sharing Between Projects
+@c ---------------------------------------------
+
+@noindent
+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 (@pxref{Tools Options in Project Files}), setting compilation
+switches for all sources of a subsystem is simple: it is just a matter of
+adding a @code{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:
+
+@itemize @bullet
+@item Since @file{build.gpr} imports @file{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:
+
+ @smallexample @c projectfile
+ project Logging is
+ package Compiler is
+ for ^Switches^Switches^ ("Ada")
+ use ("^-O2^-O2^");
+ end Compiler;
+ package Binder is
+ for ^Switches^Switches^ ("Ada")
+ use ("-E");
+ end Binder;
+ end Logging;
+
+ with "logging.gpr";
+ project Build is
+ package Compiler renames Logging.Compiler;
+ package Binder is
+ for ^Switches^Switches^ ("Ada") use Logging.Binder'Switches ("Ada");
+ end Binder;
+ end Build;
+ @end smallexample
+
+ @noindent
+ The solution used for @code{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:
+
+ @smallexample @c projectfile
+ with "imported";
+ project Main is
+ Var1 := Imported.Var;
+ end Main;
+ @end smallexample
+
+@item 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 @file{shared.gpr}.
+
+ @smallexample @c projectfile
+ abstract project Shared is
+ for Source_Files use (); -- no sources
+ package Compiler is
+ for ^Switches^Switches^ ("Ada")
+ use ("^-O2^-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;
+ @end smallexample
+
+ @noindent
+ As for the first example, we could have chosen to set the attributes
+ one by one rather than to rename a package. The reason we explicitly
+ indicate that @code{Shared} has no sources is so that it can be created
+ in any directory and we are sure it shares no sources with @code{Build}
+ or @code{Logging}, which of course would be invalid.
+
+@cindex project qualifier
+ Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
+ This qualifier is optional, but helps convey the message that we do not
+ intend this project to have sources (@pxref{Qualified Projects} for
+ more qualifiers).
+@end itemize
+
+@c ---------------------------------------------
+@node Global Attributes
+@subsection Global Attributes
+@c ---------------------------------------------
+
+@noindent
+We have already seen many examples of attributes used to specify a special
+option of one of the tools involved in the build process. Most of those
+attributes are project specific. That it to say, they only affect the invocation
+of tools on the sources of the project where they are defined.
+
+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:
+
+@table @asis
+@item @b{Builder.Global_Configuration_Pragmas}:
+@cindex @code{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
+ @code{Compiler.Local_Configuration_Pragmas} attribute.
+
+@item @b{Builder.Global_Compilation_Switches}:
+@cindex @code{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 @code{Compiler} package, which only apply to
+ the sources of the corresponding project. This attribute is indexed on
+ the name of the language.
+
+@end table
+
+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.
+
+@c ---------------------------------------------
+@node Scenarios in Projects
+@section Scenarios in Projects
+@c ---------------------------------------------
+
+@noindent
+Various aspects of the projects can be modified based on @b{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 @option{-g} as compiler switches in debug mode and @option{^-O2^-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
+@file{build_debug.gpr} and @file{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.
+
+@cindex scenarios
+Instead, project files support the notion of scenarios controlled
+by external values. Such values can come from several sources (in decreasing
+order of priority):
+
+@table @asis
+@item @b{Command line}:
+@cindex @option{-X}
+ When launching @command{gnatmake} or @command{gprbuild}, the user can pass
+ extra @option{-X} switches to define the external value. In
+ our case, the command line might look like
+
+ @smallexample
+ gnatmake -Pbuild.gpr -Xmode=debug
+ or gnatmake -Pbuild.gpr -Xmode=release
+ @end smallexample
+
+@item @b{^Environment variables^Logical names^}:
+ When the external value does not come from the command line, it can come from
+ the value of ^environment variables^logical names^ of the appropriate name.
+ In our case, if ^an environment variable^a logical name^ called "mode"
+ exist, its value will be taken into account.
+
+@item @b{External function second parameter}
+
+@end table
+
+@cindex @code{external}
+We now need to get that value in the project. The general form is to use
+the predefined function @b{external} which returns the current value of
+the external. For instance, we could setup the object directory to point to
+either @file{obj/debug} or @file{obj/release} by changing our project to
+
+@smallexample @c projectfile
+ project Build is
+ for Object_Dir use "obj/" & external ("mode", "debug");
+ ... -- as before
+ end Build;
+@end smallexample
+
+@noindent
+The second parameter to @code{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.
+
+@cindex typed variable
+@cindex case construction
+A @b{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 @b{case construction} and create conditional
+sections in the project. The following example shows how this can be done:
+
+@smallexample @c projectfile
+ 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^Switches^ ("Ada")
+ use ("-g");
+ when "release" =>
+ for ^Switches^Switches^ ("Ada")
+ use ("^-O2^-O2^");
+ end case;
+ end Compiler;
+ end Build;
+@end smallexample
+
+@noindent
+The project has suddenly grown in size, but has become much more flexible.
+@code{Mode_Type} defines the only valid values for the @code{mode} variable. If
+any other value is read from the environment, an error is reported and the
+project is considered as invalid.
+
+The @code{Mode} variable is initialized with an external value
+defaulting to @code{"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 (@code{with} clauses), which may not depend on a scenario.
+
+Scenarios work the same way with @b{project hierarchies}: you can either
+duplicate a variable similar to @code{Mode} in each of the project (as long
+as the first argument to @code{external} is always the same and the type is
+the same), or simply set the variable in the @file{shared.gpr} project
+(@pxref{Sharing Between Projects}).
+
+@c ---------------------------------------------
+@node Library Projects
+@section Library Projects
+@c ---------------------------------------------
+
+@noindent
+So far, we have seen examples of projects that create executables. However,
+it is also possible to create libraries instead. A @b{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 @b{static}
+and @b{dynamic} libraries. They also support the concept of @b{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
+@file{ALI} files to the specified location).
+
+@menu
+* Building Libraries::
+* Using Library Projects::
+* Stand-alone Library Projects::
+* Installing a library with project files::
+@end menu
+
+@c ---------------------------------------------
+@node Building Libraries
+@subsection Building Libraries
+@c ---------------------------------------------
+
+@noindent
+Let's enhance our example and transform the @code{logging} subsystem into a
+library. In order to do so, a few changes need to be made to @file{logging.gpr}.
+A number of specific attributes needs to be defined: at least @code{Library_Name}
+and @code{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 @code{library} in
+front of the @code{project} keyword.
+
+@table @asis
+@item @b{Library_Name}:
+@cindex @code{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.
+
+@item @b{Library_Dir}:
+@cindex @code{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 @code{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.
+
+@end table
+
+Here is the new version of @file{logging.gpr} that makes it a library:
+
+@smallexample @c projectfile
+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;
+@end smallexample
+
+@noindent
+Once the above two attributes are defined, the library project is valid and
+is enough for building a library with default characteristics.
+Other library-related attributes can be used to change the defaults:
+
+@table @asis
+@item @b{Library_Kind}:
+@cindex @code{Library_Kind}
+ The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
+ @code{"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
+ @file{.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.
+
+@cindex @code{Library_ALI_Dir}
+@item @b{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
+ @code{Library_Dir} directory, but as for the executables where we have a
+ separate @code{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 @code{Library_Dir} attribute apply.
+
+@cindex @code{Library_Version}
+@item @b{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 @code{"soname"}). If the library file name (built
+ from the @code{Library_Name}) is different from the @code{Library_Version},
+ then the library file will be a symbolic link to the actual file whose name
+ will be @code{Library_Version}. This follows the usual installation schemes
+ for dynamic libraries on many Unix systems.
+
+@smallexample @c projectfile
+@group
+ 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;
+@end group
+@end smallexample
+
+ @noindent
+ After the compilation, the directory @file{lib} will contain both a
+ @file{libdummy.so.1} library and a symbolic link to it called
+ @file{libdummy.so}.
+
+@cindex @code{Library_GCC}
+@item @b{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).
+
+@item @b{Library_Options}:
+@cindex @code{Library_Options}
+ This attribute may be used to specify additional switches (last switches)
+ when linking a shared library.
+
+@item @b{Leading_Library_Options}:
+@cindex @code{Leading_Library_Options}
+ This attribute, that is taken into account only by @command{gprbuild}, may be
+ used to specified leading options (first switches) when linking a shared
+ library.
+
+@cindex @code{Linker_Options}
+@item @b{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 @code{Linker.Switches}
+ defined in the main project. This is useful when a particular subsystem
+ depends on an external library: adding this dependency as a
+ @code{Linker_Options} in the project of the subsystem is more convenient than
+ adding it to all the @code{Linker.Switches} of the main projects that depend
+ upon this subsystem.
+@end table
+
+@c ---------------------------------------------
+@node Using Library Projects
+@subsection Using Library Projects
+@c ---------------------------------------------
+
+@noindent
+When the builder detects that a project file is a library project file, it
+recompiles all sources of the project that need recompilation and rebuild the
+library if any of the sources have been recompiled. It then groups all object
+files into a single file, which is a shared or a static library. This library
+can later on be linked with multiple executables. Note that the use
+of shard libraries reduces the size of the final executable and can also reduce
+the memory footprint at execution time when the library is shared among several
+executables.
+
+It is also possible to build @b{multi-language libraries}. When using
+@command{gprbuild} as a builder, multi-language library projects allow naturally
+the creation of multi-language libraries . @command{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: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
+@file{log2.adb}. If @file{log1.adb} has been modified, then the library
+@file{liblogging} will be rebuilt when compiling all the sources of
+@code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
+include a @code{"with Log1"}.
+
+To ensure that all the sources in the @code{Logging} library are
+up to date, and that all the sources of @code{Build} are also up to date,
+the following two commands needs to be used:
+
+@smallexample
+gnatmake -Plogging.gpr
+gnatmake -Pbuild.gpr
+@end smallexample
+
+@noindent
+All @file{ALI} files will also be copied from the object directory to the
+library directory. To build executables, @command{gnatmake} will use the
+library rather than the individual object files.
+
+@ifclear vms
+Library projects can also be useful to describe a library that need to be used
+but, for some reason, cannot be rebuilt. For instance, it is the case when some
+of the library sources are not available. Such library projects need simply to
+use the @code{Externally_Built} attribute as in the example below:
+
+@smallexample @c projectfile
+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;
+@end smallexample
+
+@noindent
+In the case of externally built libraries, the @code{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 @code{Linker.Linker_Options} or @code{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 @code{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 @code{with} clause, which in turn will trigger the builder to find
+the proper order of libraries in the final link command.
+@end ifclear
+
+@c ---------------------------------------------
+@node Stand-alone Library Projects
+@subsection Stand-alone Library Projects
+@c ---------------------------------------------
+
+@noindent
+@cindex standalone libraries
+A @b{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
+@code{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 @b{Library_Interface}, in addition
+to the two attributes that make a project a Library Project
+(@code{Library_Name} and @code{Library_Dir}). This third attribute may also be
+@b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada
+and takes a list of units as parameter. @b{Interfaces} works for any supported
+language and takes a list of sources as parameter.
+
+@table @asis
+@item @b{Library_Interface}:
+@cindex @code{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 @code{Library_Interface}. Other sources are
+ considered implementation units.
+
+@smallexample @c projectfile
+@group
+ for Library_Dir use "lib";
+ for Library_Name use "loggin";
+ for Library_Interface use ("lib1", "lib2"); -- unit names
+@end group
+@end smallexample
+
+@item @b{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 @code{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.
+
+@item @b{Library_Standalone}:
+@cindex @code{Library_Standalone}
+ This attribute defines the kind of standalone library to
+ build. Values are either @code{standard} (the default), @code{no} or
+ @code{encapsulated}. When @code{standard} is used the code to elaborate and
+ finalize the library is embedded, when @code{encapsulated} is used the
+ library can furthermore only depends on static libraries (including
+ the GNAT runtime). This attribute can be set to @code{no} to make it clear
+ that the library should not be standalone in which case the
+ @code{Library_Interface} should not defined. Note that this attribute
+ only applies to shared libraries, so @code{Library_Kind} must be set
+ to @code{dynamic}.
+
+@smallexample @c projectfile
+@group
+ 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";
+@end group
+@end smallexample
+
+@end table
+
+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^B$LOGGING.ADS/B^ in the example).
+This binder-generated package includes @b{initialization} and @b{finalization}
+procedures whose names depend on the library name (@code{logginginit} and
+@code{loggingfinal} in the example). The object corresponding to this package is
+included in the library.
+
+@table @asis
+@item @b{Library_Auto_Init}:
+@cindex @code{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 @b{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.
+
+@item @b{Library_Dir}:
+@cindex @code{Library_Dir}
+ For a stand-alone library, only the @file{ALI} files of the interface units
+ (those that are listed in attribute @code{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.
+
+@item @b{Binder.Default_Switches}:
+ When a stand-alone library is bound, the switches that are specified in
+ the attribute @b{Binder.Default_Switches ("Ada")} are
+ used in the call to @command{gnatbind}.
+
+@item @b{Library_Src_Dir}:
+@cindex @code{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 @code{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.
+
+@item @b{Library_Symbol_Policy}:
+@cindex @code{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:
+
+ @itemize -
+ @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
+ @item @code{"compliant"}: if attribute @b{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.
+ @item @code{"controlled"}: the attribute @b{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.
+ @item @code{"restricted"}: The attribute @b{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.
+ @item @code{"direct"}: The attribute @b{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.
+
+ @end itemize
+
+@item @b{Library_Reference_Symbol_File}
+@cindex @code{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.
+
+@item @b{Library_Symbol_File}
+@cindex @code{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.
+@end table
+
+@c ---------------------------------------------
+@node Installing a library with project files
+@subsection Installing a library with project files
+@c ---------------------------------------------
+
+@noindent
+When using project files, a usable version of the library is created in the
+directory specified by the @code{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 @code{externally_built} attribute. @ref{Using Library Projects}
+
+Another option is to use @command{gprinstall} to install the library in a
+different context than the build location. A project to use this library is
+generated automatically by @command{gprinstall} which also copy, in the install
+location, the minimum set of sources needed to use the library.
+@ref{Installation}
+
+@c ---------------------------------------------
+@node Project Extension
+@section Project Extension
+@c ---------------------------------------------
+
+@noindent
+During development of a large system, it is sometimes necessary to use
+modified versions of some of the source files, without changing the original
+sources. This can be achieved through the @b{project extension} facility.
+
+Suppose for instance that our example @code{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 @emph{project extension}. If one project (the ``child'') @emph{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 @code{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 @code{Common}.
+However, the other development branch still needs evolution of @code{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
+@code{Build} from previous examples:
+
+@smallexample @c projectfile
+ project Work extends "../bld/build.gpr" is
+ end Work;
+@end smallexample
+
+@noindent
+The project after @b{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 (@pxref{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 @code{Work} is
+placed). We can already compile that project with
+
+@smallexample
+ gnatmake -Pwork
+@end smallexample
+
+@noindent
+If no sources have been placed in the current directory, this command
+won't do anything, since this project does not change the
+sources it inherited from @code{Build}, therefore all the object files
+in @code{Build} and its dependencies are still valid and are reused
+automatically.
+
+Suppose we now want to supply an alternate version of @file{pack.adb}
+but use the existing versions of @file{pack.ads} and @file{proc.adb}.
+We can create the new file Work's current directory (likely
+by copying the one from the @code{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, @command{gnatmake} will now automatically recompile
+this file (thus creating @file{pack.o} in the current directory) and
+any file that depends on it (thus creating @file{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 @code{base} project would contain the
+sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
+import @code{base} and add @file{pack.adb}. In this scenario, @code{base}
+cannot contain the original version of @file{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 @b{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.
+
+@cindex @code{Excluded_Source_Files}
+@cindex @code{Excluded_Source_List_File}
+For that purpose, the attribute @b{Excluded_Source_Files} is used.
+Its value is a list of file names.
+It is also possible to use attribute @code{Excluded_Source_List_File}.
+Its value is the path of a text file containing one file name per
+line.
+
+@smallexample @c @projectfile
+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;
+@end smallexample
+
+@noindent
+All packages that are not declared in the extending project are inherited from
+the project being extended, with their attributes, with the exception of
+@code{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:
+@code{Languages}, @code{Main} (for a root non library project) and
+@code{Library_Name} (for a project extending a library project)
+
+@menu
+* Project Hierarchy Extension::
+@end menu
+
+@c ---------------------------------------------
+@node Project Hierarchy Extension
+@subsection Project Hierarchy Extension
+@c ---------------------------------------------
+
+@noindent
+One of the fundamental restrictions in project extension is the following:
+@b{A project is not allowed to import directly or indirectly at the same time an
+extending project and one of its ancestors}.
+
+By means of example, consider the following hierarchy of projects.
+
+@smallexample
+ a.gpr contains package A1
+ b.gpr, imports a.gpr and contains B1, which depends on A1
+ c.gpr, imports b.gpr and contains C1, which depends on B1
+@end smallexample
+
+@noindent
+If we want to locally extend the packages @code{A1} and @code{C1}, we need to
+create several extending projects:
+
+@smallexample
+ a_ext.gpr which extends a.gpr, and overrides A1
+ b_ext.gpr which extends b.gpr and imports a_ext.gpr
+ c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
+@end smallexample
+
+@noindent
+@smallexample @c projectfile
+ 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;
+@end smallexample
+
+@noindent
+The extension @file{b_ext.gpr} is required, even though we are not overriding
+any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
+import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
+
+@cindex extends all
+When extending a large system spanning multiple projects, it is often
+inconvenient to extend every project in the hierarchy that is impacted by a
+small change introduced in a low layer. In such cases, it is possible to create
+an @b{implicit extension} of entire hierarchy using @b{extends all}
+relationship.
+
+When the project is extended using @code{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:
+
+@smallexample
+ a_ext.gpr, extends a.gpr and overrides A1
+ c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
+
+@end smallexample
+
+@noindent
+@smallexample @c projectfile
+ 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;
+@end smallexample
+
+@noindent
+When building project @file{c_ext.gpr}, the entire modified project space is
+considered for recompilation, including the sources of @file{b.gpr} that are
+impacted by the changes in @code{A1} and @code{C1}.
+
+@c ---------------------------------------------
+@node Aggregate Projects
+@section Aggregate Projects
+@c ---------------------------------------------
+
+@noindent
+
+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.
+
+@menu
+* Building all main programs from a single project tree::
+* Building a set of projects with a single command::
+* Define a build environment::
+* Performance improvements in builder::
+* Syntax of aggregate projects::
+* package Builder in aggregate projects::
+@end menu
+
+@c -----------------------------------------------------------
+@node Building all main programs from a single project tree
+@subsection Building all main programs from a single project tree
+@c -----------------------------------------------------------
+
+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 @code{with}s the projects for each modules (say B and C),
+which in turn @code{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 @command{gnatmake} or
+@command{gprbuild}, using a syntax similar to
+
+@smallexample
+ gprbuild -PA.gpr
+@end smallexample
+
+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
+@command{gnatmake} commands, one per project, to build all executables.
+This is a little inconvenient, but more importantly is inefficient
+because @command{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
+
+@smallexample
+ gprbuild -PAgg.gpr
+@end smallexample
+
+this will build all mains from A, B and C.
+
+@smallexample @c projectfile
+ aggregate project Agg is
+ for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
+ end Agg;
+@end smallexample
+
+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 @command{gprbuild}, but not with
+@command{gnatmake}.
+
+@c ---------------------------------------------------------
+@node Building a set of projects with a single command
+@subsection Building a set of projects with a single command
+@c ---------------------------------------------------------
+
+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 @command{gprbuild}, you could do
+
+@smallexample
+ gprbuild -PA.gpr
+ gprbuild -PB.gpr
+@end smallexample
+
+to build both. But again, @command{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 @command{gprbuild} command. This also works nicely
+with Annex E.
+
+@c ---------------------------------------------
+@node Define a build environment
+@subsection Define a build environment
+@c ---------------------------------------------
+
+The environment variables at the time you launch @command{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
+
+@smallexample @c projectfile
+ 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^Switches^ ("Ada") use ("-q");
+ end Builder;
+ end Agg;
+@end smallexample
+
+One of the often requested features in projects is to be able to
+reference external variables in @code{with} statements, as in
+
+@smallexample @c projectfile
+ with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
+ project MyProject is
+ ...
+ end MyProject;
+@end smallexample
+
+For various reasons, this isn't authorized. But using aggregate
+projects provide an elegant solution. For instance, you could
+use a project file like:
+
+@smallexample @c projectfile
+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;
+@end smallexample
+
+@c --------------------------------------------
+@node Performance improvements in builder
+@subsection Performance improvements in builder
+@c --------------------------------------------
+
+The loading of aggregate projects is optimized in @command{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, @command{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 @command{gprbuild} and @command{gnatmake} commands in parallel).
+
+@c -------------------------------------
+@node Syntax of aggregate projects
+@subsection Syntax of aggregate projects
+@c -------------------------------------
+
+An aggregate project follows the general syntax of project files. The
+recommended extension is still @file{.gpr}. However, a special
+@code{aggregate} qualifier must be put before the keyword
+@code{project}.
+
+An aggregate project cannot @code{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
+@code{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:
+
+@itemize @bullet
+@item Languages
+@item Source_Files, Source_List_File and other attributes dealing with
+ list of sources.
+@item Source_Dirs, Exec_Dir and Object_Dir
+@item Library_Dir, Library_Name and other library-related attributes
+@item Main
+@item Roots
+@item Externally_Built
+@item Inherit_Source_Path
+@item Excluded_Source_Dirs
+@item Locally_Removed_Files
+@item Excluded_Source_Files
+@item Excluded_Source_List_File
+@item Interfaces
+@end itemize
+
+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:
+
+@table @asis
+@item @b{Project_Files}:
+@cindex @code{Project_Files}
+
+This attribute is compulsory (or else we are not aggregating any project,
+and thus not doing anything). It specifies a list of @file{.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 @code{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 @code{ADA_PROJECT_PATH},
+@code{GPR_PROJECT_PATH} and @code{GPR_PROJECT_PATH_FILE} are not used to find
+the project files. The extension @file{.gpr} is mandatory, since this attribute
+contains file names, not project names.
+
+Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
+latter indicates that any subdirectory (recursively) will be
+searched for matching files. The latter (@code{"**"}) can only occur at the
+last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
+not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
+to starting with @code{"./**"}.
+
+For now, the pattern @code{"*"} 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:
+
+@smallexample @c projectfile
+ 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
+@end smallexample
+
+@item @b{Project_Path}:
+@cindex @code{Project_Path}
+
+This attribute can be used to specify a list of directories in
+which to look for project files in @code{with} statements.
+
+When you specify a project in Project_Files
+say @code{"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 @code{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:
+
+@itemize @bullet
+@item the current directory;
+@item followed by the command line -aP switches;
+@item then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment
+variables;
+@item then the directories from the Project_Path attribute;
+@item and finally the predefined directories.
+@end itemize
+
+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:
+
+@smallexample
+ +---------------+ +----------------+
+ | 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 |
+ +-------+ +---------+
+@end smallexample
+
+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:
+
+@smallexample @c projectfile
+ for Project_Path use ("/usr/local/gpr", "gpr/");
+@end smallexample
+
+@item @b{External}:
+@cindex @code{External}
+
+This attribute can be used to set the value of environment
+variables as retrieved through the @code{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):
+
+@itemize @bullet
+@item An External attribute in aggregate project, for instance
+ @code{for External ("BUILD_MODE") use "DEBUG"};
+
+@item 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.
+
+@item The -X command line switch to @command{gprbuild}
+
+This always takes precedence.
+
+@end itemize
+
+This attribute is only taken into account in the main aggregate
+project (i.e. the one specified on the command line to @command{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.
+
+@end table
+
+@c ----------------------------------------------
+@node package Builder in aggregate projects
+@subsection package Builder in aggregate projects
+@c ----------------------------------------------
+
+As we mentioned before, only the package Builder can be specified in
+an aggregate project. In this package, only the following attributes
+are valid:
+
+@table @asis
+@item @b{^Switches^Switches^}:
+@cindex @code{^Switches^Switches^}
+This attribute gives the list of switches to use for @command{gprbuild}.
+Because no mains can be specified for aggregate projects, the only possible
+index for attribute @code{Switches} is @code{others}. All other indexes will
+be ignored.
+
+Example:
+
+@smallexample @c projectfile
+for ^Switches^Switches^ (other) use ("-v", "-k", "-j8");
+@end smallexample
+
+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.
+
+@item @b{Global_Compilation_Switches}
+@cindex @code{Global_Compilation_Switches}
+
+This attribute gives the list of compiler switches for the various
+languages. For instance,
+
+@smallexample @c projectfile
+for Global_Compilation_Switches ("Ada") use ("^O1^-O1^", "-g");
+for Global_Compilation_Switches ("C") use ("^-O2^-O2^");
+@end smallexample
+
+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:
+
+@smallexample @c projectfile
+ aggregate project Agg is
+ for Project_Files use ("a.gpr", "b.gpr");
+ package Builder is
+ for Global_Compilation_Switches ("Ada") use ("^-O2^-O2^");
+ end Builder;
+ end Agg;
+
+ with "c.gpr";
+ project A is
+ package Builder is
+ for Global_Compilation_Switches ("Ada") use ("^-O1^-O1^");
+ -- ignored
+ end Builder;
+
+ package Compiler is
+ for Default_Switches ("Ada")
+ use ("^-O1^-O1^", "-g");
+ for ^Switches^Switches^ ("a_file1.adb")
+ use ("^-O0^-O0^");
+ end Compiler;
+ end A;
+
+ with "c.gpr";
+ project B is
+ package Compiler is
+ for Default_Switches ("Ada") use ("^-O0^-O0^");
+ end Compiler;
+ end B;
+
+ project C is
+ package Compiler is
+ for Default_Switches ("Ada")
+ use ("^-O3^-O3^",
+ "^-gnatn^-gnatn^");
+ for ^Switches^Switches^ ("c_file1.adb")
+ use ("^-O0^-O0^", "-g");
+ end Compiler;
+ end C;
+@end smallexample
+
+then the following switches are used:
+
+@itemize @bullet
+@item all files from project A except a_file1.adb are compiled
+ with "^-O2^-O2^ -g", since the aggregate project has priority.
+@item the file a_file1.adb is compiled with
+ "^-O0^-O0^", since the Compiler.Switches has priority
+@item all files from project B are compiled with
+ "^-O2^-O2^", since the aggregate project has priority
+@item all files from C are compiled with "^-O2^-O2^ -gnatn", except for
+ c_file1.adb which is compiled with "^-O0^-O0^ -g"
+@end itemize
+
+Even though C is seen through two paths (through A and through
+B), the switches used by the compiler are unambiguous.
+
+@item @b{Global_Configuration_Pragmas}
+@cindex @code{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
+@code{Compiler.Local_Configuration_Pragmas} attribute if they need.
+
+@item @b{Global_Config_File}
+@cindex @code{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.
+
+@end table
+
+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.
+
+@c ---------------------------------------------
+@node Aggregate Library Projects
+@section Aggregate Library Projects
+@c ---------------------------------------------
+
+@noindent
+
+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.
+
+@menu
+* Building aggregate library projects::
+* Syntax of aggregate library projects::
+@end menu
+
+@c ---------------------------------------------
+@node Building aggregate library projects
+@subsection Building aggregate library projects
+@c ---------------------------------------------
+
+For example, we can define an aggregate project Agg that groups A, B
+and C:
+
+@smallexample @c projectfile
+ 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;
+@end smallexample
+
+Then, when you build with:
+
+@smallexample
+ gprbuild agg.gpr
+@end smallexample
+
+This will build all units from projects A, B and C and will create a
+static library named @file{libagg.a} into the @file{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:
+
+@smallexample @c projectfile
+ 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;
+@end smallexample
+
+With the above aggregate library Builder package, the @code{-fPIC}
+option will be passed to the compiler when building any source code
+from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
+
+@c ---------------------------------------------
+@node Syntax of aggregate library projects
+@subsection Syntax of aggregate library projects
+@c ---------------------------------------------
+
+An aggregate library project follows the general syntax of project
+files. The recommended extension is still @file{.gpr}. However, a special
+@code{aggregate library} qualifier must be put before the keyword
+@code{project}.
+
+An aggregate library project cannot @code{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:
+
+@itemize @bullet
+@item Languages
+@item Source_Files, Source_List_File and other attributes dealing with
+ list of sources.
+@item Source_Dirs, Exec_Dir and Object_Dir
+@item Main
+@item Roots
+@item Externally_Built
+@item Inherit_Source_Path
+@item Excluded_Source_Dirs
+@item Locally_Removed_Files
+@item Excluded_Source_Files
+@item Excluded_Source_List_File
+@item Interfaces
+@end itemize
+
+The only package that is authorized (albeit optional) is Builder.
+
+The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
+described the aggregated projects whose object files have to be
+included into the aggregate library. The environment variables
+@code{ADA_PROJECT_PATH}, @code{GPR_PROJECT_PATH} and
+@code{GPR_PROJECT_PATH_FILE} are not used to find the project files.
+
+@c ---------------------------------------------
+@node Project File Reference
+@section Project File Reference
+@c ---------------------------------------------
+
+@noindent
+This section describes the syntactic structure of project files, the various
+constructs that can be used. Finally, it ends with a summary of all available
+attributes.
+
+@menu
+* Project Declaration::
+* Qualified Projects::
+* Declarations::
+* Packages::
+* Expressions::
+* External Values::
+* Typed String Declaration::
+* Variables::
+* Case Constructions::
+* Attributes::
+@end menu
+
+@c ---------------------------------------------
+@node Project Declaration
+@subsection Project Declaration
+@c ---------------------------------------------
+
+@noindent
+Project files have an Ada-like syntax. The minimal project file is:
+
+@smallexample @c projectfile
+@group
+project Empty is
+end Empty;
+@end group
+@end smallexample
+
+@noindent
+The identifier @code{Empty} is the name of the project.
+This project name must be present after the reserved
+word @code{end} at the end of the project file, followed by a semi-colon.
+
+@b{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").
+
+@smallexample
+simple_name ::= identifier
+name ::= simple_name @{ . simple_name @}
+@end smallexample
+
+@noindent
+@b{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).
+
+@b{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: @code{all, at, case, end, for, is,
+limited, null, others, package, renames, type, use, when, with, @b{extends},
+@b{external}, @b{project}}.
+
+@b{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 @b{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 @b{with clauses}, or by @b{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 @b{limited with}.
+@c ??? Need more details here
+
+@smallexample @c projectfile
+with "other_project.gpr";
+project My_Project extends "extended.gpr" is
+end My_Project;
+@end smallexample
+
+@noindent
+These dependencies form a @b{directed graph}, potentially cyclic when using
+@b{limited with}. The subprogram reflecting the @b{extends} relations is a
+tree.
+
+A project's @b{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 @b{project hierarchy} can be created, where projects are children of
+other projects. The name of such a child project must be @code{Parent.Child},
+where @code{Parent} is the name of the parent project. In particular, this
+makes all @code{with} clauses of the parent project automatically visible
+in the child project.
+
+@smallexample
+project ::= context_clause project_declaration
+
+context_clause ::= @{with_clause@}
+with_clause ::= @i{with} path_name @{ , path_name @} ;
+path_name ::= string_literal
+
+project_declaration ::= simple_project_declaration | project_extension
+simple_project_declaration ::=
+ @i{project} @i{<project_>}name @i{is}
+ @{declarative_item@}
+ @i{end} <project_>simple_name;
+@end smallexample
+
+@c ---------------------------------------------
+@node Qualified Projects
+@subsection Qualified Projects
+@c ---------------------------------------------
+
+@noindent
+Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
+is identifiers or reserved words, to qualify the project.
+The current list of qualifiers is:
+
+@table @asis
+@item @b{abstract}: qualifies a project with no sources. Such a
+ project must either have no declaration of attributes @code{Source_Dirs},
+ @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
+ @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
+ as empty. If it extends another project, the project it extends must also be a
+ qualified abstract project.
+@item @b{standard}: a standard project is a non library project with sources.
+ This is the default (implicit) qualifier.
+@item @b{aggregate}: a project whose sources are aggregated from other
+project files.
+@item @b{aggregate library}: a library whose sources are aggregated
+from other project or library project files.
+@item @b{library}: a library project must declare both attributes
+ @code{Library_Name} and @code{Library_Dir}.
+@item @b{configuration}: a configuration project cannot be in a project tree.
+ It describes compilers and other tools to @command{gprbuild}.
+@end table
+
+@c ---------------------------------------------
+@node Declarations
+@subsection Declarations
+@c ---------------------------------------------
+
+@noindent
+Declarations introduce new entities that denote types, variables, attributes,
+and packages. Some declarations can only appear immediately within a project
+declaration. Others can appear within a project or within a package.
+
+@smallexample
+declarative_item ::= simple_declarative_item
+ | typed_string_declaration
+ | package_declaration
+
+simple_declarative_item ::= variable_declaration
+ | typed_variable_declaration
+ | attribute_declaration
+ | case_construction
+ | empty_declaration
+
+empty_declaration ::= @i{null} ;
+@end smallexample
+
+@noindent
+An empty declaration is allowed anywhere a declaration is allowed. It has
+no effect.
+
+@c ---------------------------------------------
+@node Packages
+@subsection Packages
+@c ---------------------------------------------
+
+@noindent
+A project file may contain @b{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 @pxref{Attributes} for the list of attributes that each can contain).
+
+@table @code
+@item Binder
+ This package specifies characteristics useful when invoking the binder either
+ directly via the @command{gnat} driver or when using a builder such as
+ @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
+@item 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 @code{Compiler}, @code{Binder} or @code{Linker} packages,
+ but there are some general options that should be defined in this
+ package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
+ particular.
+@ifclear FSFEDITION
+@item Check
+ This package specifies the options used when calling the checking tool
+ @command{gnatcheck} via the @command{gnat} driver. Its attribute
+ @b{Default_Switches} has the same semantics as for the package
+ @code{Builder}. The first string should always be @code{-rules} to specify
+ that all the other options belong to the @code{-rules} section of the
+ parameters to @command{gnatcheck}.
+@end ifclear
+@item Clean
+ This package specifies the options used when cleaning a project or a project
+ tree using the tools @command{gnatclean} or @command{gprclean}.
+@item Compiler
+ This package specifies the compilation options used by the compiler for
+ each languages. @xref{Tools Options in Project Files}.
+@item Cross_Reference
+ This package specifies the options used when calling the library tool
+ @command{gnatxref} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@ifclear FSFEDITION
+@item Eliminate
+ This package specifies the options used when calling the tool
+ @command{gnatelim} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@end ifclear
+@item Finder
+ This package specifies the options used when calling the search tool
+ @command{gnatfind} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@item ^Gnatls^Gnatls^
+ This package specifies the options to use when invoking @command{gnatls}
+ via the @command{gnat} driver.
+@ifclear FSFEDITION
+@item ^Gnatstub^Gnatstub^
+ This package specifies the options used when calling the tool
+ @command{gnatstub} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@end ifclear
+@item IDE
+ This package specifies the options used when starting an integrated
+ development environment, for instance @command{GPS} or @command{Gnatbench}.
+@item Install
+ This package specifies the options used when installing a project
+ with @command{gprinstall}. @xref{Installation}.
+@item Linker
+ This package specifies the options used by the linker.
+ @xref{Main Subprograms}.
+@ifclear FSFEDITION
+@item Metrics
+ This package specifies the options used when calling the tool
+ @command{gnatmetric} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@end ifclear
+@item 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.
+ @xref{Naming Schemes}.
+@ifclear FSFEDITION
+@item Pretty_Printer
+ This package specifies the options used when calling the formatting tool
+ @command{gnatpp} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@end ifclear
+@item Remote
+ This package is used by @command{gprbuild} to describe how distributed
+ compilation should be done.
+@item Stack
+ This package specifies the options used when calling the tool
+ @command{gnatstack} via the @command{gnat} driver. Its attributes
+ @b{Default_Switches} and @b{^Switches^Switches^} have the same semantics as for the
+ package @code{Builder}.
+@item Synchronize
+ This package specifies the options used when calling the tool
+ @command{gnatsync} via the @command{gnat} driver.
+
+@end table
+
+In its simplest form, a package may be empty:
+
+@smallexample @c projectfile
+@group
+project Simple is
+ package Builder is
+ end Builder;
+end Simple;
+@end group
+@end smallexample
+
+@noindent
+A package may contain @b{attribute declarations},
+@b{variable declarations} and @b{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 @code{gnat}.
+
+A package can also be defined by a @b{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 @b{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 @b{extending declaration}. This is
+similar to a @b{renaming declaration}, except that it is possible to add or
+override attributes.
+
+@smallexample
+package_declaration ::= package_spec | package_renaming | package_extension
+package_spec ::=
+ @i{package} @i{<package_>}simple_name @i{is}
+ @{simple_declarative_item@}
+ @i{end} package_identifier ;
+package_renaming ::==
+ @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
+package_extension ::==
+ @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
+ @{simple_declarative_item@}
+ @i{end} package_identifier ;
+@end smallexample
+
+@c ---------------------------------------------
+@node Expressions
+@subsection Expressions
+@c ---------------------------------------------
+
+@noindent
+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:
+@itemize @bullet
+@item A literal string, for instance @code{"comm/my_proj.gpr"}
+@item The name of a variable that evaluates to a string (@pxref{Variables})
+@item The name of an attribute that evaluates to a string (@pxref{Attributes})
+@item An external reference (@pxref{External Values})
+@item A concatenation of the above, as in @code{"prefix_" & Var}.
+
+@end itemize
+
+@noindent
+A list of strings is one of the following:
+
+@itemize @bullet
+@item A parenthesized comma-separated list of zero or more string expressions, for
+ instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
+@item The name of a variable that evaluates to a list of strings
+@item The name of an attribute that evaluates to a list of strings
+@item A concatenation of a list of strings and a string (as defined above), for
+ instance @code{("A", "B") & "C"}
+@item A concatenation of two lists of strings
+
+@end itemize
+
+@noindent
+The following is the grammar for expressions
+
+@smallexample
+string_literal ::= "@{string_element@}" -- Same as Ada
+string_expression ::= string_literal
+ | @i{variable_}name
+ | external_value
+ | attribute_reference
+ | ( string_expression @{ & string_expression @} )
+string_list ::= ( string_expression @{ , string_expression @} )
+ | @i{string_variable}_name
+ | @i{string_}attribute_reference
+term ::= string_expression | string_list
+expression ::= term @{ & term @} -- Concatenation
+@end smallexample
+
+@noindent
+Concatenation involves strings and list of strings. As soon as a list of
+strings is involved, the result of the concatenation is a list of strings. The
+following Ada declarations show the existing operators:
+
+@smallexample @c ada
+ 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;
+@end smallexample
+
+@noindent
+Here are some specific examples:
+
+@smallexample @c projectfile
+@group
+ 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
+@end group
+@end smallexample
+
+@c ---------------------------------------------
+@node External Values
+@subsection External Values
+@c ---------------------------------------------
+
+@noindent
+An external value is an expression whose value is obtained from the command
+that invoked the processing of the current project file (typically a
+@command{gnatmake} or @command{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:
+
+@smallexample
+external_value ::= @i{external} ( string_literal [, string_literal] )
+@end smallexample
+
+@noindent
+The first string_literal is the string to be used on the command line or
+in the environment to specify the external value. The second string_literal,
+if present, is the default to use if there is no specification for this
+external value either on the command line or in the environment.
+
+Typically, the external value will either exist in the
+^environment variables^logical name^
+or be specified on the command line through the
+@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{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 @code{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 @code{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 @b{case} statements to control the value assigned to
+attributes in various scenarios. Thus such variables are often called
+@b{scenario variables}.
+
+The syntax for a string list external value is:
+
+@smallexample
+external_value ::= @i{external_as_list} ( string_literal , string_literal )
+@end smallexample
+
+@noindent
+The first string_literal is the string to be used on the command line or
+in the environment to specify the external value. The second string_literal 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.
+
+@smallexample
+ @i{external_as_list} ("SWITCHES", ",")
+@end smallexample
+
+@noindent
+If the external value is "^-O2^-O2^,-g",
+the result is ("^-O2^-O2^", "-g").
+
+If the external value is ",^-O2^-O2^,-g,",
+the result is also ("^-O2^-O2^", "-g").
+
+if the external value is "^-gnatv^-gnatv^",
+the result is ("^-gnatv^-gnatv^").
+
+If the external value is ",,", the result is ("").
+
+If the external value is ",", the result is (), the empty string list.
+
+@c ---------------------------------------------
+@node Typed String Declaration
+@subsection Typed String Declaration
+@c ---------------------------------------------
+
+@noindent
+A @b{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.
+
+@smallexample
+typed_string_declaration ::=
+ @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
+@end smallexample
+
+@noindent
+The string literals in the list are case sensitive and must all be different.
+They may include any graphic characters allowed in Ada, including spaces.
+Here is an example of a string type declaration:
+
+@smallexample @c projectfile
+ type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
+@end smallexample
+
+@noindent
+Variables of a string type are called @b{typed variables}; all other
+variables are called @b{untyped variables}. Typed variables are
+particularly useful in @code{case} constructions, to support conditional
+attribute declarations. (@pxref{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.
+
+@c ---------------------------------------------
+@node Variables
+@subsection Variables
+@c ---------------------------------------------
+
+@noindent
+@b{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 @b{typed} variable can be used as part of a @b{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 @b{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.
+
+@smallexample
+typed_variable_declaration ::=
+ @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
+variable_declaration ::= @i{<variable_>}simple_name := expression;
+@end smallexample
+
+@noindent
+Here are some examples of variable declarations:
+
+@smallexample @c projectfile
+@group
+ 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");
+@end group
+@end smallexample
+
+@noindent
+A @b{variable reference} may take several forms:
+
+@itemize @bullet
+@item The simple variable name, for a variable in the current package (if any)
+ or in the current project
+@item An expanded name, whose prefix is a context name.
+
+@end itemize
+
+@noindent
+A @b{context} may be one of the following:
+
+@itemize @bullet
+@item The name of an existing package in the current project
+@item The name of an imported project of the current project
+@item The name of an ancestor project (i.e., a project extended by the current
+ project, either directly or indirectly)
+@item An expanded name whose prefix is an imported/parent project name, and
+ whose selector is a package name in that project.
+@end itemize
+
+@c ---------------------------------------------
+@node Case Constructions
+@subsection Case Constructions
+@c ---------------------------------------------
+
+@noindent
+A @b{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 @code{others} choice must appear last in the list of alternatives.
+
+The syntax of a @code{case} construction is based on the Ada case statement
+(although the @code{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 (@pxref{External Values}).
+
+Each alternative starts with the reserved word @code{when}, either a list of
+literal strings separated by the @code{"|"} character or the reserved word
+@code{others}, and the @code{"=>"} token.
+Each literal string must belong to the string type that is the type of the
+case variable.
+After each @code{=>}, 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.
+
+@smallexample
+case_statement ::=
+ @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
+
+case_item ::=
+ @i{when} discrete_choice_list =>
+ @{case_statement
+ | attribute_declaration
+ | variable_declaration
+ | empty_declaration@}
+
+discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
+@end smallexample
+
+@noindent
+Here is a typical example:
+
+@smallexample @c projectfile
+@group
+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^Switches^ ("Ada")
+ use ("-gnath");
+ when "NT" =>
+ for ^Switches^Switches^ ("Ada")
+ use ("^-gnatP^-gnatP^");
+ when others =>
+ null;
+ end case;
+ end Compiler;
+end MyProj;
+@end group
+@end smallexample
+
+@c ---------------------------------------------
+@node Attributes
+@subsection Attributes
+@c ---------------------------------------------
+
+@menu
+* Project Level Attributes::
+* Package Binder Attributes::
+* Package Builder Attributes::
+@ifclear FSFEDITION
+* Package Check Attributes::
+@end ifclear
+* Package Clean Attributes::
+* Package Compiler Attributes::
+* Package Cross_Reference Attributes::
+@ifclear FSFEDITION
+* Package Eliminate Attributes::
+@end ifclear
+* Package Finder Attributes::
+* Package ^gnatls^gnatls^ Attributes::
+@ifclear FSFEDITION
+* Package ^gnatstub^gnatstub^ Attributes::
+@end ifclear
+* Package IDE Attributes::
+* Package Install Attributes::
+* Package Linker Attributes::
+@ifclear FSFEDITION
+* Package Metrics Attribute::
+@end ifclear
+* Package Naming Attributes::
+@ifclear FSFEDITION
+* Package Pretty_Printer Attributes::
+@end ifclear
+* Package Remote Attributes::
+* Package Stack Attributes::
+* Package Synchronize Attributes::
+@end menu
+
+@noindent
+A project (and its packages) may have @b{attributes} that define
+the project's properties. Some attributes have values that are strings;
+others have values that are string lists.
+
+@smallexample
+attribute_declaration ::=
+ simple_attribute_declaration | indexed_attribute_declaration
+simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
+indexed_attribute_declaration ::=
+ @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
+attribute_designator ::=
+ @i{<simple_attribute_>}simple_name
+ | @i{<indexed_attribute_>}simple_name ( string_literal )
+@end smallexample
+
+@noindent
+There are two categories of attributes: @b{simple attributes}
+and @b{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:
+
+@smallexample @c projectfile
+ -- simple attributes
+ for Object_Dir use "objects";
+ for Source_Dirs use ("units", "test/drivers");
+
+ -- indexed attributes
+ for Body ("main") use "Main.ada";
+ for ^Switches^Switches^ ("main.ada")
+ use ("-v", "^-gnatv^-gnatv^");
+ for ^Switches^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;
+@end smallexample
+
+@noindent
+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.
+
+@smallexample
+attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
+attribute_prefix ::= @i{project}
+ | @i{<project_>}simple_name
+ | package_identifier
+ | @i{<project_>}simple_name . package_identifier
+@end smallexample
+
+@noindent
+Examples are:
+
+@smallexample @c projectfile
+ project'Object_Dir
+ Naming'Dot_Replacement
+ Imported_Project'Source_Dirs
+ Imported_Project.Naming'Casing
+ Builder'Default_Switches ("Ada")
+@end smallexample
+
+@noindent
+The prefix of an attribute may be:
+
+@itemize @bullet
+@item @code{project} for an attribute of the current project
+@item The name of an existing package of the current project
+@item The name of an imported project
+@item The name of a parent project that is extended by the current project
+@item An expanded name whose prefix is imported/parent project name,
+ and whose selector is a package name
+
+@end itemize
+
+@noindent
+
+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:
+
+@itemize @bullet
+
+@item @b{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".
+
+@item @b{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".
+
+@item @b{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".
+
+@item @b{Indexed attribute}
+
+When an it is an indexed attribute, this is indicated by the word "indexed".
+
+@item @b{Case-sensitivity of the index}
+
+For an indexed attribute, if the index is case-insensitive, this is indicated
+by the words "case-insensitive index".
+
+@item @b{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.
+
+@item @b{others allowed in index}
+
+For an indexed attribute, if it is allowed to use @b{others} as the index,
+this is indicated by the words "others allowed".
+
+When @b{others} is used as the index of an indexed attribute, the value of
+the attribute indexed by @b{others} is used when no other index would apply.
+
+@end itemize
+
+@node Project Level Attributes
+@subsubsection Project Level Attributes
+@noindent
+
+@itemize @bullet
+
+@item @b{General}
+
+@itemize @bullet
+
+@item @b{Name}: single, read-only
+
+The name of the project.
+
+@item @b{Project_Dir}: single, read-only
+
+The path name of the project directory.
+
+@item @b{Main}: list, optional index
+
+The list of main sources for the executables.
+
+@item @b{Languages}: list
+
+The list of languages of the sources of the project.
+
+@item @b{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 @b{Roots} with an index that
+is the executable source file name, if declared. Otherwise, they are those in
+@b{Roots} with an index that is the language name of the executable source,
+if present. Otherwise, they are those in @b{Roots ("*")}, if declared. If none
+of these three possibilities are declared, then there are no roots for the
+executable source.
+
+@item @b{Externally_Built}: single
+
+Indicates if the project is externally built.
+Only case-insensitive values allowed are "true" and "false", the default.
+
+@end itemize
+@noindent
+
+@item @b{Directories}
+
+@itemize @bullet
+
+@item @b{Object_Dir}: single
+
+Indicates the object directory for the project.
+
+@item @b{Exec_Dir}: single
+
+Indicates the exec directory for the project, that is the directory where the
+executables are.
+
+@item @b{Source_Dirs}: list
+
+The list of source directories of the project.
+
+@item @b{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");
+
+@item @b{Exclude_Source_Dirs}: list
+
+The list of directories that are included in Source_Dirs but are not source
+directories of the project.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Source Files}
+
+@itemize @bullet
+
+@item @b{Source_Files}: list
+
+Value is a list of source file simple names.
+
+@item @b{Locally_Removed_Files}: list
+
+Obsolescent. Equivalent to Excluded_Source_Files.
+
+@item @b{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.
+
+@item @b{Source_List_File}: single
+
+Value is a text file name that contains a list of source file simple names,
+one on each line.
+
+@item @b{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.
+
+@item @b{Interfaces}: list
+
+Value is a list of file names that constitutes the interfaces of the project.
+
+@end itemize
+
+@item @b{Aggregate Projects}
+
+@itemize @bullet
+
+@item @b{Project_Files}: list
+
+Value is the list of aggregated projects.
+
+@item @b{Project_Path}: list
+
+Value is a list of directories that are added to the project search path when
+looking for the aggregated projects.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Libraries}
+
+@itemize @bullet
+
+@item @b{Library_Dir}: single
+
+Value is the name of the library directory. This attribute needs to be
+declared for each library project.
+
+@item @b{Library_Name}: single
+
+Value is the name of the library. This attribute needs to be declared or
+inherited for each library project.
+
+@item @b{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.
+
+@item @b{Library_Version}: single
+
+Value is the name of the library file.
+
+@item @b{Library_Interface}: list
+
+Value is the list of unit names that constitutes the interfaces
+of a Stand-Alone Library project.
+
+@item @b{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.
+
+@item @b{Library_Encapsulated_Options}: list
+
+Value is a list of options that need to be used when linking an encapsulated
+Stand-Alone Library.
+
+@item @b{Library_Encapsulated_Supported}: single
+
+Indicates if encapsulated Stand-Alone Libraries are supported. Only
+authorized case-insensitive values are "true" and "false" (the default).
+
+@item @b{Library_Auto_Init}: single
+
+Indicates if a Stand-Alone Library is auto-initialized. Only authorized
+case-insentive values are "true" and "false".
+
+@item @b{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.
+
+@item @b{Library_Options}: list
+
+Value is a list of options that are to be used when linking a shared library.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{Library_gcc}: single
+
+Obsolescent attribute. Specify the linker driver used to link a shared library.
+Use instead attribute Linker'Driver.
+
+@item @b{Library_Symbol_File}: single
+
+Value is the name of the library symbol file.
+
+@item @b{Library_Symbol_Policy}: single
+
+Indicates the symbol policy kind. Only authorized case-insensitive values are
+"autonomous", "default", "compliant", "controlled" or "direct".
+
+@item @b{Library_Reference_Symbol_File}: single
+
+Value is the name of the reference symbol file.
+
+@end itemize
+
+@item @b{Configuration - General}
+
+@itemize @bullet
+
+@item @b{Default_Language}: single
+
+Value is the case-insensitive name of the language of a project when attribute
+Languages is not specified.
+
+@item @b{Run_Path_Option}: list
+
+Value is the list of switches to be used when specifying the run path option
+in an executable.
+
+@item @b{Run_Path_Origin}: single
+
+Value is the the string that may replace the path name of the executable
+directory in the run path options.
+
+@item @b{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).
+
+@item @b{Toolchain_Version}: single, indexed, case-insensitive index
+
+Index is a language name. Specify the version of a toolchain for a language.
+
+@item @b{Toolchain_Description}: single, indexed, case-insensitive index
+
+Obsolescent. No longer used.
+
+@item @b{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).
+
+@item @b{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).
+
+@item @b{Target}: single
+
+Value is the name of the target platform.
+
+@end itemize
+
+@item @b{Configuration - Libraries}
+
+@itemize @bullet
+
+@item @b{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".
+
+@item @b{Library_Support}: single
+
+Indicates the level of support of libraries. Only authorized case-insensitive
+values are "static_only", "full" or "none" (the default).
+
+@end itemize
+
+@item @b{Configuration - Archives}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{Archive_Indexer}: list
+
+Value is the name of the archive indexer, followed by the required options.
+
+@item @b{Archive_Suffix}: single
+
+Value is the extension of archives. When not declared, the extension is ".a".
+
+@item @b{Library_Partial_Linker}: list
+
+Value is the name of the partial linker executable, followed by the required
+options.
+
+@end itemize
+
+@item @b{Configuration - Shared Libraries}
+
+@itemize @bullet
+
+@item @b{Shared_Library_Prefix}: single
+
+Value is the prefix in the name of shared library files. When not declared,
+the prefix is "lib".
+
+@item @b{Shared_Library_Suffix}: single
+
+Value is the the extension of the name of shared library files. When not
+declared, the extension is ".so".
+
+@item @b{Symbolic_Link_Supported}: single
+
+Indicates if symbolic links are supported on the platform. Only authorized
+case-insensitive values are "true" and "false" (the default).
+
+@item @b{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).
+
+@item @b{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).
+
+@item @b{Shared_Library_Minimum_Switches}: list
+
+Value is the list of required switches when linking a shared library.
+
+@item @b{Library_Version_Switches}: list
+
+Value is the list of switches to specify a internal name for a shared library.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@end itemize
+
+@node Package Binder Attributes
+@subsubsection Package Binder Attributes
+
+@itemize @bullet
+
+@item @b{General}
+
+@itemize @bullet
+
+@item @b{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^.
+
+@item @b{^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.
+
+@end itemize
+
+@item @b{Configuration - Binding}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@end itemize
+
+@node Package Builder Attributes
+@subsubsection Package Builder Attributes
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{^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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@ifclear FSFEDITION
+@node Package Check Attributes
+@subsubsection Package Check Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatcheck} for a source of the language, if there is no applicable
+attribute ^Switches^Switches^.
+
+@item @b{^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 @code{gnatcheck} for the source.
+
+@end itemize
+@end ifclear
+
+@node Package Clean Attributes
+@subsubsection Package Clean Attributes
+
+@itemize @bullet
+
+@item @b{^Switches^Switches^}: list
+
+Value is a list of switches to be used by the cleaning application.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@node Package Compiler Attributes
+@subsubsection Package Compiler Attributes
+
+@itemize @bullet
+
+@item @b{General}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{^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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Configuration - Compiling}
+
+@itemize @bullet
+
+@item @b{Driver}: single, indexed, case-insensitive index
+
+Index is a language name. Value is the name of the executable for the compiler
+of the language.
+
+@item @b{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).
+
+@item @b{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).
+
+@item @b{Required_Switches}: list, indexed, case-insensitive index
+
+Equivalent to attribute Leading_Required_Switches.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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).
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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".
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Configuration - Mapping Files}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Configuration - Config Files}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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).
+
+@end itemize
+
+@item @b{Configuration - Dependencies}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@item @b{Configuration - Search Paths}
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@end itemize
+
+@node Package Cross_Reference Attributes
+@subsubsection Package Cross_Reference Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatxref} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatxref} for the source.
+
+@end itemize
+
+@ifclear FSFEDITION
+@node Package Eliminate Attributes
+@subsubsection Package Eliminate Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatelim} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatelim} for the source.
+
+@end itemize
+@end ifclear
+
+@node Package Finder Attributes
+@subsubsection Package Finder Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatfind} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatfind} for the source.
+
+@end itemize
+
+@node Package ^gnatls^gnatls^ Attributes
+@subsubsection Package ^gnatls^gnatls^ Attributes
+
+@itemize @bullet
+
+@item @b{^Switches^Switches^}: list
+
+Value is a list of switches to be used when invoking @code{gnatls}.
+
+@end itemize
+
+@ifclear FSFEDITION
+@node Package ^gnatstub^gnatstub^ Attributes
+@subsubsection Package ^gnatstub^gnatstub^ Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatstub} for a source of the language, if there is no applicable
+attribute ^Switches^Switches^.
+
+@item @b{^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 @code{gnatstub} for the source.
+
+@end itemize
+@end ifclear
+
+@node Package IDE Attributes
+@subsubsection Package IDE Attributes
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{Communication_Protocol}: single
+
+Value is the name of the protocol to use to communicate with the target
+in a cross-compilation environment, for example @code{"wtx"} or
+@code{"vxworks"}.
+
+@item @b{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 @code{Compiler_Command ("Ada")} is
+expected to be compatible with @command{gnatmake}, in particular in
+the handling of switches.
+
+@item @b{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.
+
+@item @b{^gnatlist^gnatlist^}: single
+
+Value is a string that specifies the name of the @command{^gnatls^gnatls^} utility
+to be used to retrieve information about the predefined path; for example,
+@code{"^gnatls^gnatls^"}, @code{"powerpc-wrs-vxworks-gnatls"}.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{VCS_Log_Check}: single
+
+Value is a string that specifies the command used by the VCS to check
+the validity of a log file.
+
+@item @b{Documentation_Dir}: single
+
+Value is the directory used to generate the documentation of source code.
+
+@end itemize
+
+@node Package Install Attributes
+@subsubsection Package Install Attributes
+
+@itemize @bullet
+
+@item @b{Prefix}: single
+
+Value is the install destination directory.
+
+@item @b{Sources_Subdir}: single
+
+Value is the sources directory or subdirectory of Prefix.
+
+@item @b{Exec_Subdir}: single
+
+Value is the executables directory or subdirectory of Prefix.
+
+@item @b{Lib_Subdir}: single
+
+Value is library directory or subdirectory of Prefix.
+
+@item @b{Project_Subdir}: single
+
+Value is the project directory or subdirectory of Prefix.
+
+@item @b{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.
+
+@end itemize
+
+@node Package Linker Attributes
+@subsubsection Package Linker Attributes
+
+@itemize @bullet
+
+@item @b{General}
+
+@itemize @bullet
+
+@item @b{Required_Switches}: list
+
+Value is a list of switches that are required when invoking the linker to link
+an executable.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{^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 linker to build an executable for the source or
+for its language.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{Map_File_Option}: single
+
+Value is the switch to specify the map file name that the linker needs to
+create.
+
+@end itemize
+
+@item @b{Configuration - Linking}
+
+@itemize @bullet
+
+@item @b{Driver}: single
+
+Value is the name of the linker executable.
+
+@end itemize
+
+@item @b{Configuration - Response Files}
+
+@itemize @bullet
+
+@item @b{Max_Command_Line_Length}: single
+
+Value is the maximum number of character in the command line when invoking
+the linker to link an executable.
+
+@item @b{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".
+
+@item @b{Response_File_Switches}: list
+
+Value is the list of switches to specify a response file to the linker.
+
+@end itemize
+
+@end itemize
+
+@ifclear FSFEDITION
+@node Package Metrics Attribute
+@subsubsection Package Metrics Attribute
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatmetric} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatmetric} for the source.
+
+@end itemize
+@end ifclear
+
+@node Package Naming Attributes
+@subsubsection Package Naming Attributes
+
+@itemize @bullet
+
+@item @b{Specification_Suffix}: single, indexed, case-insensitive index
+
+Equivalent to attribute Spec_Suffix.
+
+@item @b{Spec_Suffix}: single, indexed, case-insensitive index
+
+Index is a language name. Value is the extension of file names for specs of
+the language.
+
+@item @b{Implementation_Suffix}: single, indexed, case-insensitive index
+
+Equivalent to attribute Body_Suffix.
+
+@item @b{Body_Suffix}: single, indexed, case-insensitive index
+
+Index is a language name. Value is the extension of file names for bodies of
+the language.
+
+@item @b{Separate_Suffix}: single
+
+Value is the extension of file names for subunits of Ada.
+
+@item @b{Casing}: single
+
+Indicates the casing of sources of the Ada language. Only authorized
+case-insensitive values are "lowercase", "uppercase" and "mixedcase".
+
+@item @b{Dot_Replacement}: single
+
+Value is the string that replace the dot of unit names in the source file names
+of the Ada language.
+
+@item @b{Specification}: single, optional index, indexed,
+ case-insensitive index
+
+Equivalent to attribute Spec.
+
+@item @b{Spec}: single, optional index, indexed, case-insensitive index
+
+Index is a unit name. Value is the file name of the spec of the unit.
+
+@item @b{Implementation}: single, optional index, indexed,
+ case-insensitive index
+
+Equivalent to attribute Body.
+
+@item @b{Body}: single, optional index, indexed, case-insensitive index
+
+Index is a unit name. Value is the file name of the body of the unit.
+
+@item @b{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.
+
+@item @b{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.
+
+@end itemize
+
+@ifclear FSFEDITION
+@node Package Pretty_Printer Attributes
+@subsubsection Package Pretty_Printer Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatpp} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatpp} for the source.
+
+@end itemize
+@end ifclear
+
+@node Package Remote Attributes
+@subsubsection Package Remote Attributes
+
+@itemize @bullet
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{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.
+
+@item @b{Root_Dir}: single
+
+Value is the root directory used by the slave machines.
+
+@end itemize
+
+@node Package Stack Attributes
+@subsubsection Package Stack Attributes
+
+@itemize @bullet
+
+@item @b{^Switches^Switches^}: list
+
+Value is the list of switches to be used when invoking @code{gnatstack}.
+
+@end itemize
+
+@node Package Synchronize Attributes
+@subsubsection Package Synchronize Attributes
+
+@itemize @bullet
+
+@item @b{Default_Switches}: list, indexed, case-insensitive index
+
+Index is a language name. Value is a list of switches to be used when invoking
+@code{gnatsync} for a source of the language, if there is no applicable
+attribute Switches.
+
+@item @b{^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 @code{gnatsync} for the source.
+
+@end itemize
+