This chapter describes GNAT’s Project Manager, a facility that allows
you to manage complex builds involving a number of source files, directories,
and options for different system configurations. In particular,
project files allow you to specify properties including:
The directory or set of directories containing the source files, and/or the
names of the specific source files themselves;
The directory in which the compiler’s output
(ALI files, object files, tree files, etc.) is to be placed;
The directory in which the executable programs are to be placed;
Switch settings, which can be applied either globally or to individual
compilation units, for any of the project-enabled tools;
The source files containing the main subprograms to be built;
The source programming language(s); and
Source file naming conventions, which can be specified either globally or for
individual compilation units (see Naming Schemes).
Project files also allow you to:
Change any of the above settings depending on external values, thus enabling
the reuse of the projects in various scenarios (see Scenarios in Projects); and
Automatically build libraries as part of the build process
(see Library Projects).
Project files are written in an Ada-like syntax, using familiar
notions such as packages, context clauses, declarations, default values,
assignments, and inheritance (see Project File Reference).
Project files can depend upon other project files in a modular fashion,
simplifying complex system integration and project reuse.
One project can import other projects containing needed source files.
More generally, the Project Manager lets you structure large development
efforts into possibly interrelated subsystems, where build decisions are
delegated to the subsystem level, and thus different compilation
environments (switch settings) are used for different subsystems.
See Organizing Projects into Subsystems.
You can organize GNAT projects in a hierarchy: a project
can extend a base project, inheriting its source files and
optionally overriding any of them with alternative versions.
See Project Extension.
Several tools support project files, generally in addition to specifying
the information on the command line itself. They share common switches
to control the loading of the project (in particular
-Pprojectfile to define the applicable project file and
-Xvbl=value to set the value of an external variable).
The Project Manager supports a wide range of development strategies,
for systems of all sizes. Here are some typical practices that are
easily handled:
Using a common set of source files and generating object files in different
directories via different switch settings. This can be used for instance to
generate separate sets of object files for debugging and for production.
Using a mostly shared set of source files with different versions of
some units or subunits. This can be used for instance to group and hide
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 sections below use an example-driven approach to present and illustrate
the various concepts related to projects.
In its simplest form a project may be used in a stand-alone fashion to build
a single executable, and this section will focus on such a setup in order
to introduce the main ideas.
Later sections will extend this basic model to more complex and realistic
configurations.
The following concepts are the foundation of project files, and will be further
detailed later in this documentation. They are summarized here as a reference.
Project file:
A text file expressed in an Ada-like syntax, generally with the .gpr
extension. It defines build-related characteristics of an application.
The characteristics include the list of sources, the location of those
sources, the location for the generated object files, the name of
the main program, and the options for the various tools involved in the
build process.
Project attribute:
A specific project characteristic is defined by an attribute clause. Its
value is a string or a sequence of strings. All settings in a project
are defined through a list of predefined attributes with precise
semantics. See Attributes.
Package in a project:
Global attributes are defined at the top level of a project.
Attributes affecting specific tools are grouped in a
package whose name is related to tool’s function. The most common
packages are Builder, Compiler, Binder,
and Linker. See Packages.
Project variables:
In addition to attributes, a project can use variables to store intermediate
values and avoid duplication in complex expressions. Variables can be initialized
with external values coming from the environment.
A frequent use of variables is to define scenarios.
See External Values, Scenarios in Projects, and Variables.
Source files and source directories:
A source file is associated with a language through a naming convention. For
instance, foo.c is typically the name of a C source file;
bar.ads or bar.1.ada are two common naming conventions for a
file containing an Ada spec. A compilable entity is often composed of a main
source file and potentially several auxiliary ones, such as header files in C.
The naming conventions can be user-defined (see Naming Schemes), and will
drive the builder to call the appropriate compiler for the given source file.
Source files are searched for in the source directories associated with the
project through the Source_Dirs attribute. By default, all the files (in
these source directories) following the naming conventions associated with the
declared languages are considered to be part of the project. It is also
possible to limit the list of source files using the Source_Files or
Source_List_File attributes. Note that those last two attributes only
accept basenames with no directory information.
Object files and object directory:
An object file is an intermediate file produced by the compiler from a
compilation unit. It is used by post-compilation tools to produce
final executables or libraries. Object files produced in the context of
a given project are stored in a single directory that can be specified by the
Object_Dir attribute. In order to store objects in
two or more object directories, the system must be split into
distinct subsystems, each with its own project file.
The following subsections introduce the attributes of interest
for simple build needs. Here is the basic setup that will be used in the
following examples:
The Ada source files pack.ads, pack.adb, and
proc.adb are in the common/ directory. The file
proc.adb contains an Ada main subprogram Proc that
withs package Pack. We want to compile these source files
with the switch -O2, and place the resulting files in
the common/obj/ directory. Here is the directory structure:
Our project is to be called Build. The name of the
file is the name of the project (case-insensitive) with the
.gpr extension, therefore the project file name is
build.gpr. This is not mandatory, but a warning is issued
when this convention is not followed.
This is a very simple example, and as stated above, a single project
file is sufficient. We will thus create a new file, build.gpr, that
initially contains an empty project declaration:
project Buildisend Build;
Note that repeating the project name after end is mandatory.
When you create a new project, the first task is to specify where the
corresponding source files are located. These are 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, etc.).
The first step is thus to declare the source directories, which are the directories
to be searched to find source files. In the current example,
the common directory is the only source directory.
There are several ways to specify the source directories:
When the attribute Source_Dirs is not defined, a project contains a
single source directory which is the one where the project file itself
resides. In our example, if build.gpr is placed in the common
directory, the project will have the needed implicit source directory.
The attribute Source_Dirs can be set to a list of path names, one
for each of the source directories. Such paths can either be absolute
names (for instance "/usr/local/common/" on Unix), or relative to the
directory in which the project file resides (for instance "." if
build.gpr is inside common/, or "common" if it is one level up).
Each of the source directories must exist and be readable.
The syntax for directories is platform specific. For portability, however,
the project manager will always properly translate Unix-like path names to
the native format of the specific platform. For instance, when the same
project file is to be used both on Unix and Windows, "/" should be used as
the directory separator rather than "\".
The attribute Source_Dirs can automatically include subdirectories
using a special syntax inspired by some Unix shells. If any of the paths in
the list ends with “**”, then that path and all its subdirectories
(recursively) are included in the list of source directories. For instance,
“**” and “./**” represent the complete directory tree rooted at
the directory in which the project file resides.
When using the Source_Dirs construct, you may sometimes find it convenient
to also use the attribute Excluded_Source_Dirs, which is also a list of
paths. Each entry specifies a directory whose immediate content, not including
subdirs, is to be excluded. It is also possible to exclude a complete
directory subtree using the ** notation.
It is often desirable to remove, from the source directories, directory
subtrees rooted at some subdirectories. An example is the subdirectories
created by a Version Control System such as Subversion that creates directory
subtrees rooted at a subdirectory named .svn. To do that, attribute
Ignore_Source_Sub_Dirs can be used. It specifies the list of simple
file names or patterns for the roots of these undesirable directory subtrees.
With the declaration of attribute Ignore_Source_Sub_Dirs above, .svn subtrees
as well as subtrees rooted at subdirectories with a name starting with ‘@’
are not part of the source directories of the project.
When applied to the simple example, and because we generally prefer to have
the project file at the top-level directory rather than mixed with the sources,
we will add the relevant definition for the Source_Dirs attribute to
our build.gpr project file:
Once the source directories have been specified, you may need to indicate
specific 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 explicitly specify the list of sources to consider.
In such a case, only source file base names are indicated and not
their absolute or relative path names. The project manager is in charge of
locating the specified source files in the specified source directories.
By default, the project manager searches 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,
all the sources in subdirectory common for the default language (Ada) using
the default naming convention.
However, when compiling a multi-language application, or a pure C
application, the project manager must be told which languages are of
interest, which is done by setting the Languages attribute to a list of
strings, each of which is the name of a language.
Even when only Ada is used, the default naming might not be suitable. Indeed,
how does the project manager distinguish an Ada source file from any other
file? Project files can describe the naming scheme used for source files,
and override the default (see Naming Schemes). The default is the
standard GNAT extension (.adb for bodies and .ads for
specs), which is what is used in our example, and thus no naming scheme
is explicitly specified.
See Naming Schemes.
Source_Files.
In some cases, source directories might contain files that should not be
included in a project. One can specify the explicit list of file names to
be considered through the Source_Files attribute.
When this attribute is defined, instead of looking at every file in the
source directories, the project manager takes only those names into
consideration and reports errors if they cannot be found in the source
directories or do not correspond to the naming scheme.
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
Organizing Projects into Subsystems. To do this, the attribute
Source_Files is set to the empty list, i.e. (). Alternatively,
Source_Dirs can be set to the empty list, with the same
result.
Source_List_File.
If there is a large number of files, it might be more convenient to use
the attribute Source_List_File, which specifies the full path of a file.
This file must contain a list of source file names (one per line, no
directory information) that are searched as if they had been defined
through Source_Files. Such a file can easily be created through
external tools.
A warning is issued if both attributes Source_Files and
Source_List_File are given explicit values. In this case, the
attribute Source_Files prevails.
Excluded_Source_Files.
Specifying an explicit list of files is not always convenient. Instead it might
be preferable to use the default search rules with specific exceptions.
This can be done through the attribute Excluded_Source_Files
(or its synonym Locally_Removed_Files).
Its value is the list of file names that should not be taken into account.
This attribute is often used when extending a project,
see Project Extension. A similar attribute
Excluded_Source_List_File plays the same
role but takes the name of file containing file names similarly to
Source_List_File.
In most simple cases, such as the above example, the default source file search
behavior provides the expected result, and we do not need to add anything after
setting Source_Dirs. The Project Manager automatically finds
pack.ads, pack.adb, and proc.adb as source files of the
project.
Note that by default a warning is issued when a project has no sources attached
to it and this is not explicitly indicated in the project file.
If the order of the source directories is known statically, that is if
"/**" is not used in the string list for Source_Dirs, then there may
be several files with the same name situated in different directories of the
project. In this case, only the file in the first directory is considered as a
source of the project and the others are hidden. If "/**" is used in the
string list for Source_Dirs, it is an error to have several files with the
same name in the same directory "/**" subtree, since there would be an
ambiguity as to which one should be used.
If there are two sources with the same name in different directories of the same "/**"
subtree, one way to resolve the problem is to exclude the directory of the
file that should not be used as a source of the project.
Another consideration when designing a project is to decide where the compiler should
place the object files. In fact, the compiler and other tools might create
several different kinds of files (for GNAT, there is the object file and the ALI
file). One of the important concepts in projects is that most
tools may consider source directories as read-only and thus do not attempt to create
new or temporary files there. Instead, all such files are created in the object
directory. (This is not true for project-aware IDEs, one of whose purposes is
to create the source files.)
The object directory is specified through the Object_Dir attribute.
Its value is the path to the object directory, either absolute or
relative to the directory containing the project file. This
directory must already exist and be readable and writable, although
some tools have a switch to create the directory if needed (See
the switch -p for gprbuild).
If the attribute Object_Dir is not specified, it defaults to
the directory containing the project file.
For our example, we can specify the object directory in this way
(assuming that the project file will reside in the parent directory
of common):
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 across
several directories, one option is to move all of them into the same directory if
you want to build it with a single project file. An alternative approach is
described below (see Organizing Projects into Subsystems), allowing each
separate object directory to be associated with a corresponding subsystem
of the application.
Incidentally, the directory designated by the Object_Dir attribute may
be used by project aware tools other than the compilation toolchain to store
reports or intermediate files.
When the linker is called, it usually creates an executable. By
default, this executable is placed in the project’s object directory.
However in some situations it may be convenient to store it in elsewhere.
This can be done through the Exec_Dir attribute, which, like
Object_Dir contains a single absolute or relative path and must point to
an existing and writable directory, unless you ask the tool to create it on
your behalf. If neither Object_Dir nor Exec_Dir is specified then
the executable is placed in the directory containing the project file.
In our example, let’s specify that the executable is to
be placed in the same directory as the project file build.gpr.
The project file is now:
An important role of a project file is to identify the executable(s) that
will be built. It does this by specifying the source file for the
main subprogram (for Ada) or the file that contains the main function
(for C).
There can be any number of such main files within a given project, and thus
several executables can be built from a single project file. Of
course, a given executable might not (and in general will not) need all the
source files referenced by the project. As opposed to other build mechanisms
such as through a Makefile, you do not need to specify the list of
dependencies of each executable. The project-aware builder knows enough of the
semantics of the languages to build and link only the necessary elements.
The list of main files is specified via the Main attribute. It contains
a list of file names (no directories). If a file name is specified without
extension, it is completed using the naming convention defined in the package
Naming. If a project defines this
attribute, it is not necessary to identify main files on the
command line when invoking a builder, and editors like
GPS will be able to create extra menus to spawn or debug the
corresponding executables.
If this attribute is defined in the project, then spawning the builder
with a command such as
gprbuild-Pbuild
automatically builds all the executables corresponding to the files
listed in the Main attribute. It is possible to specify one
or more executables on the command line to build a subset of them.
One or more spaces may be placed between the -P and the project
name, and the project name may be a simple name (no file extension) or
a path for the project file. Thus each of the following is equivalent to
the command above:
We now have a project file that fully describes our environment, and it can be
used to build the application with a simple GPRbuild command as shown
above. In fact, the empty project that we saw at
the beginning (with no attribute definitions) could already achieve this effect
if it was placed in the common directory.
Of course, we might want more control. This section shows you how to specify
the compilation switches that the various tools involved in the building of the
executable should use.
Since source names and locations are described in the project file, it is not
necessary to use switches on the command line for this purpose (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
various text files, such as response files, for this purpose and thus are not subject
to command line overflow.
Several tools are used to create an executable: the compiler
produces object files from the source files; the binder (when the language is Ada)
creates a “source” file that, among other things, takes care of elaboration
issues and global variable initialization; and the linker gathers everything
into a single executable. All these tools are known to
the project manager and will be invoked with user-defined switches from the
project files. To obtain this effect, a project file feature known as
a package is used.
A project file contains zero or more packages, each of which
defines the attributes specific to one tool (or one set of tools). Project
files use an Ada-like syntax for packages. Package names permitted in project
files are restricted to a predefined set (see Packages), and the contents
of packages are limited to a small set of constructs and attributes
(see Attributes).
Our example project file below includes several empty packages. At
this stage, they could all be omitted since they are empty, but they show which
packages would be involved in the build process.
project BuildisforSource_Dirsuse("common");forObject_Diruse"obj";forExec_Diruse".";forMainuse("proc.adb");package Builderis--<<< for gprbuildend Builder;package Compileris--<<< for the compilerend Compiler;package Binderis--<<< for the binderend Binder;package Linkeris--<<< for the linkerend Linker;end Build;
Let’s first examine the compiler switches. As stated in the initial description
of the example, we want to compile all files with -O2. This is a
compiler switch, although it is typical, on the command line, to pass it to the
builder which then passes it to the compiler. We recommend directly using
the correct package, which will make the setup easier to understand.
Several attributes can be used to specify the switches:
Default_Switches:
This illustrates the concept of an indexed attribute. When
such an attribute is defined, you must supply an index in the form of a
literal string.
In the case of Default_Switches, the index is the name of the
language to which the switches apply (since a different compiler will
likely be used for each language, and each compiler has its own set of
switches). The value of the attribute is a list of switches.
In this example, we want to compile all Ada source files with the switch
-O2; the resulting Compiler package is as follows:
In some cases, we might want to use specific switches
for one or more files. For instance, compiling proc.adb might not be
desirable at a high level of optimization.
In such a case, the Switches
attribute (indexed by the file name) can be used and will override the
switches defined by Default_Switches. The Compiler package in our
project file would become:
Sources pkg.adb and pkg-child.adb would be compiled with -O0,
not -O2.
Switches can also be given a language name as index instead of a file
name in which case it has the same semantics as Default_Switches.
However, indexes with wild cards are never valid for language name.
Local_Configuration_Pragmas:
This attribute may specify the path
of a file containing configuration pragmas for use by the Ada compiler,
such as pragma Restrictions (No_Tasking). These pragmas will be
used for all the sources of the project.
The switches for the other tools are defined in a similar manner through the
Default_Switches and Switches attributes, respectively in the
Builder package (for GPRbuild),
the Binder package (binding Ada executables) and the Linker
package (for linking executables).
Now that our project file is written, let’s build our executable.
Here is the command we would use from the command line:
gprbuild-Pbuild
This will automatically build the executables specified in the
Main attribute: for each, it will compile or recompile the
sources for which the object file does not exist or is not up-to-date; it
will then run the binder; and finally run the linker to create the
executable itself.
The GPRbuild builder can automatically manage C files the
same way: create the file utils.c in the common directory,
set the attribute Languages to “(Ada, C)”, and re-run
gprbuild-Pbuild
GPRbuild knows how to recompile the C files and will
recompile them only if one of their dependencies has changed. No direct
indication on how to build the various elements is given in the
project file, which describes the project properties rather than a
set of actions to be executed. Here is the invocation of
GPRbuild when building a multi-language program:
The first three gcc commands correspond to the compilation phase.
The gprbind command corresponds to the post-compilation phase.
The last gcc command corresponds to the final link.
The default output of GPRbuild is reasonably simple and easy
to understand. In particular, some of the less frequently used commands are not
shown, and some parameters are abbreviated. Thus it is not possible to rerun the
effect of the GPRbuild command by cut-and-pasting its output.
The -v option to GPRbuild provides a much more verbose output which includes,
among other information, more complete compilation, post-compilation and link
commands.
By default, the executable name corresponding to a main file is
computed from the main source file name. Through the attribute
Executable in package Builder, it is possible to change
this default.
For instance, instead of building an executable named "proc" (or "proc.exe"
on Windows), we could configure our project file to build proc1
(respectively proc1.exe) as follows:
project Buildis...-- same as beforepackage BuilderisforExecutable("proc.adb")use"proc1";end Builderend Build;
Attribute Executable_Suffix, when specified, changes the suffix
of the executable files when no attribute Executable applies:
its value replaces the platform-specific executable suffix.
The default executable suffix is the empty string empty on Unix and ".exe" on Windows.
It is also possible to change the name of the produced executable by using the
command line switch -o. However, when several main programs are defined in the project,
it is not possible to use the -o switch; then the only way to change the
names of the executable is through the attributes Executable and
Executable_Suffix.
This project has many similarities with the previous one.
As expected, its Main attribute now refers to a C source file.
The attribute Exec_Dir is now omitted, thus the resulting
executable will be put in the object directory obj.
The most noticeable difference is the use of a variable in the
Compiler package to store settings used in several attributes.
This avoids text duplication and eases maintenance (a single place to
modify if we want to add new switches for C files). We will later revisit
the use of variables in the context of scenarios (see Scenarios in Projects).
In this example, we see that the file main.c will be compiled with
the switches used for all the other C files, plus -g.
In this specific situation the use of a variable could have been
replaced by a reference to the Default_Switches attribute:
The default switches for Ada sources,
the default switches for C sources (in the compilation of lib.c),
and the specific switches for main.c have all been taken into
account.
Sometimes an Ada software system needs to be ported from one compilation environment to
another (such as GNAT), but the files might not be named using the default GNAT
conventions. Instead of changing all the file names, which for a variety of
reasons might not be possible, you can define the relevant file naming scheme
in the Naming package of your project file.
The naming scheme has two distinct goals for the Project Manager: it
allows source files to be located when searching in the source
directories, and given a source file name it makes it possible to infer
the associated language, and thus which compiler to use.
Note that the Ada compiler’s use of pragma Source_File_Name is not
supported when using project files. You must use the features described here.
You can, however, specify other configuration pragmas.
The following attributes can be defined in package Naming:
Casing:
Its value must be one of "lowercase" (the default if
unspecified), "uppercase" or "mixedcase". It describes the
casing of file names with regard to the Ada unit name.
Given an Ada package body My_Unit, the base file name (i.e. minus the
extension, which is controlled by other attributes described below)
will respectively be:
for “lowercase”: “my_unit”
for “uppercase”: “MY_UNIT”
for “mixedcase”: any spelling with indifferent casing such as “My_Unit”,
“MY_Unit”, “My_UnIT” etc… The case insensitive name must be unique,
otherwise an error will be reported. For example, there cannot be two
source file names such as “My_Unit.adb” and “MY_UnIT.adb”.
On Windows, file names are case insensitive, so this attribute is
irrelevant.
Dot_Replacement:
This attribute specifies the string that should replace the "." in unit
names. Its default value is "-" so that a unit
Parent.Child is expected to be found in the file
parent-child.adb. The replacement string must satisfy the following
requirements to avoid ambiguities in the naming scheme:
It must not be empty
It cannot start or end with an alphanumeric character
It cannot be a single underscore
It cannot start with an underscore followed by an alphanumeric
It cannot contain a dot '.' unless the entire string is "."
It cannot include a space or a character that is not printable ASCII
Spec_Suffix and Specification_Suffix:
For Ada, these attributes specify the suffix used in file names that contain
specifications. For other languages, they give the extension for files
that contain declarations (header files in C for instance). The attribute
is indexed by the language name.
The two attributes are equivalent, but Specification_Suffix is obsolescent.
If the value of the attribute is the empty string, it indicates to the
Project Manager that the only specifications/header files for the language
are those specified with attributes Spec or
Specification_Exceptions.
If Spec_Suffix("Ada") is not specified, then the default is
".ads".
A non empty value must satisfy the following requirements:
It must include at least one dot
If Dot_Replacement is a single dot, then it cannot include
more than one dot.
Body_Suffix and Implementation_Suffix:
These attributes are equivalent and specify the extension used for file names that contain
code (bodies in Ada). They are indexed by the language name.
Implementation_Suffix is obsolescent and fully replaced by the first attribute.
For each language of a project, one of these two attributes needs to be
specified, either in the project itself or in the configuration project file.
If the value of the attribute is the empty string, it indicates to the
Project Manager that the only source files for the language
are those specified with attributes Body or
Implementation_Exceptions.
These attributes must satisfy the same requirements as Spec_Suffix.
In addition, they must be different from any of the values in
Spec_Suffix.
If Body_Suffix("Ada") is not specified, then the default is
".adb".
If Body_Suffix("Ada") and Spec_Suffix("Ada") end with the
same string, then a file name that ends with the longest of these two
suffixes will be a body if the longest suffix is Body_Suffix("Ada"),
or a spec if the longest suffix is Spec_Suffix("Ada").
If the suffix does not start with a '.', a file with a name exactly equal to
the suffix will also be part of the project (for instance if you define the
suffix as Makefile.in, a file called Makefile.in will be part
of the project. This capability is usually not of interest when building.
However, it might become useful when a project is also used to
find the list of source files in an editor, like the GNAT Programming System
(GPS).
Separate_Suffix:
This attribute is specific to Ada. It denotes the suffix used in file names for files
that contain subunits (separate bodies). If it is not specified, then it defaults to
same value as Body_Suffix("Ada").
The value of this attribute cannot be the empty string.
Otherwise, the same rules apply as for the Body_Suffix attribute.
Spec or Specification:
These attributes are equivalent.
The Spec attribute 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.
These attribute play the same role as Spec, but for Ada bodies.
Specification_Exceptions and Implementation_Exceptions:
These attributes define exceptions to the naming scheme for languages
other than Ada. They are indexed by the language name, and contain
a list of file names respectively for headers and source code.
As an example of several of these attributes,
the following package models the Apex file naming rules:
A subsystem is a coherent part of the complete system to be built. It is
represented by a set of sources and a single object directory. A system can
consist of a single subsystem when it is simple as we have seen in the
earlier examples. 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, we’ll enhance the previous example. Let’s assume some
sources of our Build project depend on other sources.
For instance, when building a graphical interface, it is usual to depend upon
a graphical library toolkit such as GtkAda. Furthermore, we also need
sources from a logging module we had previously written.
GtkAda comes with its own project file (appropriately called
gtkada.gpr), and we will assume we have already built a project
called logging.gpr for the logging module. With the information provided
so far in build.gpr, building the application would fail with an error
indicating that the gtkada and logging units that are relied upon by the sources
of this project cannot be found.
This is solved by defining build.gpr to import the gtkada and
logging projects: this is done by adding the following with clauses
at the beginning of our project:
with"gtkada.gpr";with"a/b/logging.gpr";project Buildis...-- as beforeend Build;
When such a project is compiled, gprbuild will automatically check
the imported projects and recompile their sources when needed. It will also
recompile the sources from Build when needed, and finally create the
executable.
In some cases, the implementation units needed to recompile a
project are not available, or come from some third party and you do not want to
recompile it yourself. In this case, set the attribute Externally_Built to
"true", indicating to the builder that this project can be assumed to be
up-to-date, and should not be considered for recompilation. In Ada, if the
sources of this externally built project were compiled with another version of
the compiler or with incompatible options, the binder will issue an error.
The project’s with clause has several effects. It provides source
visibility between projects during the compilation process. It also guarantees
that the necessary object files from Logging and GtkAda are
available when linking Build.
As can be seen in this example, the syntax for importing projects is similar
to the syntax for importing compilation units in Ada. However, project files
use literal strings instead of names, and the with clause identifies
project files rather than packages.
Each literal string after with is the path
(absolute or relative) to a project file. The .gpr extension is
optional, but we recommend adding it. If no extension is specified,
and no project file with the .gpr extension is found, then
the file is searched for exactly as written in the with clause,
that is with no extension.
As mentioned above, the path after a with has to be a literal
string, and you cannot use concatenation, or lookup the value of external
variables to change the directories from which a project is loaded.
A solution if you need something like this is to use aggregate projects
(see Aggregate Projects).
When a relative path or a base name is used, the
project files are searched relative to each of the directories in the
project path. This path includes all the directories found by the
following procedure, in decreasing order of priority; the first matching
file is used:
First, the file is searched relative to the directory that contains the
current project file.
Then it is searched relative to all the directories specified in the
environment variables GPR_PROJECT_PATH_FILE,
GPR_PROJECT_PATH and ADA_PROJECT_PATH (in that order) if they exist.
The value of GPR_PROJECT_PATH_FILE, when defined, is the path name of
a text file that contains project directory path names, one per line.
GPR_PROJECT_PATH and ADA_PROJECT_PATH, when defined, contain
project directory path names separated by directory separators.
ADA_PROJECT_PATH is used for compatibility, it is recommended to
use GPR_PROJECT_PATH_FILE or GPR_PROJECT_PATH.
Finally, it is searched relative to the default project directories.
The following locations are searched, in the specified order:
<compiler_prefix>/<target>/<runtime>/share/gpr
<compiler_prefix>/<target>/<runtime>/lib/gnat
<compiler_prefix>/<target>/share/gpr
<compiler_prefix>/<target>/lib/gnat
<compiler_prefix>/share/gpr/
<compiler_prefix>/lib/gnat/
The first two paths are only added if the explicit runtime is specified either
via --RTS switch or via Runtime attribute. <target> can be
communicated via --target switch or Target attribute, otherwise
default target will be used. <compiler_prefix> is typically discovered
automatically based on target, runtime and language information.
In our example, gtkada.gpr is found in the predefined directory if
it was installed at the same root as GNAT.
Some tools also support extending the project path from the command line,
generally through the -aP. You can see the value of the project
path by using the gprls-v command.
Any symbolic link will be fully resolved in the directory of the
importing project file before the imported project file is examined.
Any source file in the imported project can be used by the sources of the
importing project, transitively.
Thus if A imports B, which imports C, the sources of
A may depend on the sources of C, even if A does not
import C explicitly. However, this is not recommended, because if
and when B ceases to import C, some sources in A will
no longer compile. GPRbuild has a switch --no-indirect-imports
that will report such indirect dependencies.
Project import closure
The project import closure for a given project proj is the set
of projects consisting of proj itself, together with each
project that is directly or indirectly imported by proj.
The import may be from either a with or, as will be explained below,
a limitedwith.
Note
One very important aspect of a project import closure is that
a given source can only belong to one project in this set
(otherwise the project manager
would not know which settings apply to it and when to recompile it).
Thus different project files do not usually share source directories, or,
when they do, they need to specify precisely which project owns which sources
using the attribute Source_Files or equivalent. By contrast, two projects
can each own a source with the same base file name as long as they reside in
different directories. The latter is not true for Ada sources because of the
correlation between source files and Ada units.
In general, cyclic import dependencies are forbidden:
if project A withs project B (directly or indirectly) then B
is not allowed to with A. However, there are cases when cyclic
dependencies at the project level are necessary, as dependencies at
the source level may exist both ways between A’s sources and B’s sources.
For these cases, another form of import between projects is supplied:
the limited with.
A project A that imports a project B with a simple with may also be
imported, directly or indirectly, by B through a limitedwith.
The difference between a simple with and limitedwith is that
the name of a project imported with a limitedwith cannot be used
in the importing project. In particular, its packages cannot be renamed and
its variables cannot be referenced.
with"b.gpr";with"c.gpr";project AisforExec_DiruseB'Exec_Dir;-- OKend A;limitedwith"a.gpr";-- Cyclic dependency: A -> B -> Aproject BisforExec_DiruseA'Exec_Dir;-- not OKend B;with"d.gpr";project Cisend C;limitedwith"a.gpr";-- Cyclic dependency: A -> C -> D -> Aproject DisforExec_DiruseA'Exec_Dir;-- not OKend D;
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 might all have the same compilation switches.
As seen above (see Tools Options in Project Files), setting compilation
switches for all sources of a subsystem is simple: it is just a matter of
adding a Compiler'Default_Switches attribute to each project file with
the same value. However, that would entail duplication of data, and both places would need
to be changed in order to recompile the whole application with different
switches. This may be a serious issue if there are many subsystems and thus
many project files to edit.
There are two main approaches to avoiding this duplication:
Since build.gpr imports logging.gpr, we could change the former
to reference the attribute in Logging, either through a package renaming,
or by referencing the attribute. The following example shows both cases:
The solution used for Compiler gets the same value for all
attributes of the package, but you cannot modify anything from the
package (adding extra switches or some exceptions). The solution
for the Binder package 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:
The second approach is to define the switches in a separate project.
That project does not contain any source files (thus, as opposed to
the first example, none of the projects plays a special role), and
will only be used to define the attributes. Such a project is
typically named shared.gpr.
As with the first example, we could have chosen to set the attributes
one by one rather than to rename a package. The reason we explicitly
indicate that Shared has no sources is so that it can be created
in any directory, and we are sure it shares no sources with Build
or Logging, which would be invalid.
Note the additional use of the abstract qualifier in shared.gpr.
This qualifier is optional, but helps convey the message that we do not
intend this project to have source files (see Qualified Projects for
additional information about project qualifiers).
We have already seen many examples of attributes used to specify a particular
option for one of the tools involved in the build process. Most of those
attributes are project specific. That is 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, when defined for a “main” project
proj, also apply to all other projects in the project import closure of proj.
A main project is a project explicitly specified on the command line.
Such attributes are known as global attributes;
here are several that are commonly used:
Builder’Global_Configuration_Pragmas:
This attribute specifies a file that contains configuration pragmas
to use when building executables. These pragmas apply to all
executables built from this project import closure. As noted earlier,
additional pragmas can be specified on a per-project basis by setting the
Compiler'Local_Configuration_Pragmas attribute.
Builder’Global_Compilation_Switches:
This attribute is a list of compiler switches that apply when compiling any
source file in the project import closure. These switches are used in addition
to the ones defined in the Compiler package, which only apply to
the sources of the corresponding project. This attribute is indexed by
the name of the language.
Using such global capabilities is convenient, but care is needed since
it can also lead to unexpected
behavior. An example is when several subsystems are shared among different main
projects but the different global attributes are not
compatible. Note that using aggregate projects can be a safer and more powerful
alternative to global attributes.
Various project properties can be modified based on scenarios. These
are user-defined modes (the values of project variables and attributes)
that determine the behavior of a project, based on the
values of externally defined variables. 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, while the latter would request an increased level of code
optimization).
Let’s enhance our example to support debug and release modes. The issue is to
let the user choose which kind of system to build: use -g as a
compiler switch in debug mode and -O2 in release mode. We will also
set up 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 two modes.
One approach is to create two different project files, say
build_debug.gpr and build_release.gpr, that set the appropriate
attributes as explained in previous sections. This solution does not scale
well, because in the presence of multiple projects depending on each other, you
will also have to duplicate the complete set of projects and adapt the project
files accordingly.
Instead, project files support the notion of scenarios controlled
by the values of externally defined variables.
Such values can come from several sources (in decreasing
order of priority):
Command line:
When launching gprbuild, the user can pass
-X switches to define the external variables. In
our case, the command line might look like
gprbuild-Pbuild.gpr-Xmode=release
which defines the external variable named mode and sets its value to
"release".
Environment variables:
When the external value does not come from the command line, it can come from
the value of an environment variable of the appropriate name.
In our case, if an environment variable named mode
exists, its value will be used.
Tool mode:
In the special case of the GPR_TOOL variable, if its value has not been
specified via the command line or as an environment variable, the various
tools set this variable to a value proper to each tool. gprbuild sets this
value to gprbuild. See the documentation of other tools to find out which
value they set this variable to.
External function second parameter.
Once an external variable is defined, its value needs to be obtained by
the project. The general form is to use
the predefined function external, which returns the current value of
the external variable. For instance, we could set up the object directory to point to
either obj/debug or obj/release by changing our project to
project BuildisforObject_Diruse"obj/"&external("mode","debug");...-- as beforeend Build;
The second parameter to external is optional, and is the default
value to use if mode is not set from the command line or the environment.
If the second parameter is not supplied, and there is no external or
environment variable named by the first parameter, then an error is reported.
In order to set the switches according to the different scenarios, other
constructs are needed, such as typed variables and case constructions.
A typed variable is a variable that
can take only a limited number of values, similar to variable from an
enumeration type in Ada.
Such a variable can then be used in a case construction, resulting in
conditional sections in the project. The following example shows how
this can be done:
project BuildistypeMode_Typeis("debug","release");-- all possible valuesMode:Mode_Type:=external("mode","debug");-- a typed variablepackage CompileriscaseModeiswhen"debug"=>forSwitches("Ada")use("-g");when"release"=>forSwitches("Ada")use("-O2");end case;end Compiler;end Build;
This project is larger than the ones we have seen previously,
but it has become much more flexible.
The Mode_Type type defines the only valid values for the
Mode variable. If
any other value is read from the environment, an error is reported and the
project is considered as invalid.
The Mode variable is initialized with an external value
defaulting to "debug". This default could be omitted and that would
force the user to define the value. Finally, we can use a case construction to set the
switches depending on the scenario the user has chosen.
Most aspects of a project can depend on scenarios. The notable exception
is the identity of an imported project (via a with or limitedwith
clause), which cannot depend on a scenario.
Scenarios work analogously across projects in a project import closure.
You can either
duplicate a variable similar to Mode in each of the projects (as long
as the first argument to external is always the same and the type is
the same), or simply set the variable in the shared.gpr project
(see Sharing between Projects).
So far, we have seen examples of projects that create executables. However,
it is also possible to create libraries instead. A library is a specific
type of subsystem where, for convenience, objects are grouped together
using system-specific means such as archives or Windows DLLs.
Library projects provide a system- and language-independent way of building
both static and dynamic libraries. They also support the concept of
standalone libraries (SAL) which offer two significant properties: the
elaboration (e.g. initialization) of the library is either automatic or
very simple; a change in the
implementation part of the library implies minimal post-compilation actions on
the complete system and potentially no action at all for the rest of the
system in the case of dynamic SALs.
There is a restriction on shared library projects: by default, they are only
allowed to import other shared library projects. They are not allowed to
import non-library projects or static library projects.
The GNAT Project Manager takes complete care of the library build, rebuild and
installation tasks, including recompilation of the source files for which
objects do not exist or are not up to date, assembly of the library archive, and
installation of the library (i.e., copying associated source, object and
ALI files to the specified location).
Let’s enhance our example and transform the logging subsystem into a
library. In order to do so, a few changes need to be made to
logging.gpr. Some attributes need to be defined: at least
Library_Name and Library_Dir; in addition, some other attributes
can be used to specify specific aspects of the library. For readability, it is
also recommended (although not mandatory), to use the qualifier library
in front of the project keyword.
Library_Name:
This attribute is the name of the library to be built. There is no
restriction on the name of a library imposed by the project manager, except
for stand-alone libraries whose names must follow the syntax of Ada
identifiers; however, there may be system-specific restrictions on the name.
In general, we recommend using only alphanumeric characters (and
possibly single underscores), to help portability.
Library_Dir:
This attribute is the path (absolute or relative) of the directory where
the library is to be installed. In the process of building a library,
the sources are compiled and the object files are placed in the explicitly- or
implicitly specified 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 exist and be
writable. It must also be different from the object directory so that cleanup
activities in the Library_Dir do not affect recompilation needs.
Here is the new version of logging.gpr that makes it a library:
libraryproject Loggingis-- "library" is optionalforLibrary_Nameuse"logging";-- will create "liblogging.a" on UnixforObject_Diruse"obj";forLibrary_Diruse"lib";-- different from object_dirend Logging;
Once the above two attributes are defined, the library project is valid and
is sufficient for building a library with default characteristics.
Other library-related attributes can be used to change the defaults:
Library_Kind:
The value of this attribute must be either "static",
"static-pic", "dynamic" or "relocatable" (the last 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). A
static-pic library is also an archive, but the code is Position Independent
Code, usually compiled with the switch -fPIC. When the library is set to
be dynamic, a separate image is created that will be loaded independently,
usually at the start of the main program execution. Support for dynamic
libraries is very platform specific, for instance on Windows it takes the
form of a DLL while on GNU/Linux, it is a dynamic elf image whose suffix is
usually .so. Library project files, on the other hand, can be written
in a platform independent way so that the same project file can be used to
build a library on different operating systems.
If you need to build both a static and a dynamic library, we recommend
using 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 that uses scenarios to indicate
the various kinds of library to be built and their corresponding object_dir.
Library_ALI_Dir:
This attribute may be specified to indicate the directory where the ALI
files of the library are installed. By default, they are copied into the
Library_Dir directory, but as for the executables where we have a
separate Exec_Dir attribute, you might want to put them in a separate
directory since there may be hundreds of such files. The same restrictions as for
the Library_Dir attribute apply.
Library_Version:
This attribute is platform dependent, and has no effect on Windows.
On Unix, it is used only for dynamic libraries as the internal
name of the library (the “soname”). If the library file name (built
from the Library_Name) is different from the Library_Version,
then the library file will be a symbolic link to the actual file whose name
will be Library_Version. This follows the usual installation schemes
for dynamic libraries on many Unix systems.
After the compilation, the directory lib will contain both a
liblogging.so.1 library and a symbolic link to it called
liblogging.so.
Library_GCC:
This attribute is the name of the tool to use instead of gcc to link shared
libraries. A common use of this attribute is to define a wrapper script that
accomplishes specific actions before calling gcc (which itself calls the
linker to build the library image).
Library_Options:
This attribute may be used to specify additional switches (“last switches”)
when linking a shared library or a static standalone library.
In the case of a simple static library, the values for this attribute are
restricted to paths to object files. Those paths may be absolute or relative
to the object directory.
Leading_Library_Options:
This attribute, which is taken into account only by GPRbuild, may be
used to specify leading options (“first switches”) when linking a shared
library.
When the builder detects that a project file is a library project file, it
recompiles all sources of the project that need recompilation and rebuilds 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 shared 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.
GPRbuild also allows building multi-language libraries when specifying
sources from multiple languages.
A non-library project NLP can import a library project LP. When the builder
is invoked on NLP, it always rebuilds LP even if all of the latter’s files are
up to date. For instance, let’s assume in our example that logging has
the following sources: log1.ads, log1.adb, log2.ads and
log2.adb. If log1.adb has been modified, then the library
liblogging will be rebuilt when compiling all the sources of
Build even if proc.ads, pack.ads and pack.adb
do not include a "withLog1".
To ensure that all the sources in the Logging library are
up to date, and that all the sources of Build are also up to date,
the following two commands need to be used:
gprbuild-Plogging.gpr
gprbuild-Pbuild.gpr
All ALI files will also be copied from the object directory to the
library directory. To build executables, GPRbuild will use the
library rather than the individual object files.
Library projects can also be useful to specify a library that needs to be used
but, for some reason, cannot be rebuilt. Such a situation may arise when some
of the library sources are not available. Such library projects need to use the
Externally_Built attribute as in the example below:
In the case of externally built libraries, the Object_Dir
attribute does not need to be specified because it will never be
used.
The main effect of using such an externally built library project is mostly to
affect the linker command in order to reference the desired library. It can
also be achieved by using Linker'Linker_Options or Linker'Switches
in the project corresponding to the subsystem needing this external library.
This latter method is more straightforward in simple cases but when several
subsystems depend upon the same external library, finding the proper place
for the Linker'Linker_Options might not be easy and if it is
not placed properly, the final link command is likely to present ordering issues.
In such a situation, it is better to use the externally built library project
so that all other subsystems depending on it can declare this dependency through
a project with clause, which in turn will trigger the builder to find
the proper order of libraries in the final link command.
A stand-alone library is a library that contains the necessary code to
elaborate the Ada units that are included in the library. A stand-alone
library is a convenient way to add an Ada subsystem to a more global system
whose main is not in Ada since it makes the elaboration of the Ada part mostly
transparent. However, stand-alone libraries are also useful when the main is in
Ada: they provide a means for minimizing relinking and redeployment of complex
systems when localized changes are made.
The name of a stand-alone library, specified with attribute
Library_Name, must have the syntax of an Ada identifier.
The most prominent characteristic of a stand-alone library is that it offers a
distinction between interface units and implementation units. Only the former
are visible to units outside the library. A stand-alone library project is thus
characterized by a third attribute, usually Library_Interface, in addition
to the two attributes that make a project a Library Project
(Library_Name and Library_Dir). This third attribute may also be
Interfaces. Library_Interface only works when the interface is in Ada
and takes a list of units as parameter. Interfaces works for any supported
language and takes a list of sources as parameter.
Library_Interface:
This attribute defines an explicit subset of the units of the project. Units
from projects importing this library project may only “with” units whose
sources are listed in the Library_Interface. Other sources are
considered implementation units.
forLibrary_Diruse"lib";forLibrary_Nameuse"logging";forLibrary_Interfaceuse("lib1","lib2");-- unit names
Interfaces
This attribute defines an explicit subset of the source files of a project.
Sources from projects importing this project, can only depend on sources from
this subset. This attribute can be used on non library projects. It can also
be used as a replacement for attribute Library_Interface, in which
case, units have to be replaced by source files. For multi-language library
projects, it is the only way to make the project a Stand-Alone Library project
whose interface is not purely Ada.
Library_Standalone:
This attribute defines the kind of stand-alone library to
build. Values are either standard (the default), no or
encapsulated. When standard is used the code to elaborate and
finalize the library is embedded, when encapsulated is used the
library can furthermore depend only on static libraries (including
the GNAT runtime). This attribute can be set to no to make it clear
that the library should not be stand-alone in which case the
Library_Interface should not defined. Note that this attribute
only applies to shared libraries, so Library_Kind must be set
to dynamic or relocatable.
forLibrary_Diruse"lib";forLibrary_Nameuse"logging";forLibrary_Kinduse"dynamic";forLibrary_Interfaceuse("lib1","lib2");-- unit namesforLibrary_Standaloneuse"encapsulated";
In order to include the elaboration code in the stand-alone library, the binder
is invoked on the closure of the library units creating a package whose name
depends on the library name (b~logging.ads/b in the example).
This binder-generated package includes initialization and finalization
procedures whose names depend on the library name (logginginit and
loggingfinal in the example). The object corresponding to this package is
included in the library.
Library_Auto_Init:
A dynamic stand-alone Library is automatically initialized
if automatic initialization of stand-alone Libraries is supported on the
platform and if attribute Library_Auto_Init is not specified or
is specified with the value "true".
Whether a static stand-alone Library is automatically initialized
is platform dependent. Specifying "false" for the Library_Auto_Init
attribute prevents automatic initialization.
When a non-automatically initialized stand-alone library is used in an
executable, its initialization procedure must be called before any service of
the library is used. When the main subprogram is in Ada, it may mean that the
initialization procedure has to be called during elaboration of another
package.
Library_Dir:
For a stand-alone library, only the ALI files of the interface units
(those that are listed in attribute Library_Interface) are copied to
the library directory. As a consequence, only the interface units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
Binder’Default_Switches:
When a stand-alone library is bound, the switches that are specified in
the attribute Binder'Default_Switches("Ada") are
used in the call to gnatbind.
Library_Src_Dir:
This attribute defines the location (absolute or relative to the project
directory) where the sources of the interface units are copied at
installation time.
These sources includes the specs of the interface units along with the
closure of sources necessary to compile them successfully. That may include
bodies and subunits, when pragmas Inline are used, or when there are
generic units in specs. This directory cannot point to the object directory
or one of the source directories, but it can point to the library directory,
which is the default value for this attribute.
Library_Symbol_Policy:
This attribute controls the export of symbols on some platforms (like
Windows, GNU/Linux). It is not supported on all platforms (where it
will just have no effect). It may have one of the
following values:
"restricted": The exported symbols will be restricted to the one
from the interface of the stand-alone library. This is either computed
automatically or using the Library_Symbol_File if specified.
"unrestricted": All symbols from the stand-alone library are exported.
Library_Symbol_File
This attribute may define the name of the symbol file to be used when
building a stand-alone library when the symbol policy is
"restricted", on platforms that support symbol control. This file
must contain one symbol per line and only those symbols will be
exported from the stand-alone library.
When using project files, a usable version of the library is created in the
directory specified by the Library_Dir attribute of the library
project file. Thus no further action is needed in order to make use of
the libraries that are built as part of the general application build.
You may want to install a library in a context different from where the library
is built. This situation arises with third party suppliers, who may want
to distribute a library in binary form where the user is not expected to be
able to recompile the library. The simplest option in this case is to provide
a project file slightly different from the one used to build the library, by
using the Externally_Built attribute. See Using Library Projects.
Another option is to use gprinstall to install the library in a
different context than the build location. The gprinstall tool automatically
generates a project to use this library, and also copies the minimum set of
sources needed to use the library to the install location.
See Package Install Attributes.
During development of a large system, it is sometimes necessary to use
modified versions of some of the source files, without changing the original
sources. This can be achieved through the project extension facility.
Suppose that our example Build project is built every night for the whole
team, in some shared directory. A developer usually needs 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 since that could require too much disk space and too
much time to recompile everything. A better approach is to override some of
the source files in a separate directory, while still using the object files
generated at night for the non-overridden shared sources.
Another use case is a large software system with multiple implementations of
a common interface; in Ada terms, multiple versions of a package body for the
same spec, or perhaps different versions of a package spec that have the same
visible part but different private parts. For example, one package might be
safe for use in tasking programs, while another might be used only in
sequential applications.
A third example is different versions of the same system. For instance,
assume that a Common project is used by two development branches. One of
the branches has now been frozen, and no further change can be done to it or
to Common. However, on the other development branch the sources in Common
are still evolving. A new version of the subsystem is needed, which reuses
as much as possible from the original.
Each of these can be implemented in GNAT using project extension:
If one project extends another project (the base project) then by default
all source files of the base project are inherited by the extending project,
but the latter can override any of the base project’s source files with a
new version, and can also add new files or remove unnecessary ones. A project
can extend at most one base project.
This facility is somewhat analogous to class extension (with single
inheritance) in object-oriented programming. Project extension hierarchies
are permitted (an extending project may itself serve as a base project and
be extended), and a project that extends a project can also import other projects.
An extending project implicitly inherits all the sources and objects from
its base project. It is possible to create a new version of some of
the sources in one of the additional source directories of the extending
project. Those new versions hide the original versions. As noted above,
adding new sources or removing existing ones is also possible. Here is an
example of how to extend the project Build from previous examples:
project Workextends"../bld/build.gpr"isend Work;
The project after the extends keyword is the base project 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. The Work project does not
specify source or object directories, so the default values for these
attributes will be used; that is, the current directory (where project
Work is placed). We can compile that project with
gprbuild-Pwork
If no sources have been placed in the current directory, this command
has no effect, since this project does not change the
sources it inherited from Build and thus all the object files
in Build and its dependencies are still valid and are reused
automatically.
Suppose we now want to supply an alternative version of pack.adb
but use the existing versions of pack.ads and proc.adb.
We can create the new file in the Work project’s directory (for example by
copying the one from the Build project and making changes to it).
If new packages are needed at the same time, we simply create new files
in the source directory of the extending project.
When we recompile, GPRbuild will now automatically recompile
this file (thus creating pack.o in the current directory) and
any file that depends on it (thus creating proc.o). Finally, the
executable is also linked locally.
Note that we could have obtained the desired behavior using project import
rather than project inheritance. Some project proj would contain
the sources for pack.ads and proc.adb, and Work would
import proj and add pack.adb. In this situation proj
cannot contain the original version of pack.adb since otherwise
two versions of the same unit would be in project import closure of proj,
which is not allowed. In general we do not recommended placing the spec and
body of a unit in different projects, since this affects their autonomy and
reusability.
In a project file that extends another project, it is possible to
indicate that an inherited source is not part of the sources of the
extending project. This is necessary, for example, when a package spec has
been overridden in such a way that a body is forbidden. 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.
Two attributes are available for this purpose:
Excluded_Source_Files, whose value is a list of file names, and
Excluded_Source_List_File, whose value is the path of a text file
containing one file name per line.
project Workextends"../bld/build.gpr"isforSource_Filesuse("pack.ads");-- New spec of Pkg does not need a completionforExcluded_Source_Filesuse("pack.adb");end Work;
All tool packages that are not declared in the extending project are inherited from
the base project, with their attributes, with the exception of
Linker'Linker_Options which is never inherited. In particular, an
extending project retains all the switches specified in its base project.
At the project level, if they are not declared in the extending project, some
attributes are inherited from the base project. They are:
Languages, Main (for a root non library project) and
Library_Name (for a project extending a library project).
One of the fundamental restrictions for project extension is the following:
A project is not allowed to import, directly or indirectly, both an extending
project P and also some project that P extends either directly or
indirectly
In the absence of this rule, two imports might access different versions of the
same source file, or different sets of tool switches for the same source file
(one from the base project and the other from an extending project).
As an example of this problem, consider the following set of project files:
a.gpr which contains the source files foo.ads and
foo.adb, among others
b.gpr which imports a.gpr (one of its source files
withs foo)
c.gpr which imports b.gpr
Suppose we want to extend the projects as follows:
a_ext.gpr extends a.gpr and overrides foo.adb
c_ext.gpr extends c.gpr, overriding one of its source files
Since c_ext.gpr needs to access sources in b.gpr, it will
import b.gpr
Finally, main.gpr needs to access the overridden source files in
a_ext.gpr and c_ext.gpr and thus will import these two
projects.
This project structure is shown in figure#.
Fig. 2.1 Example of Source File Ambiguity from imports/extends Violation¶
This violates the restriction above, since main.gpr imports the extending project
a_ext.gpr and also (indirectly through c_ext.gpr and b.gpr)
the project a.gpr that a_ext.gpr extends.
The problem is that the import path through c_ext.gpr and b.gpr would build with the version
of foo.adb from a.gpr, whereas the import path through a_ext.gpr would use that project’s
version of foo.adb.
The error will be detected and reported by gprbuild.
A solution is to introduce an “empty” extension of b.gpr, which is imported by
c_ext.gpr and imports a_ext.gpr:
Fig. 2.2 Using “Empty” Project Extension to Avoid imports/extends Violation¶
There is now no ambiguity over which version of foo.adb to use;
it will be the one from a_ext.gpr.
When extending a large system spanning multiple projects, it is often
inconvenient to extend every project in the project import closure that
is impacted by a small change introduced in a low layer. In such cases,
it is possible to create an implicit extension of an entire hierarchy
using the extends all relationship.
When a project P is extended using extends all inheritance, all projects
that are imported by P, both directly and indirectly, are considered virtually
extended. That is, the project manager creates implicit projects
that extend every project in the project import closure; all these implicit
projects do not control sources on their own and use the object directory of
the extends all project.
It is possible to explicitly extend one or more projects in the import closure
in order to adapt the sources. These extending projects must be imported by
the extendsall project, which will replace the corresponding virtual
projects with the explicit ones.
When building such a project closure extension, the project manager will
ensure recompilation of both the modified sources and the sources in implicit
extending projects that depend on them.
To illustrate the extendsall feature, here’s a slight variation on the
earlier examples. We have a Main project that imports project C,
which imports B, which imports A. The source files in Main refer
to compilation units whose sources are in C and A. (Recall that
imports is transitive, so A is implicitly accessible in Main.)
This project structure is shown in figure#.
Fig. 2.3 Simple Project Structure before Extension¶
Suppose that we want to extend a.gpr, overriding one of
its source files, and create a new version of main.gpr
that can access the overridden file in the extending project
a_ext.gpr and otherwise use the sources in b.gpr
and c.gpr.
Instead of explicitly defining empty projects to extend b.gpr and
c.gpr, we can create a new project main_ext.gpr that does an
extendsall of main.gpr and imports a_ext.gpr. The
extends_all will implicitly create the empty projects b_ext.gpr
and c_ext.gpr as well as the relevant import relationships:
c_ext.gpr will import
b_ext.gpr, which will import a_ext.gpr
main_ext.gpr will implicitly import c_ext.gpr since
main.gpr imports c.gpr.
The resulting project structure is shown in figure#,
where the italicized labels, dashed arrows, and dashed boxes indicate what was
added implicitly as an effect of the extends_all.
When project main_ext.gpr is built, the entire modified project space is
considered for recompilation, including the sources from b.gpr and
c.gpr that are affected by the changes to a.gpr.
In order to more clearly express the relationship between
a project Q and some other project P that Q
either imports or extends, you can use the notation P.Q
to declare Q as a child of P.
The project P is then referred to as the parent of Q.
This is useful, for example, when the purpose of the child
is to serve as a testing subsystem for the parent.
The visibility of the child on the sources and other properties
of the parent is determined by whether the child imports or
extends the parent. No additional visibility is obtained by
declaring the project as a child; the parent.child notation
serves solely as a naming convention to convey to the reader
the closeness of the relationship between the projects.
Child projects may in turn be the parents of other projects, so
in general a project hierarchy can be created. A project
may be the parent of many child projects, but a child project
can only have one parent.
Note that child projects have slightly different semantics from
their Ada language analog (child units). An Ada child unit implicitly
withs its parent, whereas a child project must have an explicit
with clause (or else extend its parent). The need to explicitly
with or extend the parent project helps avoid the error of
unintentionally creating a child of some project that happens
to be on the project path.
Aggregate projects are an extension of the project paradigm, and are
designed to handle a few specific situations that cannot be solved directly
using standard projects. This section will present several such use
cases.
2.8.1. Building all main programs from a single project closure¶
A large application is typically organized into modules and submodules,
which are conveniently represented as a project graph (the project import
closure): a “root” project A withs the projects for modules B and C,
which in turn with projects for submodules.
Very often, modules will build their own executables (for testing
purposes for instance) or libraries (for easier reuse in various
contexts).
However, if you build your project through GPRbuild, using a syntax similar to
gprbuild-PA.gpr
this will only rebuild the main programs of project A, not those of the
imported projects B and C. Therefore you have to spawn several
GPRbuild commands, one per project, to build all executables.
This is somewhat inconvenient, but more importantly is inefficient
because GPRbuild 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.
To solve this problem you can define an aggregate projectAgg that
groups A, B and C:
this will build all main programs from A, B and C.
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 an 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.
2.8.2. Building a set of projects with a single command¶
Another application of aggregate projects is when you have multiple
applications and libraries that are built independently
(but can be built in parallel). For instance, you might have a project graph
rooted at A, and another one (which might share some subprojects) rooted
at B.
Using only GPRbuild, you could do
gprbuild-PA.gpr
gprbuild-PB.gpr
to build both. But again, GPRbuild has to do some duplicate work for
those files that are shared between the two, and cannot truly build
things in parallel efficiently.
If the two projects are really independent, share no sources other
than through a common subproject, and have no source files with a
common basename, you could create a project C that imports A and
B. But these restrictions are often too strong, and one has to build
them independently. An aggregate project does not have these
limitations and can aggregate two project graphs that have common
sources:
This scenario is particularly useful in environments like VxWorks 653
where the applications running in the multiple partitions can be built
in parallel through a single GPRbuild command. This also works well
with Annex E of the Ada Language Reference Manual.
The environment variables at the time you launch GPRbuild
will influence the view these tools have of the project
(for example PATH to find the compiler, ADA_PROJECT_PATH or
GPR_PROJECT_PATH to find the projects, and environment variables
that are referenced in project files
through the external built-in function). 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 benefits is that
you can put the aggregate project under configuration management, and
make sure all your users have a consistent environment when
building. For example:
Another use of aggregate projects is to simulate the
referencing of external variables in with clauses,
For technical reasons the following project file is not
allowed:
The loading of aggregate projects is optimized in GPRbuild,
so that all files are searched for only once on the disk
(thus reducing the number of system calls and yielding faster
compilation times, especially on systems with sources on remote
servers). As part of the loading, GPRbuild
computes how and where a source file should be compiled, and even if it is
located several times in the aggregated projects it will be compiled only
once.
Since there is no ambiguity as to which switches should be used, individual
compilations, binds and links can be performed in parallel (through the usual
-j switch) and this can be done while maximizing the use of CPUs
(compared to launching multiple GPRbuild commands in parallel). The -j
option can control parallelization of compilation, binding, and linking
separately with -jc, -jb, and -jl variants accordingly.
An aggregate project follows the general syntax of project files. The
recommended extension is still .gpr. However, a special
aggregate qualifier must appear before the keyword
project.
An aggregate project cannot with any other project (standard or
aggregate), except an abstract project (which can be used to share attribute
values). Also, aggregate projects cannot be extended or imported though a
with clause by any other project. Building other aggregate projects from
an aggregate project is done through the Project_Files attribute (see below).
An aggregate project does not have any source files directly (only
through other standard projects). Therefore a number of the standard
attributes and packages are forbidden in an aggregate project. Here is a
(non exhaustive) list:
Languages
Source_Files, Source_List_File and other attributes dealing with
list of sources.
Source_Dirs and Exec_Dir
Library_Dir, Library_Name and other library-related attributes
Main
Roots
Externally_Built
Inherit_Source_Path
Excluded_Source_Dirs
Locally_Removed_Files
Excluded_Source_Files
Excluded_Source_List_File
Interfaces
The Object_Dir attribute is allowed and used by some analysis tools such
as gnatcheck to store intermediate files and aggregated results. The
attribute value is just ignored by the compilation toolchain, for which every
artifact of interest is best associated with the leaf non aggregate projects
and stored in the corresponding Object_Dir.
The package Naming and packages that control the compilation process
(Compiler, Binder, Linker and Install) are forbidden.
The following three attributes can be used only in an aggregate project:
Project_Files:
This attribute is compulsory.
It specifies a list of constituent .gpr files
that are grouped in the aggregate. The list may be empty. The project
files can be any projects except configuration or abstract projects;
they can be other aggregate projects. When
grouping standard projects, you can have both the root of a project import
closure (and you do not need to specify all its imported projects), and
any project within the closure.
The basic 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 specify projects that do not use the Main
attribute or the Library_* attributes, and the result will be to
build all their source files (not just the ones needed by other
projects).
The file can include paths (absolute or relative). Paths are relative to
the location of the aggregate project file itself (if you use a base name,
the .gpr file is expected in the same directory as the aggregate
project file). The environment variables ADA_PROJECT_PATH,
GPR_PROJECT_PATH and GPR_PROJECT_PATH_FILE are not used to
find the project files. The extension .gpr is mandatory, since
this attribute contains file names, not project names.
Paths can also include the "*" and "**" globbing patterns. The
latter indicates that any subdirectory (recursively) will be
searched for matching files. The "**" pattern can only occur at the
last position in the directory part (i.e. "a/**/*.gpr" is supported, but
not "**/a/*.gpr"). Starting the pattern with "**" is equivalent
to starting with "./**".
At present the pattern "*" is only allowed in the filename part, not
in the directory part. This is mostly for efficiency reasons to limit the
number of system calls that are needed.
Here are a few examples:
forProject_Filesuse("a.gpr","subdir/b.gpr");-- two specific projects relative to the directory of agg.gprforProject_Filesuse("**/*.gpr");-- all projects recursively, except in the current directoryforProject_Filesuse("**/*.gpr","*.gpr");-- all projects recursively
Project_Path:
This attribute can be used to specify a list of directories in
which to search for project files in with clauses.
When you specify a project in Project_Files (say x/y/a.gpr), and
a.gpr imports a project b.gpr, only b.gpr is
searched in the project path. The file a.gpr must be exactly at
diroftheaggregate/x/y/a.gpr.
This attribute, however, does not affect the search for the aggregated
project files specified with Project_Files.
Each aggregate project has its own Project_Path (thus if
agg1.gpr includes agg2.gpr, they can potentially both have a
different Project_Path).
This project path is defined as the concatenation, in this order, of:
the current directory;
followed by the command line -aP switches;
then the directories from the GPR_PROJECT_PATH and
ADA_PROJECT_PATH environment variables;
then the directories from the Project_Path attribute;
and finally the predefined directories.
In the example above, the project path for agg2.gpr is not influenced by
the attribute agg1’Project_Path, nor is agg1 influenced by
agg2’Project_Path.
This can potentially lead to errors. Consider the example in
figure#.
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.gprwithing 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.
Example:
forProject_Pathuse("/usr/local/gpr","gpr/");
External:
This attribute can be used to set the value of environment
variables as retrieved through the external function
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 aggregate project, and in the aggregated projects.
The exact value of an external variable comes from one of three
sources (each level overrides the previous levels):
An External attribute in aggregate project, for instance
for External (“BUILD_MODE”) use “DEBUG”;
Environment variables.
These override the value given by the attribute, so that
users can override the value set in the (presumably shared
with others team members) aggregate project.
The -X command line switch to gprbuild.
This always takes precedence.
This attribute is only taken into account in the main aggregate
project (i.e. the one specified on the command line to GPRbuild),
and ignored in other aggregate projects. It is invalid
in standard projects.
The goal is to have a consistent value in all
projects that are built through the aggregate, which would not
be the case in a “diamond” situation: 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.
When used in an aggregate project, only the following attributes of this
package are valid:
Switches:
This attribute gives the list of switches to use for GPRbuild.
Because no mains can be specified for aggregate projects, the only possible
index for attribute Switches is others. All other indexes will
be ignored.
Example:
forSwitches(others)use("-v","-k","-j8");
These switches are only read from the main aggregate project (the
one passed on the command line), and ignored in all other aggregate
projects or projects.
It can only contain builder switches, not compiler switches.
Global_Compilation_Switches
This attribute gives the list of compiler switches for the various
languages. For instance,
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 has 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, which
both depend on C. Here is an example for all of these projects:
all files from project A except a_file1.adb are compiled
with -O2-g, since the aggregate project has priority.
the file a_file1.adb is compiled with
:option”-O0, since Compiler'Switches has priority
all files from project B are compiled with
-O2, since the aggregate project has priority
all files from C are compiled with -O2-gnatn, except for
c_file1.adb which is compiled with -O0-g
Even though C is seen through two paths (through A and through
B), the switches used by the compiler are unambiguous.
Global_Configuration_Pragmas
This attribute can be used to specify a file containing
configuration pragmas, to be passed to the Ada compiler. Since we
ignore the package Builder in other aggregate projects and projects,
only those pragmas defined in the main aggregate project will be
taken into account.
Projects can locally add to those by using the
Compiler'Local_Configuration_Pragmas attribute if they need.
Global_Config_File
This attribute, indexed with a language name, can be used to specify a config
when compiling sources of the language. For Ada, these files are configuration
pragmas files.
For projects that are built through the aggregate mechanism, 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.
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 (for example a GUI, database access, and other)
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.
this will build all units from projects A, B and C and will create a
static library named libagg.a in the lagg
directory. An aggregate library project has the same set of
restrictions as a standard library project.
Note that a shared aggregate library project cannot aggregate a
static library project. In platforms where a compiler option is
required to create relocatable object files, a Builderpackage in the
aggregate library project may be used:
With the above aggregate library Builder package, the -fPIC
option will be passed to the compiler when building any source code
from projects a.gpr, b.gpr and c.gpr.
An aggregate library project follows the general syntax of project
files. The recommended extension is still .gpr. However, a special
aggregatelibrary qualifier must appear before the keyword
project.
An aggregate library project cannot with any other project
(standard or aggregate), except an abstract project which can be used
to share attribute values.
An aggregate library project does not have any source files directly (only
through other standard projects). Therefore a number of the standard
attributes and packages are forbidden in an aggregate library
project. Here is a (non-exhaustive) list:
Languages
Source_Files, Source_List_File and other attributes dealing with
a list of sources.
Source_Dirs and Exec_Dir
Main
Roots
Externally_Built
Inherit_Source_Path
Excluded_Source_Dirs
Locally_Removed_Files
Excluded_Source_Files
Excluded_Source_List_File
The only package that is allowed (and optional) is Builder.
The Project_Files attribute is used to
describe the aggregated projects whose object files have to be
included into the aggregate library. The environment variables
ADA_PROJECT_PATH, GPR_PROJECT_PATH and
GPR_PROJECT_PATH_FILE are not used to find the project files.
As for regular (not library) aggregate projects, the Object_Dir attribute
is allowed and used by some analysis tools in the same fashion.
This section describes the syntactic structure of project files, explains
the various constructs that can be used, and summarizes the available
attributes.
The syntax is presented in a notation similar to what is used in the Ada
Language Reference Manual. Curly braces ‘{’ and ‘}’ indicate 0 or more
occurrences of the enclosed construct, and square brackets ‘[’ and ‘]’ indicate
0 or 1 occurrence of the enclosed construct. Reserved words are enclosed
between apostrophes.
Project files have an Ada-like syntax. The minimal project file is:
project Emptyisend Empty;
The identifier Empty is the name of the project.
This project name must be present after the reserved
word end at the end of the project file, followed by a semicolon.
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").
Strings are used for values of attributes or as indexes for these
attributes. They are in general case sensitive, except when noted
otherwise (in particular, strings representing file names will be case
insensitive on some systems, so that "file.adb" and "File.adb" both
represent the same file).
Reserved words are the standard Ada 95 reserved words, plus several
others listed below, and cannot be used for identifiers.
In particular, the following Ada 95 reserved words are currently
used in project files:
Note that aggregate and library are qualifiers that may appear before
the keyword project, but they are not themselves keywords.
To avoid possible compatibility issues in the future, we recommend that
the reserved words introduced by Ada 2005 and Ada 2012 not be used as
identifiers in project files. Note also that new reserved words
may be added to the project file syntax in a later release.
Comments in project files have the same syntax as in Ada, two consecutive
hyphens through the end of the line.
A project may be an independent project, entirely defined by a single
project file. Any source file in an independent project depends only
on the predefined library and other source files in the same project.
Alternatively, a project may depend on other projects in various ways:
by importing them through context clauses (with clauses), or
by extending at most one other project (its base project).
A given project may exhibit either or both of these dependencies; for example:
The import dependencies form a directed graph, potentially cyclic when using
limited with. The subgraph reflecting the extends relationship is a tree
(hierarchy).
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 uniquely identifies 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 variables 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, and may not
appear in different context clauses for the same project.
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 clauses
in the cycle is a limitedwith.
A project’s immediate sources are the source files directly defined by
that project, either implicitly by residing in the project source directories,
or explicitly through any of the source-related attributes.
More generally, a project’s 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.
Immediately preceding the reserved project, a qualifier may be
specified which identifies the nature of the project. The following
qualifiers are allowed:
standard:
A standard project is a non-library project with source files.
This is the default (implicit) qualifier.
abstract:
A project with no source files.
Such a project must either have no declaration for attributes Source_Dirs,
Source_Files, Languages or Source_List_File, or one of
Source_Dirs, Source_Files, or Languages must be declared
as empty. If it extends another project, the base project must also be
an abstract project.
aggregate:
A project whose sources are aggregated from other project files.
aggregate library:
A library whose sources are aggregated from other project
or library project files.
library:
A library project must define both of the attributes
Library_Name and Library_Dir.
configuration:
A configuration project cannot be in a project tree.
It describes compilers and other tools to gprbuild.
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.
A project file may contain packages, which 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 Attributes for the list of attributes that each can contain).
Binder
This package specifies characteristics useful when invoking the binder either
directly via the gnat driver or when using GPRbuild.
See Main Subprograms.
Builder
This package specifies the compilation options used when building an
executable or a library for a project. Most of the options should be
set in one of Compiler, Binder or Linker packages,
but there are some general options that should be defined in this
package. See Main Subprograms, and Executable File Names in
particular.
Check
This package specifies the options used when calling the coding standard
verification tool gnatcheck. Its attributes
Default_Switches and Switches have the same semantics as for the package
Builder. The first string should always be -rules to specify
that all the other options belong to the -rules section of the
parameters to gnatcheck.
Clean
This package specifies the options used when cleaning a project or a project
tree using the tools gnatclean or gprclean.
Compiler
This package specifies the compilation options used by the compiler for
each language. See Tools Options in Project Files.
Cross_Reference
This package specifies the options used when calling the library tool
gnatxref via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Documentation
This package specifies the options used when calling the tool
gnatdoc.
Eliminate
This package specifies the options used when calling the tool
gnatelim. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Finder
This package specifies the options used when calling the search tool
gnatfind via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Gnatls
This package specifies the options to use when invoking gnatls
via the gnat driver.
Gnatstub
This package specifies the options used when calling the tool
gnatstub. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
IDE
This package specifies the options used when starting an integrated
development environment, for instance GPS or GNATbench.
Install
This package specifies the options used when installing a project
with gprinstall. See Package Install Attributes.
Linker
This package specifies the options used by the linker.
See Main Subprograms.
Metrics
This package specifies the options used when calling the tool
gnatmetric. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Naming
This package specifies the naming conventions that apply
to the source files in a project. In particular, these conventions are
used to automatically find all source files in the source directories,
or given a file name to find out its language for proper processing.
See Naming Schemes.
Pretty_Printer
This package specifies the options used when calling the formatting tool
gnatpp. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Remote
This package is used by GPRbuild to describe how distributed
compilation should be done.
Stack
This package specifies the options used when calling the tool
gnatstack. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Synchronize
This package specifies the options used when calling the tool
gnatsync via the gnat driver.
A package may contain attribute declarations,
variable declarations and case constructions, as will be
described below.
When there is ambiguity between a project name and a package name,
the name always designates the project. To avoid possible confusion, it is
always a good idea to avoid naming a project with one of the
names allowed for packages or any name that starts with gnat.
Package renaming
A package may be defined by a renaming declaration. The new package
renames a package declared in a different project file, and has the same
attributes as the package it renames. The name of the renamed package
must be the same as the name of the renaming package. The project must
contain a package declaration with this name, and the project
must appear in the context clause of the current project, or be its
base or
parent project. It is not possible to add or override attributes to the renaming
project. If you need to do so, you should use an extending declaration
(see below).
Packages that are renamed in other project files often come from project files
that have no sources: they are just used as templates. Any modification in the
template will be reflected automatically in all the project files that rename
a package from the template. This is a very common way to share settings
between projects.
Package extension
A package can also be defined by an extending declaration. This is
similar to a renaming declaration, except that it is possible to add or
override attributes.
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 run-time
computation by the Project Manager. In a project file, the computed value of
an expression is either a string or a list of strings.
A string value is one of:
A literal string, for instance "comm/my_proj.gpr"
The name of a variable that evaluates to a string (see Variables)
The name of an attribute that evaluates to a string (see Attributes)
An external reference (see External_Values)
A concatenation of the above, as in "prefix_"&Var.
A list of strings is one of the following:
A parenthesized comma-separated list of zero or more string expressions, for
instance (File_Name,"gnat.adc",File_Name&".orig") or ().
The name of a variable that evaluates to a list of strings
The name of an attribute that evaluates to a list of strings
A concatenation of a list of strings and a string (as defined above), for
instance ("A","B")&"C"
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:
List:=()&File_Name;-- One string in this listList2:=List&(File_Name&".orig");-- Two stringsBig_List:=List&Lists2;-- Three stringsIllegal:="gnat.adc"&List2;-- Illegal, must start with list
Built-in functions may be used in expression. The names of built-in functions
are not reserved words and may also be used as variable names.
In an expression, a built-in function is recognized if its name is immediately
followed by an open parenthesis (‘(‘).
An external value is an expression whose value is obtained from the command
that invoked the processing of the current project file (typically a
gprbuild command).
The first string_literal is the name of the external variable, whose
value (a string) may be specified by an environment variable with this name,
or on the command line via the -Xname=value option.
The command line takes precedence if the name is defined in both contexts,
thus allowing the user to locally override an environment variable.
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.
If the value of the external variable is not obtained from an
environment variable or the command line, and the invocation of
the external function does not supply a second parameter, then
an error is reported.
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.
This construct is typically used to initialize typed variables, which
are then used in case constructions to control the value assigned to
attributes in various scenarios. Thus such variables are often called
scenario variables.
An external value is an expression whose value is obtained from the command
that invoked the processing of the current project file (typically a
gprbuild command).
The first string_literal is the name of the external variable, with
the same interpretation as for the external function; it is
looked up first on the command line (as the name in a -Xname=value
option) and, if not so specified, then as an environment variable.
If it is not defined by either of these, then the function returns
an empty list.
The second string_literal is the separator between each component of the
string list.
An empty list is returned 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.
Note the following differences between external and external_as_list:
The external_as_list function has no default value for the external
variable
The external_as_list function returns an empty list, and does not
report an error, when the value of the external variable is undefined.
These differences reflect the different use cases for the two functions.
External variables evaluated by the external function are
often used for configuration control, and misspellings should be
detected as errors rather than silently returning the empty string. If the
user intended an empty string as the result when the external variable
was undefined, then this could easily be obtained:
external("SOME_VAR","")
In contrast, the external_as_list function more typically is used
for external variables that may or may not have definitions (for example,
lists of options or paths) and then the desired result in the undefined
case is an empty list, not a reported error.
Here is an example of the external_as_list function:
external_as_list("SWITCHES",",")
If the external value of SWITCHES is "-O2,-g",
the result is ("-O2","-g").
If the external value is ",-O2,-g,",
the result is also ("-O2","-g").
if the external value is "-gnatv",
the result is ("-gnatv").
If the external value is ",,", the result is ("").
If the external value is ",", the result is (), the empty string list.
Function Split takes two single string parameters and return a string list.
Example:
Split("-gnatf,-gnatv",",")=>("-gnatf","gnatv")
The first string argument is the string to be split. The second argument is
the separator. Each occurrence of the separator in the first argument is a place
where it is split. If the first argument is an empty string or contains only
occurrences of the separator, then the result is an empty string list.
If the argument does not contains any occurrence of the separator, then the
result is a list with only one string: the first argument. Empty strings are
not included in the result.
A type declaration introduces a discrete set of string literals.
If a string variable is declared to have this type, its value
is restricted to the given set of literals. These are the only named
types in project files. A type declaration may only appear at the project
level, not inside a package.
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:
typeOSis("GNU/Linux","Unix","Windows","VMS");
Variables of a string type are called typed variables; all other
variables are called untyped variables. Typed variables are
particularly useful in case constructions, to support conditional
attribute declarations. (See 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.
Variables store values (strings or list of strings) and can appear
as part of an expression. The declaration of a variable creates the
variable and assigns the value of the expression to it. The name of the
variable is available immediately after the assignment symbol, if you
need to reuse its old value to compute the new value. Before the completion
of its first declaration, the value of a variable defaults to the empty
string ("").
A typed variable can be used as part of a case expression to
compute the value, but it can only be declared once in the project file,
so that all case constructions see the same value for the variable. This
provides more consistency and makes the project easier to understand.
The syntax for its declaration is identical to the Ada syntax for an
object declaration. In effect, a typed variable acts as a constant.
An untyped variable can be declared and overridden multiple times
within the same project. It is declared implicitly through an Ada
assignment. The first declaration establishes the kind of the variable
(string or list of strings) and successive declarations must respect
the initial kind. Assignments are executed in the order in which they
appear, so the new value replaces the old one and any subsequent reference
to the variable uses the new value.
A variable may be declared at the project file level, or within a package.
This_OS:OS:=external("OS");-- a typed variable declarationThat_OS:="GNU/Linux";-- an untyped variable declarationName:="readme.txt";Save_Name:=Name&".saved";Empty_List:=();List_With_One_Element:=("-gnaty");List_With_Two_Elements:=List_With_One_Element&"-gnatg";Long_List:=("main.ada","pack1_.ada","pack1.ada","pack2_.ada");
A variable reference may take several forms:
The simple variable name, for a variable in the current package (if any)
or in the current project
An expanded name, whose prefix is a context name.
A context may be one of the following:
The name of an existing package in the current project
The name of an imported project of the current project
The name of a direct or indirect base project (i.e., a project extended by the current
project, either directly or indirectly)
An expanded name whose prefix is an imported/parent project name, and
whose selector is a package name in that project.
A case construction is used in a project file to effect conditional
behavior. Through this construction, you can set the value of attributes
and variables depending on the value previously assigned to a typed
variable.
All choices in a choice list must be distinct. Unlike Ada, the choice
lists of all alternatives do not need to include all values of the type.
An others choice must appear last in the list of alternatives.
The syntax of a case construction is based on the Ada case construction
(although the null declaration for empty alternatives is optional).
The case expression must be a string variable, either typed or not, whose value
is often given by an external reference (see External_Values).
Each alternative starts with the reserved word when, either a list of
literal strings separated by the "|" character or the reserved word
others, and the "=>" token.
When the case expression is a typed string variable, each literal string must
belong to the string type that is the type of the case variable.
After each =>, there are zero or more declarations. The only
declarations 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.
A project (and its packages) may have attributes that define
the project’s properties. Some attributes have values that are strings;
others have values that are string lists.
There are two categories of attributes: simple attributes
and indexed attributes.
Each simple attribute has a default value: the empty string (for string
attributes) and the empty list (for string list attributes).
An attribute declaration defines a new value for an attribute, and overrides
the previous value. The syntax of a simple attribute declaration is similar to
that of an attribute definition clause in Ada.
Some attributes are indexed. These attributes are mappings whose
domain is a set of strings. They are declared one association
at a time, by specifying a point in the domain and the corresponding image
of the attribute.
Like untyped variables and simple attributes, indexed attributes
may be declared several times. Each declaration supplies a new value for the
attribute, and replaces the previous setting.
Here are some examples of attribute declarations:
-- simple attributesforObject_Diruse"objects";forSource_Dirsuse("units","test/drivers");-- indexed attributesforBody("main")use"Main.ada";forSwitches("main.ada")use("-v","-gnatv");forSwitches("main.ada")useBuilder'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.forDefault_SwitchesuseDefault.Builder'Default_Switches;
When an attribute is defined in the configuration project but not in the user
project, it is inherited in the user project.
When a single string attribute is defined in both the configuration project
and the user project, its value in the user project is as declared; the value
in the configuration project does not matter.
For string list attributes, there are two cases. Some of these attributes are
configuration concatenable. For these attributes, when they are declared
in both the configuration project and the user project, the final value is
the concatenation of the value in the configuration project with the value
in the user project. The configuration concatenable attributes are indicated
in the list below.
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, with some exceptions.
Exec_Dir: default is 'Object_Dir, that is, the value of attribute
Object_Dir in the same project, declared or defaulted
Source_Dirs: default is (".")
The prefix of an attribute may be:
project for an attribute of the current project
The name of an existing package of the current project
The name of an imported project
The name of a parent project that is extended by the current project
An expanded name whose prefix is imported/base/parent project name,
and whose selector is a package name
In the following sections, all predefined attributes are succinctly described,
first the project level attributes (that is, those attributes that are not in a
package), then the attributes in the different packages.
It is possible for different tools to dynamically create new packages with
attributes, or new attributes in predefined packages. These attributes are
not documented here.
The attributes under Configuration headings are usually found only in
configuration project files.
The characteristics of each attribute are indicated as follows:
Type of value
The value of an attribute may be a single string, indicated by the word
“single”, or a string list, indicated by the word “list”.
Read-only
When the attribute is read-only – that is when a declaration for
the attribute is forbidden – this is indicated by the “read-only”.
Optional index
If an optional index is allowed in the value of the attribute (both single
and list), this is indicated by the words “optional index”.
Indexed attribute
An indexed attribute is indicated by the word “indexed”.
Case-sensitivity of the index
For an indexed attribute, if the index is case-insensitive, this is indicated
by the words “case-insensitive index”.
File name index
For an indexed attribute, when the index is a file name, this is indicated by
the words “file name index”. The index may or may not be case-sensitive,
depending on the platform.
others allowed in index
For an indexed attribute, if it is allowed to use others as the index,
this is indicated by the words “others allowed”.
When others is used as the index of an indexed attribute, the value of
the attribute indexed by others is used when no other index would apply.
configuration concatenable
For a string list attribute, the final value if the attribute is declared
in both the configuration project and the user project is the concatenation
of the two value, configuration then user.
The list of languages of the sources of the project.
Roots: list, indexed, file name index
The index is the file name of an executable source. Indicates the list of units
from the main project that need to be bound and linked with their closures
with the executable. The index is either a file name, a language name or “*”.
The roots for an executable source are those in Roots with an index that
is the executable source file name, if declared. Otherwise, they are those in
Roots with an index that is the language name of the executable source,
if present. Otherwise, they are those in Roots (“*”), if declared. If none
of these three possibilities are declared, then there are no roots for the
executable source.
Externally_Built: single
Indicates if the project is externally built.
Only case-insensitive values allowed are “true” and “false”, the default.
Warning_Message: single
Causes gprbuild to emit a user-defined warning message.
Directories
Object_Dir: single
Indicates the object directory for the project.
Exec_Dir: single
Indicates the exec directory for the project, that is the directory where the
executables are.
Create_Missing_Dirs: single
Indicates if the missing object, library and executable directories should
be created automatically by the project-aware tool. Taken into account
only in the main project. Only authorized case-insensitive values are
“true” and “false”.
Source_Dirs: list
The list of source directories of the project.
Inherit_Source_Path: list, indexed, case-insensitive index
Index is a language name. Value is a list of language names. Indicates that
in the source search path of the index language the source directories of
the languages in the list should be included.
Example:
forInherit_Source_Path("C++")use("C");
Exclude_Source_Dirs: list
The list of directories that are included in Source_Dirs but are not source
directories of the project.
Ignore_Source_Sub_Dirs: list
Value is a list of simple names or patterns for subdirectories that are
removed from the list of source directories, including their subdirectories.
Source Files
Source_Files: list
Value is a list of source file simple names.
Locally_Removed_Files: list
Obsolescent. Equivalent to Excluded_Source_Files.
Excluded_Source_Files: list
Value is a list of simple file names that are not sources of the project.
Allows to remove sources that are inherited or found in the source directories
and that match the naming scheme.
Source_List_File: single
Value is a text file name that contains a list of source file simple names,
one on each line.
Excluded_Source_List_File: single
Value is a text file name that contains a list of file simple names that
are not sources of the project.
Interfaces: list
Value is a list of file names that constitutes the interfaces of the project.
Aggregate Projects
Project_Files: list
Value is the list of aggregated projects.
Project_Path: list
Value is a list of directories that are added to the project search path when
looking for the aggregated projects.
External: single, indexed
Index is the name of an external reference. Value is the value of the
external reference to be used when parsing the aggregated projects.
Libraries
Library_Dir: single
Value is the name of the library directory. This attribute needs to be
declared for each library project.
Library_Name: single
Value is the name of the library. This attribute needs to be declared or
inherited for each library project.
Library_Kind: single
Specifies the kind of library: static library (archive) or shared library.
Case-insensitive values must be one of “static” for archives (the default),
“static-pic” for archives of Position Independent Code, or “dynamic” or
“relocatable” for shared libraries.
Library_Version: single
Value is the name of the library file.
Library_Interface: list
Value is the list of unit names that constitutes the interfaces
of a Stand-Alone Library project.
Library_Standalone: single
Specifies if a Stand-Alone Library (SAL) is encapsulated or not.
Only authorized case-insensitive values are “standard” for non encapsulated
SALs, “encapsulated” for encapsulated SALs or “no” for non SAL library project.
Index is a language name. Value is a list of options for an invocation of the
compiler of the language. This invocation is done for a shared library project
with sources of the language. The output of the invocation is the path name
of a shared library file. The directory name is to be put in the run path
option switch when linking the shared library for the project.
Library_Src_Dir: single
Value is the name of the directory where copies of the sources of the
interfaces of a Stand-Alone Library are to be copied.
Library_ALI_Dir: single
Value is the name of the directory where the ALI files of the interfaces
of a Stand-Alone Library are to be copied. When this attribute is not declared,
the directory is the library directory.
Library_gcc: single
Obsolescent attribute. Specify the linker driver used to link a shared library.
Use instead attribute Linker’Driver.
Library_Symbol_File: single
Value is the name of the library symbol file.
Library_Symbol_Policy: single
Indicates the symbol policy kind. Only authorized case-insensitive
values are “restricted”, “unrestricted”.
Library_Reference_Symbol_File: single
Value is the name of the reference symbol file.
Configuration - General
Default_Language: single
Value is the case-insensitive name of the language of a project when attribute
Languages is not specified.
Run_Path_Option: list
Value is the list of switches to be used when specifying the run path option
in an executable.
Run_Path_Origin: single
Value is the string that may replace the path name of the executable
directory in the run path options.
Separate_Run_Path_Options: single
Indicates if there may be several run path options specified when linking an
executable. Only authorized case-insensitive values are “true” or “false” (the
default).
Toolchain_Version: single, indexed, case-insensitive index
Index is a language name. Specify the version of a toolchain for a language.
Required_Toolchain_Version: single, indexed, case-insensitive index
Index is a language name. Specify the value expected for the Toolchain_Version
attribute for this language, typically provided by an auto-generated configuration
project. If Required_Toolchain_Version and Toolchain_Version do not match, the
project processing aborts with an error.
Toolchain_Description: single, indexed, case-insensitive index
Obsolescent. No longer used.
Object_Generated: single, indexed, case-insensitive index
Index is a language name. Indicates if invoking the compiler for a language
produces an object file. Only authorized case-insensitive values are “false”
and “true” (the default).
Objects_Linked: single, indexed, case-insensitive index
Index is a language name. Indicates if the object files created by the compiler
for a language need to be linked in the executable. Only authorized
case-insensitive values are “false” and “true” (the default).
Target: single
Value is the name of the target platform. Taken into account only in the main
project.
Note that when the target is specified on the command line (usually with
a switch –target=), the value of attribute reference ‘Target is the one
specified on the command line.
Runtime: single, indexed, case-insensitive index
Index is a language name. Indicates the runtime directory that is to be used
when using the compiler of the language. Taken into account only in the main
project, or its extended projects if any.
Note that when the runtime is specified for a language on the command line
(usually with a switch –RTS), the value of attribute reference ‘Runtime
for this language is the one specified on the command line.
Runtime_Dir: single, indexed, case-insensitive index
Index is a language name. Value is the path name of the runtime directory
for the language.
Runtime_Library_Dirs: list, indexed, case-insensitive index
Index is a language name. Value is the path names of the directories where
the runtime libraries are located. This attribute is not normally declared.
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. This attribute is obsolete.
Runtime_Source_Dirs: list, indexed, case-insensitive index
Index is a language name. Value is the path names of the directories where
the sources of runtime libraries are located. This attribute is not
normally declared.
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. This attribute is obsolete.
Runtime_Library_Version: single, indexed, case-insensitive index
Index is a language name. Value is library version for the language. This
attribute is not normally declared.
Toolchain_Name: single, indexed, case-insensitive index
Index is a language name. Indicates the toolchain name that is to be used
when using the compiler of the language. Taken into account only in the main
project, or its extended projects if any.
Configuration - Libraries
Library_Builder: single
Value is the path name of the application that is to be used to build
libraries. Usually the path name of “gprlib”.
Library_Support: single
Indicates the level of support of libraries. Only authorized case-insensitive
values are “static_only”, “full” or “none” (the default).
Configuration - Archives
Archive_Builder: list
Value is the name of the application to be used to create a static library
(archive), followed by the options to be used.
Archive_Builder_Append_Option: list
Value is the list of options to be used when invoking the archive builder
to add project files into an archive.
Archive_Indexer: list
Value is the name of the archive indexer, followed by the required options.
Archive_Suffix: single
Value is the extension of archives. When not declared, the extension is “.a”.
Library_Partial_Linker: list
Value is the name of the partial linker executable, followed by the required
options.
Configuration - Shared Libraries
Shared_Library_Prefix: single
Value is the prefix in the name of shared library files. When not declared,
the prefix is “lib”.
Shared_Library_Suffix: single
Value is the extension of the name of shared library files. When not
declared, the extension is “.so”.
Symbolic_Link_Supported: single
Indicates if symbolic links are supported on the platform. Only authorized
case-insensitive values are “true” and “false” (the default).
Library_Major_Minor_Id_Supported: single
Indicates if major and minor ids for shared library names are supported on
the platform. Only authorized case-insensitive values are “true” and “false”
(the default).
Library_Auto_Init_Supported: single
Indicates if auto-initialization of Stand-Alone Libraries is supported. Only
authorized case-insensitive values are “true” and “false” (the default).
Index is either a language name or a source file name. Value is the list of
switches to be used when binding code. Index is either the source file name
of the executable to be bound or the language name of the code to be bound.
Configuration - Binding
Driver: single, indexed, case-insensitive index
Index is a language name. Value is the name of the application to be used when
binding code of the language.
Index is a language name. Value is the list of the required switches to be
used when binding code of the language.
Prefix: single, indexed, case-insensitive index
Index is a language name. Value is a prefix to be used for the binder exchange
file name for the language. Used to have different binder exchange file names
when binding different languages.
Objects_Path: single,indexed, case-insensitive index
Index is a language name. Value is the name of the environment variable that
contains the path for the object directories.
Object_Path_File: single,indexed, case-insensitive index
Index is a language name. Value is the name of the environment variable. The
value of the environment variable is the path name of a text file that
contains the list of object directories.
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.
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.
Index is a language name. Value is the list of compilation switches to be
used when building an executable. Index is either the source file name of
the executable to be built or its language name.
Executable: single, indexed, case-insensitive index
Index is an executable source file name. Value is the simple file name of the
executable to be built.
Executable_Suffix: single
Value is the extension of the file names of executable. When not specified,
the extension is the default extension of executables on the platform.
Global_Configuration_Pragmas: single
Value is the file name of a configuration pragmas file that is specified to
the Ada compiler when compiling any Ada source in the project tree.
Global_Config_File: single, indexed, case-insensitive index
Index is a language name. Value is the file name of a configuration file that
is specified to the compiler when compiling any source of the language in the
project tree.
Index is a language name. Value is a list of switches to be used when invoking
gnatcheck for a source of the language, if there is no applicable
attribute Switches.
Taken into account only in the main project.
Value is a list of switches to be used by the cleaning application.
Source_Artifact_Extensions: list, indexed, case-insensitive index
Index is a language names. Value is the list of extensions for file names
derived from object file names that need to be cleaned in the object
directory of the project.
Object_Artifact_Extensions: list, indexed, case-insensitive index
Index is a language names. Value is the list of extensions for file names
derived from source file names that need to be cleaned in the object
directory of the project.
Artifacts_In_Object_Dir: single
Value is a list of file names expressed as regular expressions that are to be
deleted by gprclean in the object directory of the project.
Artifacts_In_Exec_Dir: single
Value is list of file names expressed as regular expressions that are to be
deleted by gprclean in the exec directory of the main project.
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.
Index is a source file name or a language name. Value is the list of switches
to be used when invoking the compiler for the source or for its language.
Local_Configuration_Pragmas: single
Value is the file name of a configuration pragmas file that is specified to
the Ada compiler when compiling any Ada source in the project.
Local_Config_File: single, indexed, case-insensitive index
Index is a language name. Value is the file name of a configuration file that
is specified to the compiler when compiling any source of the language in the
project.
Configuration - Compiling
Driver: single, indexed, case-insensitive index
Index is a language name. Value is the name of the executable for the compiler
of the language.
Language_Kind: single, indexed, case-insensitive index
Index is a language name. Indicates the kind of the language, either file based
or unit based. Only authorized case-insensitive values are “unit_based” and
“file_based” (the default).
Dependency_Kind: single, indexed, case-insensitive index
Index is a language name. Indicates how the dependencies are handled for the
language. Only authorized case-insensitive values are “makefile”, “ali_file”,
“ali_closure” or “none” (the default).
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.
Index is a language name. Value is the list of the minimum switches to be used
at the end of the command line when invoking the compiler for the language.
PIC_Option: list, indexed, case-insensitive index
Index is a language name. Value is the list of switches to be used when
compiling a source of the language when the project is a shared library
project.
Source_File_Switches: single, indexed, case-insensitive index
configuration concatenable
Index is a language name. Value is a list of switches to be used just before
the path name of the source to compile when invoking the compiler for a source
of the language.
Object_File_Suffix: single, indexed, case-insensitive index
Index is a language name. Value is the extension of the object files created
by the compiler of the language. When not specified, the extension is the
default one for the platform.
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”.
Index is a language name. Value is the list of switches to be used to compile
a unit in a multi unit source of the language. The index of the unit in the
source is concatenated with the last switches in the list.
Multi_Unit_Object_Separator: single, indexed, case-insensitive index
Index is a language name. Value is the string to be used in the object file
name before the index of the unit, when compiling a unit in a multi unit source
of the language.
Index is a language name. Value is the list of switches to be used to specify
a mapping file when invoking the compiler for a source of the language.
Mapping_Spec_Suffix: single, indexed, case-insensitive index
Index is a language name. Value is the suffix to be used in a mapping file
to indicate that the source is a spec.
Mapping_Body_Suffix: single, indexed, case-insensitive index
Index is a language name. Value is the suffix to be used in a mapping file
to indicate that the source is a body.
Configuration - Config Files
Config_File_Switches: list: single, indexed, case-insensitive index,
configuration concatenable
Index is a language name. Value is the list of switches to specify to the
compiler of the language a configuration file.
Config_Body_File_Name: single, indexed, case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration specific to a body of the language in a configuration
file.
Config_Body_File_Name_Index: single, indexed, case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration specific to the body a unit in a multi unit source of the
language in a configuration file.
Config_Body_File_Name_Pattern: single, indexed,
case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration for all bodies of the languages in a configuration file.
Config_Spec_File_Name: single, indexed, case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration specific to a spec of the language in a configuration
file.
Config_Spec_File_Name_Index: single, indexed, case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration specific to the spec a unit in a multi unit source of the
language in a configuration file.
Config_Spec_File_Name_Pattern: single, indexed,
case-insensitive index
Index is a language name. Value is the template to be used to indicate a
configuration for all specs of the languages in a configuration file.
Config_File_Unique: single, indexed, case-insensitive index
Index is a language name. Indicates if there should be only one configuration
file specified to the compiler of the language. Only authorized
case-insensitive values are “true” and “false” (the default).
Index is a language name. Value is the list of switches to be used to specify
to the compiler the dependency file when the dependency kind of the language is
file based, and when Dependency_Driver is not specified for the language.
Dependency_Driver: list, indexed, case-insensitive index
Index is a language name. Value is the name of the executable to be used to
create the dependency file for a source of the language, followed by the
required switches.
Index is a language name. Value is the list of switches to specify to the
compiler of the language to indicate a directory to look for sources.
Include_Path: single, indexed, case-insensitive index
Index is a language name. Value is the name of an environment variable that
contains the path of all the directories that the compiler of the language
may search for sources.
Include_Path_File: single, indexed, case-insensitive index
Index is a language name. Value is the name of an environment variable the
value of which is the path name of a text file that contains the directories
that the compiler of the language may search for sources.
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.
Configuration - Response Files
Max_Command_Line_Length: single
Value is the maximum number of character in the command line when invoking
a compiler that supports response files.
Response_File_Format: single, indexed, case-insensitive index
Indicates the kind of response file to create when the length of the compiling
command line is too large. The index is the name of the language for the compiler.
Only authorized case-insensitive values are “none”,
“gnu”, “object_list”, “gcc_gnu”, “gcc_option_list” and “gcc_object_list”.
Index is a language name. Value is a list of switches to be used when invoking
gnatxref for a source of the language, if there is no applicable
attribute Switches.
Index is a language name. Value is a list of switches to be used when invoking
gnatfind for a source of the language, if there is no applicable
attribute Switches.
Index is a language name. Value is a list of switches to be used when invoking
gnatstub for a source of the language, if there is no applicable
attribute Switches.
An indexed attribute to declare a set of files not part of the sources
to be installed. The array index is the directory where the
file is to be installed. If a relative directory then Prefix (see
below) is prepended. Note also that if the same file name occurs
multiple time in the attribute list, the last one will be the one
installed. If an artifact is not found a warning is displayed.
Required_Artifacts: list, indexed
As above, but artifacts must be present or an error is reported.
Prefix: single
Value is the install destination directory. If the value is a
relative path, it is taken as relative to the global prefix
directory. That is, either the value passed to –prefix option or
the default installation prefix.
Sources_Subdir: single
Value is the sources directory or subdirectory of Prefix.
Exec_Subdir: single
Value is the executables directory or subdirectory of Prefix.
ALI_Subdir: single
Value is ALI directory or subdirectory of Prefix.
Lib_Subdir: single
Value is library directory or subdirectory of Prefix.
Project_Subdir: single
Value is the project directory or subdirectory of Prefix.
Active: single
Indicates that the project is to be installed or not. Case-insensitive value
“false” means that the project is not to be installed, all other values mean
that the project is to be installed.
Mode: single
Value is the installation mode, it is either dev (default) or usage.
Install_Name: single
Specify the name to use for recording the installation. The default is
the project name without the extension.
Side_Debug: single
Indicates that the project’s executable and shared libraries are to
be stripped of the debug symbols. Those debug symbols are written
into a side file named after the original file with the “.debug”
extension added. Case-insensitive value “false” (default) disables
this feature. Set it to “true” to activate.
Install_Project: single
Indicates that a project is to be generated and installed. The
value is either “true” to “false”. Default is “true”.
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.
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.
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.
Index is a source file name or a language name. Value is the list of switches
to be used at the end of the command line when invoking the linker to
build an executable for the source or for its language. These switches may
override the Required_Switches.
Linker_Options: list, configuration concatenable
This attribute specifies a list of additional switches to be given to the
linker when linking an executable. It is ignored when defined in the main
project and taken into account in all other projects that are imported
directly or indirectly. These switches complement the Linker'Switches
defined in the main project. This is useful when a particular subsystem
depends on an external library: adding this dependency as a
Linker_Options in the project of the subsystem is more convenient than
adding it to all the Linker'Switches of the main projects that depend
upon this subsystem.
Map_File_Option: single
Value is the switch to specify the map file name that the linker needs to
create.
Unconditionally_Linked: single, indexed, case-insensitive index
Index is a language name. Indicates that all object files of this language
going to be linked unconditionally. Only case-insensitive values allowed
are “true” and “false”, the default.
Configuration - Linking
Driver: single
Value is the name of the linker executable.
Configuration - Response Files
Max_Command_Line_Length: single
Value is the maximum number of character in the command line when invoking
the linker to link an executable.
Response_File_Format: single
Indicates the kind of response file to create when the length of the linking
command line is too large. Only authorized case-insensitive values are “none”,
“gnu”, “object_list”, “gcc_gnu”, “gcc_option_list” and “gcc_object_list”.
Index is a language name. Value is a list of switches to be used when invoking
gnatmetric for a source of the language, if there is no applicable
attribute Switches.
Specification_Suffix: single, indexed, case-insensitive index
Equivalent to attribute Spec_Suffix.
Spec_Suffix: single, indexed, case-insensitive index
Index is a language name. Value is the extension of file names for specs of
the language.
Implementation_Suffix: single, indexed, case-insensitive index
Equivalent to attribute Body_Suffix.
Body_Suffix: single, indexed, case-insensitive index
Index is a language name. Value is the extension of file names for bodies of
the language.
Separate_Suffix: single
Value is the extension of file names for subunits of Ada.
Casing: single
Indicates the casing of sources of the Ada language. Only authorized
case-insensitive values are “lowercase”, “uppercase” and “mixedcase”.
Dot_Replacement: single
Value is the string that replace the dot of unit names in the source file names
of the Ada language.
Specification: single, optional index, indexed,
case-insensitive index
Equivalent to attribute Spec.
Spec: single, optional index, indexed, case-insensitive index
Index is a unit name. Value is the file name of the spec of the unit.
Implementation: single, optional index, indexed,
case-insensitive index
Equivalent to attribute Body.
Body: single, optional index, indexed, case-insensitive index
Index is a unit name. Value is the file name of the body of the unit.
Specification_Exceptions: list, indexed, case-insensitive index
Index is a language name. Value is a list of specs for the language that do not
necessarily follow the naming scheme for the language and that may or may not
be found in the source directories of the project.
Implementation_Exceptions: list, indexed, case-insensitive index
Index is a language name. Value is a list of bodies for the language that do not
necessarily follow the naming scheme for the language and that may or may not
be found in the source directories of the project.
Index is a language name. Value is a list of switches to be used when invoking
gnatpp for a source of the language, if there is no applicable
attribute Switches.
If this attribute is defined it sets the patterns to
synchronized from the master to the slaves. It is exclusive
with Excluded_Patterns, that is it is an error to define
both.
Included_Artifact_Patterns: list
If this attribute is defined it sets the patterns of compilation
artifacts to synchronized from the slaves to the build master.
This attribute replace the default hard-coded patterns.
Excluded_Patterns: list
Set of patterns to ignore when synchronizing sources from the build
master to the slaves. A set of predefined patterns are supported
(e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to
add some more patterns.
Root_Dir: single
Value is the root directory used by the slave machines.
Default_Switches: list, indexed, case-insensitive index
Index is a language name. Value is a list of switches to be used when invoking
gnatsync for a source of the language, if there is no applicable
attribute Switches.
A project that in effect combines several projects in order to efficiently support
concurrent builds or builds of all main programs from the constituent projects,
or the convenient definition of a common environment for the constituent projects.
See Aggregate Projects.
A project that is defined by a name Parent_proj.Child_proj
where Child_proj either imports or extends Parent_Proj.
This feature is typically used to show a close relationship between
the two projects, for example where the child project serves as a testbed
for the parent. See Child Projects.
The reuse and possible adaption by one project of the source files from
another project (the base project). Somewhat analogous to (single) class inheritance in
object-oriented programming. See Project Extension.
A variable that is defined on the command line (by the -X switch), as the
value of an environment variable, or, by default, as the second parameter to the
external function. See Scenarios in Projects.
A set of named properties and their values, associated with the GNAT tools that
are used during the development of software in Ada and other languages.
Properties include directories for source files, object files, and executables;
the switch settings for the various tools; and the naming scheme for source
files.
The project import closure for a given project proj is the set
of projects consisting of proj itself, together with each
project that is directly or indirectly imported by proj.
The import may be from either a with or a limitedwith.
See Project Import Closure.
The values of a project’s variables and attributes, as determined by
the settings of external variables referenced by a project. A scenario
typically defines a particular mode of usage for the project.
See Scenarios in Projects.
A project variable that can take any of a specified set of values, analogous
to a variable of an Ada enumeration type but where the values are string literals.
See Scenarios in Projects.