| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
11.1 Introduction 11.2 Building With Projects 11.3 Organizing Projects into Subsystems 11.4 Scenarios in Projects 11.5 Library Projects 11.6 Project Extension 11.7 Project File Reference
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
Project files are written in a syntax close to that of Ada, using familiar notions such as packages, context clauses, declarations, default values, assignments, and inheritance (see section 11.7 Project File Reference).
Project files can be built hierarchically from other project files, simplifying complex system integration and project reuse (see section 11.3 Organizing Projects into Subsystems).
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' and `-Xvbl=value'). See section 12.1.1 Switches Related to Project Files.
The Project Manager supports a wide range of development strategies, for systems of all sizes. Here are some typical practices that are easily handled:
all OS dependencies in a small number of implementation units.
Project files can be used to achieve some of the effects of a source versioning system (for example, defining separate projects for the different sets of sources that comprise different releases) but the Project Manager is independent of any source configuration management tool that might be used by the developers.
The various sections below introduce the different concepts related to projects. Each section starts with examples and use cases, and then goes into the details of related project file capabilities.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In its simplest form, a unique project is used to build a single executable. This section concentrates on such a simple setup. Later sections will extend this basic model to more complex setups.
The following concepts are the foundation of project files, and will be further detailed later in this documentation. They are summarized here as a reference.
Builder, Compiler, Binder,
and Linker. See section 11.7.4 Packages.
foo.c is typically the name of a C source file;
bar.ads or bar.1.ada are two common naming conventions for a
file containing an Ada spec. A compilation unit is often composed of a main
source file and potentially several auxiliary ones, such as header files in C.
The naming conventions can be user defined See section 11.2.8 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.
The following subsections introduce gradually all the attributes of interest for simple build needs. Here is the simple setup that will be used in the following examples.
The Ada source files `pack.ads', `pack.adb', and `proc.adb' are in
the `common/' directory. The file `proc.adb' contains an Ada main
subprogram Proc that withs package Pack. We want to compile
these source files with the switch `-O2', and put the resulting files in
the directory `obj/'.
common/ pack.ads pack.adb proc.adb common/release/ proc.ali, proc.o pack.ali, pack.o |
Our project is to be called Build. The name of the file is the name of the project (case-insensitive) with the `.gpr' extension, therefore the project file name is `build.gpr'. This is not mandatory, but a warning is issued when this convention is not followed.
This is a very simple example, and as stated above, a single project file is enough for it. We will thus create a new file, that for now should contain the following code:
project Build is end Build; |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When you create a new project, the first thing to describe is how to find the corresponding source files. This is the only settings that are needed by all the tools that will use this project (builder, compiler, binder and linker for the compilation, IDEs to edit the source files,...).
First step is to declare the source directories, which are the directories to be searched to find source files. In the case of the example, the `common' directory is the only source directory.
There are several ways of defining source directories:
The syntax for directories is platform specific. For portability, however, the project manager will always properly translate UNIX-like path names to the native format of specific platform. For instance, when the same project file is to be used both on Unix and Windows, "/" should be used as the directory separator rather than "\".
When using that construct, it can sometimes be convenient to also use the attribute Excluded_Source_Dirs, which is also a list of paths. Each entry specifies a directory whose immediate content, not including subdirs, is to be excluded. It is also possible to exclude a complete directory subtree using the "/**" notation.
When applied to the simple example, and because we generally prefer to have the project file at the toplevel directory rather than mixed with the sources, we will create the following file
build.gpr
project Build is
for Source_Dirs use ("common"); -- <<<<
end Build;
|
Once source directories have been specified, one may need to indicate source files of interest. By default, all source files present in the source directories are considered by the project manager. When this is not desired, it is possible to specify the list of sources to consider explicitly. In such a case, only source file base names are indicated and not their absolute or relative path names. The project manager is in charge of locating the specified source files in the specified source directories.
Since the project manager was initially developed for Ada environments, the default language is usually Ada and the above project file is complete: it defines without ambiguity the sources composing the project: that is to say, all the sources in subdirectory "common" for the default language (Ada) using the default naming convention.
However, when compiling a multi-language application, or a pure C
application, the project manager must be told which languages are of
interest, which is done by setting the Languages attribute to a list of
strings, each of which is the name of a language. Tools like
gnatmake only know about Ada, while other tools like
gprbuild know about many more languages such as C, C++, Fortran,
assembly and others can be added dynamically.
Even when using only Ada, the default naming might not be suitable. Indeed, how does the project manager recognizes an "Ada file" from any other file? Project files can describe the naming scheme used for source files, and override the default (see section 11.2.8 Naming Schemes). The default is the standard GNAT extension (`.adb' for bodies and `.ads' for specs), which is what is used in our example, explaining why no naming scheme is explicitly specified. See section 11.2.8 Naming Schemes.
Source Files
@cindex Source_Files
In some cases, source directories might contain files that should not be
included in a project. One can specify the explicit list of file names to
be considered through the Source_Files attribute.
When this attribute is defined, instead of looking at every file in the
source directories, the project manager takes only those names into
consideration reports errors if they cannot be found in the source
directories or does not correspond to the naming scheme.
(). Alternatively,
Source_Dirs can be set to the empty list, with the same
result.
Source_List_File
If there is a great number of files, it might be more convenient to use
the attribute Source_List_File, which specifies the full path of a file.
This file must contain a list of source file names (one per line, no
directory information) that are searched as if they had been defined
through Source_Files. Such a file can easily be created through
external tools.
A warning is issued if both attributes Source_Files and
Source_List_File are given explicit values. In this case, the
attribute Source_Files prevails.
Excluded_Source_Files
Specifying an explicit list of files is not always convenient.It might be
more convenient to use the default search rules with specific exceptions.
This can be done thanks to the attribute Excluded_Source_Files
(or its synonym Locally_Removed_Files).
Its value is the list of file names that should not be taken into account.
This attribute is often used when extending a project, See section 11.6 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 it is considered an error for a project file to have no sources attached to it unless explicitly declared as mentionend above.
If the order of the source directories is known statically, that is if
"/**" is not used in the string list Source_Dirs, then there may
be several files with the same source file name sitting in different
directories of the project. In this case, only the file in the first directory
is considered as a source of the project and the others are hidden. If
"/**" is not used in the string list Source_Dirs, it is an error
to have several files with the same source file name in the same directory
"/**" subtree, since there would be an ambiguity as to which one should
be used. However, two files with the same source file name may in two single
directories or directory subtrees. In this case, the one in the first directory
or directory subtree is a source of the project.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The next step when writing a project is to indicate where the compiler should put the object files. In fact, the compiler and other tools might create several different kind of files (for GNAT, there is the object file and the ALI file for instance). One of the important concepts in projects is that most tools may consider source directories as read-only and do not attempt to create new or temporary files there. Instead, all files are created in the object directory. It is of course not true for project-aware IDEs, whose purpose it is to create the source files.
The object directory is specified through the Object_Dir attribute.
Its value is the path to the object directory, either absolute or
relative to the directory containing the project file. This
directory must already exist and be readable and writable, although
some tools have a switch to create the directory if needed (See
the switch -p for gnatmake and gprbuild).
If the attribute Object_Dir is not specified, it defaults to
the project directory, that is the directory containing the project file.
For our example, we can specify the object dir in this way:
project Build is
for Source_Dirs use ("common");
for Object_Dir use "obj"; -- <<<<
end Build;
|
As mentioned earlier, there is a single object directory per project. As a result, if you have an existing system where the object files are spread in several directories, you can either move all of them into the same directory if you want to build it with a single project file, or study the section on subsystems (see section 11.3 Organizing Projects into Subsystems) to see how each separate object directory can be associated with one of the subsystem constituting the application.
When the linker is called, it usually creates an executable. By
default, this executable is placed in the object directory of the project. It
might be convenient to store it in its own directory.
This can be done through the Exec_Dir attribute, which, like
Object_Dir contains a single absolute or relative path and must point to
an existing and writable directory, unless you ask the tool to create it on
your behalf. When not specified, It defaults to the object directory and
therefore to the project file's directory if neither Object_Dir nor
Exec_Dir was specified.
In the case of the example, let's place the executable in the root of the hierarchy, ie the same directory as `build.gpr'. Hence the project file is now
project Build is
for Source_Dirs use ("common");
for Object_Dir use "obj";
for Exec_Dir use "."; -- <<<<
end Build;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In the previous section, executables were mentioned. The project manager needs
to be taught what they are. In a project file, an executable is indicated by
pointing to source file of the main subprogram. In C this is the file that
contains the main function, and in Ada the file that contains the main
unit.
There can be any number of such main files within a given project, and thus
several executables can be built in the context of a single project file. Of
course, one given executable might not (and in fact will not) need all the
source files referenced by the project. As opposed to other build environments
such as makefile, one does not need to specify the list of
dependencies of each executable, the project-aware builders knows enough of the
semantics of the languages to build ands link only the necessary elements.
The list of main files is specified via the Main attribute. It contains
a list of file names (no directories). If a project defines this
attribute, it is not necessary to identify main files on the
command line when invoking a builder, and editors like
GPS will be able to create extra menus to spawn or debug the
corresponding executables.
project Build is
for Source_Dirs use ("common");
for Object_Dir use "obj";
for Exec_Dir use ".";
for Main use ("proc.adb"); -- <<<<
end Build;
|
If this attribute is defined in the project, then spawning the builder with a command such as
gnatmake -Pbuild |
automatically builds all the executables corresponding to the files listed in the Main attribute. It is possible to specify one or more executables on the command line to build a subset of them.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We now have a project file that fully describes our environment, and can be
used to build the application with a simple gnatmake command as seen
in the previous section. In fact, the empty project we showed immediately at
the beginning (with no attribute at all) could already fullfill that need if it
was put in the `common' directory.
Of course, we always want more control. This section will show you how to specify the compilation switches that the various tools involved in the building of the executable should use.
Since source names and locations are described into the project file, it is not necessary to use switches on the command line for this purpose (switches such as -I for gcc). This removes a major source of command line length overflow. Clearly, the builders will have to communicate this information one way or another to the underlying compilers and tools they call but they usually use response files for this and thus should not be subject to command line overflows.
Several tools are participating to the creation of an executable: the compiler produces object files from the source files; the binder (in the Ada case) creates an source file that takes care, among other things, of elaboration issues and global variables initialization; and the linker gathers everything into a single executable that users can execute. All these tools are known by the project manager and will be called with user defined switches from the project files. However, we need to introduce a new project file concept to express which switches to be used for any of the tools involved in the build.
A project file is subdivided into zero or more packages, each of which contains the attributes specific to one tool (or one set of tools). Project files use an Ada-like syntax for packages. Package names permitted in project files are restricted to a predefined set (see section 11.7.4 Packages), and the contents of packages are limited to a small set of constructs and attributes (see section 11.7.9 Attributes).
Our example project file can be extended with the following empty packages. At this stage, they could all be omitted since they are empty, but they show which packages would be involved in the build process.
project Build is
for Source_Dirs use ("common");
for Object_Dir use "obj";
for Exec_Dir use ".";
for Main use ("proc.adb");
end Build;
package Builder is --<<< for gnatmake and gprbuild
end Builder;
package Compiler is --<<< for the compiler
end Builder;
package Binder is --<<< for the binder
end Builder;
package Linker is --<<< for the linker
end Builder;
|
Let's first examine the compiler switches. As stated in the initial description of the example, we want to compile all files with `-O2'. This is a compiler switch, although it is usual, on the command line, to pass it to the builder which then passes it to the compiler. It is recommended to use directly the right package, which will make the setup easier to understand for other people.
Several attributes can be used to specify the switches:
In this example, we want to compile all Ada source files with the
`-O2' switch, and the resulting project file is as follows
(only the Compiler package is shown):
package Compiler is
for Default_Switches ("Ada") use ("-O2");
end Compiler;
|
package Compiler is
for Default_Switches ("Ada") use ("-O2");
for Switches ("proc.adb") use ("-O0");
end Compiler;
|
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.
pragma Restrictions (No_Tasking). These pragmas will be
used for all the sources of the project.
The switches for the other tools are defined in a similar manner through the
Default_Switches and Switches attributes, respectively in the
Builder package (for gnatmake and gprbuild),
the Binder package (binding Ada executables) and the Linker
package (for linking executables).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Now that our project files are written, let's build our executable. Here is the command we would use from the command line:
gnatmake -Pbuild |
This will automatically build the executables specified through the Main attribute: for each, it will compile or recompile the sources for which the object file does not exist or is not up-to-date; it will then run the binder; and finally run the linker to create the executable itself.
gnatmake only knows how to handle Ada files. By using
gprbuild as a builder, you could automatically manage C files the
same way: create the file `utils.c' in the `common' directory,
set the attribute Languages to "(Ada, C)", and run
gprbuild -Pbuild |
Gprbuild knows how to recompile the C files and will
recompile them only if one of their dependencies has changed. No direct
indication on how to build the various elements is given in the
project file, which describes the project properties rather than a
set of actions to be executed. Here is the invocation of
gprbuild when building a multi-language program:
$ gprbuild -Pbuild gcc -c proc.adb gcc -c pack.adb gcc -c utils.c gprbind proc ... gcc proc.o -o proc |
Notice the three steps described earlier:
The default output of GPRbuild's execution is kept reasonably simple and easy
to understand. In particular, some of the less frequently used commands are not
shown, and some parameters are abbreviated. So it is not possible to rerun the
effect ofthe gprbuild command by cut-and-pasting its output. GPRbuild's option
-v provides a much more verbose output which includes, among other
information, more complete compilation, post-compilation and link commands.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, the executable name corresponding to a main file is computed from the main source file name. Through the attribute Builder.Executable, it is possible to change this default.
For instance, instead of building proc (or proc.exe
on Windows), we could configure our project file to build "proc1"
(resp proc1.exe) with the following addition:
project Build is
... -- same as before
package Builder is
for Executable ("proc.adb") use "proc1";
end Builder
end Build;
|
Attribute Executable_Suffix, when specified, may change the suffix
of the executable files, when no attribute Executable applies:
its value replace the platform-specific executable suffix.
The default executable suffix is empty on UNIX and ".exe" on Windows.
It is also possible to change the name of the produced executable by using the
command line switch `-o'. When several mains are defined in the project,
it is not possible to use the `-o' switch and the only way to change the
names of the executable is provided by Attributes Executable and
Executable_Suffix.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To illustrate some other project capabilities, here is a slightly more complex project using similar sources and a main program in C:
project C_Main is
for Languages use ("Ada", "C");
for Source_Dirs use ("common");
for Object_Dir use "obj";
for Main use ("main.c");
package Compiler is
C_Switches := ("-pedantic");
for Default_Switches ("C") use C_Switches;
for Default_Switches ("Ada") use ("-gnaty");
for Switches ("main.c") use C_Switches & ("-g");
end Compiler;
end C_Main;
|
This project has many similarities with the previous one.
As expected, its Main attribute now refers to a C source.
The attribute Exec_Dir is now omitted, thus the resulting
executable will be put in the directory `obj'.
The most noticeable difference is the use of a variable in the Compiler package to store settings used in several attributes. This avoids text duplication, and eases maintenance (a single place to modify if we want to add new switches for C files). We will revisit the use of variables in the context of scenarios (see section 11.4 Scenarios in Projects).
In this example, we see how the file `main.c' can be compiled with
the switches used for all the other C files, plus `-g'.
In this specific situation the use of a variable could have been
replaced by a reference to the Default_Switches attribute:
for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
|
Note the tick (') used to refer to attributes defined in a package.
Here is the output of the GPRbuild command using this project:
$gprbuild -Pc_main gcc -c -pedantic -g main.c gcc -c -gnaty proc.adb gcc -c -gnaty pack.adb gcc -c -pedantic utils.c gprbind main.bexch ... gcc main.o -o main |
The default switches for Ada sources, the default switches for C sources (in the compilation of `lib.c'), and the specific switches for `main.c' have all been taken into account.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes an Ada software system is ported from one compilation environment to another (say GNAT), and the file are not named using the default GNAT conventions. Instead of changing all the file names, which for a variety of reasons might not be possible, you can define the relevant file naming scheme in the Naming package of your project file.
The naming scheme has two distinct goals for the project manager: it allows finding of source files when searching in the source directories, and given a source file name it makes it possible to guess the associated language, and thus the compiler to use.
Note that the use by the Ada compiler of pragmas Source_File_Name is not supported when using project files. You must use the features described in this paragraph. You can however specify other configuration pragmas (see section 12.1.3 Specifying Configuration Pragmas).
The following attributes can be defined in package Naming:
"lowercase" (the default if
unspecified), "uppercase" or "mixedcase". It describes the
casing of file names with regards to the Ada unit name. Given an Ada unit
My_Unit, the file name will respectively be `my_unit.adb' (lowercase),
`MY_UNIT.ADB' (uppercase) or `My_Unit.adb' (mixedcase).
On Windows, file names are case insensitive, so this attribute is
irrelevant.
"-" 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:
'.' except if the entire string
is "."
Spec_Suffix ("Ada") is not specified, then the default is
".ads".
The value must satisfy the following requirements:
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, a file called `Makefile' will be part
of the project. This capability is usually not interesting when building.
However, it might become useful when a project is also used to
find the list of source files in an editor, like the GNAT Programming System
(GPS).
Body_Suffix ("Ada"). The same rules apply as for the
Body_Suffix attribute. The only accepted index is "Ada".
Spec can be used to define the source file name for a
given Ada compilation unit's spec. The index is the literal name of the Ada
unit (case insensitive). The value is the literal base name of the file that
contains this unit's spec (case sensitive or insensitive depending on the
operating system). This attribute allows the definition of exceptions to the
general naming scheme, in case some files do not follow the usual
convention.
When a source file contains several units, the relative position of the unit can be indicated. The first unit in the file is at position 1
for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
for Spec ("top") use "foo.a" at 1;
for Spec ("foo") use "foo.a" at 2;
|
For example, the following package models the Apex file naming rules:
package Naming is
for Casing use "lowercase";
for Dot_Replacement use ".";
for Spec_Suffix ("Ada") use ".1.ada";
for Body_Suffix ("Ada") use ".2.ada";
end Naming;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A subsystem is a coherent part of the complete system to be built. It is represented by a set of sources and one single object directory. A system can be composed of a single subsystem when it is simple as we have seen in the first section. Complex systems are usually composed of several interdependent subsystems. A subsystem is dependent on another subsystem if knowledge of the other one is required to build it, and in particular if visibility on some of the sources of this other subsystem is required. Each subsystem is usually represented by its own project file.
In this section, the previous example is being extended. Let's assume some
sources of our Build project depend on other sources.
For instance, when building a graphical interface, it is usual to depend upon
a graphical library toolkit such as GtkAda. Furthermore, we also need
sources from a logging module we had previously written.
11.3.1 Project Dependencies 11.3.2 Cyclic Project Dependencies 11.3.3 Sharing Between Projects 11.3.4 Global Attributes
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GtkAda comes with its own project file (appropriately called `gtkada.gpr'), and we will assume we have already built a project called `logging.gpr' for the logging module. With the information provided so far in `build.gpr', building the application would fail with an error indicating that the gtkada and logging units that are relied upon by the sources of this project cannot be found.
This is easily solved by adding the following with clauses at the beginning of our project:
with "gtkada.gpr";
with "a/b/logging.gpr";
project Build is
... -- as before
end Build;
|
When such a project is compiled, gnatmake will automatically
check the other projects and recompile their sources when needed. It will also
recompile the sources from Build when needed, and finally create the
executable. In some cases, the implementation units needed to recompile a
project are not available, or come from some third-party and you do not want to
recompile it yourself. In this case, the attribute Externally_Built to
"true" can be set, indicating to the builder that this project can be assumed
to be up-to-date, and should not be considered for recompilation. In Ada, if
the sources of this externally built project were compiled with another version
of the compiler or with incompatible options, the binder will issue an error.
The project's with clause has several effects. It provides source
visibility between projects during the compilation process. It also guarantees
that the necessary object files from Logging and GtkAda are
available when linking Build.
As can be seen in this example, the syntax for importing projects is similar
to the syntax for importing compilation units in Ada. However, project files
use literal strings instead of names, and the with clause identifies
project files rather than packages.
Each literal string after with is the path
(absolute or relative) to a project file. The .gpr extension is
optional, although we recommend adding it. If no extension is specified,
and no project file with the `.gpr' extension is found, then
the file is searched for exactly as written in the with clause,
that is with no extension.
When a relative path or a base name is used, the project files are searched relative to each of the directories in the project path. This path includes all the directories found with the following algorithm, in that order, as soon as a matching file is found, the search stops:
gnatmake, there is
one default project directory: `<prefix>/lib/gnat/'. In our example,
`gtkada.gpr' is found in the predefined directory if it was installed at
the same root as GNAT.
Some tools also support extending the project path from the command line,
generally through the `-aP'. You can see the value of the project
path by using the gnatls -v command.
Any symbolic link will be fully resolved in the directory of the importing project file before the imported project file is examined.
Any source file in the imported project can be used by the sources of the
importing project, transitively.
Thus if A imports B, which imports C, the sources of
A may depend on the sources of C, even if A does not
import C explicitly. However, this is not recommended, because if
and when B ceases to import C, some sources in A will
no longer compile. gprbuild has a switch `--no-indirect-imports'
that will report such indirect dependencies.
One very important aspect of a project hierarchy is that
a given source can only belong to one project (otherwise the project manager
would not know which settings apply to it and when to recompile it). It means
that different project files do not usually share source directories or
when they do, they need to specify precisely which project owns which sources
using attribute Source_Files or equivalent. By contrast, 2 projects
can each own a source with the same base file name as long as they live in
different directories. The latter is not true for Ada Sources because of the
correlation betwen source files and Ada units.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Cyclic dependencies are mostly forbidden:
if A imports B (directly or indirectly) then B
is not allowed to import A. However, there are cases when cyclic
dependencies would be beneficial. For these cases, another form of import
between projects exists: the limited with. A project A that
imports a project B with a straight with may also be imported,
directly or indirectly, by B through a limited with.
The difference between straight with and limited with is that
the name of a project imported with a limited with cannot be used in the
project importing it. In particular, its packages cannot be renamed and
its variables cannot be referred to.
with "b.gpr";
with "c.gpr";
project A is
For Exec_Dir use B'Exec_Dir; -- ok
end A;
limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
project B is
For Exec_Dir use A'Exec_Dir; -- not ok
end B;
with "d.gpr";
project C is
end C;
limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
project D is
For Exec_Dir use A'Exec_Dir; -- not ok
end D;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When building an application, it is common to have similar needs in severa of the projects corresponding to the subsystems under construction. For instance, they will all have the same compilation switches.
As seen before (see section 11.2.4 Tools Options in Project Files), setting compilation
switches for all sources of a subsystem is simple: it is just a matter of
adding a Compiler.Default_Switches attribute to each project files with
the same value. Of course, that means duplication of data, and both places need
to be changed in order to recompile the whole application with different
switches. It can become a real problem if there are many subsystems and thus
many project files to edit.
There are two main approaches to avoiding this duplication:
project Logging is
package Compiler is
for Switches ("Ada") use ("-O2");
end Compiler;
package Binder is
for Switches ("Ada") use ("-E");
end Binder;
end Logging;
with "logging.gpr";
project Build is
package Compiler renames Logging.Compiler;
package Binder is
for Switches ("Ada") use Logging.Binder'Switches ("Ada");
end Binder;
end Build;
|
The solution used for Compiler gets the same value for all
attributes of the package, but you cannot modify anything from the
package (adding extra switches or some exceptions). The second
version is more flexible, but more verbose.
If you need to refer to the value of a variable in an imported project, rather than an attribute, the syntax is similar but uses a "." rather than an apostrophe. For instance:
with "imported";
project Main is
Var1 := Imported.Var;
end Main;
|
abstract project Shared is
for Source_Files use (); -- no project
package Compiler is
for Switches ("Ada") use ("-O2");
end Compiler;
end Shared;
with "shared.gpr";
project Logging is
package Compiler renames Shared.Compiler;
end Logging;
with "shared.gpr";
project Build is
package Compiler renames Shared.Compiler;
end Build;
|
As for the first example, we could have chosen to set the attributes
one by one rather than to rename a package. The reason we explicitly
indicate that Shared has no sources is so that it can be created
in any directory and we are sure it shares no sources with Build
or Logging, which of course would be invalid.
Note the additional use of the abstract qualifier in `shared.gpr'. This qualifier is optional, but helps convey the message that we do not intend this project to have sources (see section 11.7.2 Qualified Projects for more qualifiers).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We have already seen many examples of attributes used to specify a special option of one of the tools involved in the build process. Most of those attributes are project specific. That it to say, they only affect the invocation of tools on the sources of the project where they are defined.
There are a few additional attributes that apply to all projects in a hierarchy as long as they are defined on the "main" project. The main project is the project explicitly mentioned on the command-line. The project hierarchy is the "with"-closure of the main project.
Here is a list of commonly used global attributes:
Compiler.Local_Configuration_Pragmas attribute.
Compiler package, which only apply to
the sources of the corresponding project. This attribute is indexed on
the name of the language.
Using such global capabilities is convenient. It can also lead to unexpected behavior. Especially when several subsystems are shared among different main projects and the different global attributes are not compatible. Note that using aggregate projects can be a safer and more powerful replacement to global attributes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Various aspects of the projects can be modified based on scenarios. These are user-defined modes that change the behavior of a project. Typical examples are the setup of platform-specific compiler options, or the use of a debug and a release mode (the former would activate the generation of debug information, when the second will focus on improving code optimization).
Let's enhance our example to support a debug and a release modes.The issue is to let the user choose what kind of system he is building: use `-g' as compiler switches in debug mode and `-O2' in release mode. We will also setup the projects so that we do not share the same object directory in both modes, otherwise switching from one to the other might trigger more recompilations than needed or mix objects from the 2 modes.
One naive approach is to create two different project files, say `build_debug.gpr' and `build_release.gpr', that set the appropriate attributes as explained in previous sections. This solution does not scale well, because in presence of multiple projects depending on each other, you will also have to duplicate the complete hierarchy and adapt the project files to point to the right copies.
Instead, project files support the notion of scenarios controlled by external values. Such values can come from several sources (in decreasing order of priority):
gnatmake or gprbuild, the user can pass
extra `-X' switches to define the external value. In
our case, the command line might look like
gnatmake -Pbuild.gpr -Xmode=debug or gnatmake -Pbuild.gpr -Xmode=release |
We now need to get that value in the project. The general form is to use the predefined function external which returns the current value of the external. For instance, we could setup the object directory to point to either `obj/debug' or `obj/release' by changing our project to
project Build is
for Object_Dir use "obj/" & external ("mode", "debug");
... -- as before
end Build;
|
The second parameter to external is optional, and is the default
value to use if "mode" is not set from the command line or the environment.
In order to set the switches according to the different scenarios, other constructs have to be introduced such as typed variables and case statements.
A typed variable is a variable that can take only a limited number of values, similar to an enumeration in Ada. Such a variable can then be used in a case statement and create conditional sections in the project. The following example shows how this can be done:
project Build is
type Mode_Type is ("debug", "release"); -- all possible values
Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
package Compiler is
case Mode is
when "debug" =>
for Switches ("Ada") use ("-g");
when "release" =>
for Switches ("Ada") use ("-O2");
end case;
end Compiler;
end Build;
|
The project has suddenly grown in size, but has become much more flexible.
Mode_Type defines the only valid values for the mode variable. If
any other value is read from the environment, an error is reported and the
project is considered as invalid.
The Mode variable is initialized with an external value
defaulting to "debug". This default could be omitted and that would
force the user to define the value. Finally, we can use a case statement to set the
switches depending on the scenario the user has chosen.
Most aspects of the projects can depend on scenarios. The notable exception
are project dependencies (with clauses), which may not depend on a scenario.
Scenarios work the same way with project hierarchies: you can either
duplicate a variable similar to Mode in each of the project (as long
as the first argument to external is always the same and the type is
the same), or simply set the variable in the `shared.gpr' project
(see section 11.3.3 Sharing Between Projects).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
So far, we have seen examples of projects that create executables. However, it is also possible to create libraries instead. A library is a specific type of subsystem where, for convenience, objects are grouped together using system-specific means such as archives or windows DLLs.
Library projects provide a system- and language-independent way of building both static and dynamic libraries. They also support the concept of standalone libraries (SAL) which offers two significant properties: the elaboration (e.g. initialization) of the library is either automatic or very simple; a change in the implementation part of the library implies minimal post-compilation actions on the complete system and potentially no action at all for the rest of the system in the case of dynamic SALs.
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).
11.5.1 Building Libraries 11.5.2 Using Library Projects 11.5.3 Stand-alone Library Projects 11.5.4 Installing a library with project files
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Let's enhance our example and transform the logging subsystem into a
library.In orer to do so, a few changes need to be made to `logging.gpr'.
A number of specific attributes needs to be defined: at least Library_Name
and Library_Dir; in addition, a number of other attributes can be used
to specify specific aspects of the library. For readablility, it is also
recommended (although not mandatory), to use the qualifier library in
front of the project keyword.
Object_Dir directory. When all sources of a library
are compiled, some of the compilation artifacts, including the library itself,
are copied to the library_dir directory. This directory must exists and be
writable. It must also be different from the object directory so that cleanup
activities in the Library_Dir do not affect recompilation needs.
Here is the new version of `logging.gpr' that makes it a library:
library project Logging is -- "library" is optional for Library_Name use "logging"; -- will create "liblogging.a" on Unix for Object_Dir use "obj"; for Library_Dir use "lib"; -- different from object_dir end Logging; |
Once the above two attributes are defined, the library project is valid and is enough for building a library with default characteristics. Other library-related attributes can be used to change the defaults:
"static", "dynamic" or
"relocatable" (the latter is a synonym for dynamic). It indicates
which kind of library should be build (the default is to build a
static library, that is an archive of object files that can potentially
be linked into a static executable). When the library is set to be dynamic,
a separate image is created that will be loaded independnently, usually
at the start of the main program execution. Support for dynamic libraries is
very platform specific, for instance on Windows it takes the form of a DLL
while on GNU/Linux, it is a dynamic elf image whose suffix is usually
`.so'. Library project files, on the other hand, can be written in
a platform independant way so that the same project file can be used to build
a library on different Oses.
If you need to build both a static and a dynamic library, it is recommended use two different object directories, since in some cases some extra code needs to be generated for the latter. For such cases, one can either define two different project files, or a single one which uses scenarios to indicate at the various kinds of library to be build and their corresponding object_dir.
Library_Dir directory, but as for the executables where we have a
separate Exec_Dir attribute, you might want to put them in a separate
directory since there can be hundreds of them. The same restrictions as for
the Library_Dir attribute apply.
"soname"). If the library file name (built
from the Library_Name) is different from the Library_Version,
then the library file will be a symbolic link to the actual file whose name
will be Library_Version. This follows the usual installation schemes
for dynamic libraries on many Unix systems.
project Logging is
Version := "1";
for Library_Dir use "lib";
for Library_Name use "logging";
for Library_Kind use "dynamic";
for Library_Version use "liblogging.so." & Version;
end Logging;
|
After the compilation, the directory `lib' will contain both a `libdummy.so.1' library and a symbolic link to it called `libdummy.so'.
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When the builder detects that a project file is a library project file, it recompiles all sources of the project that need recompilation and rebuild the library if any of the sources have been recompiled. It then groups all object files into a single file, which is a shared or a static library. This library can later on be linked with multiple executables. Note that the use of shard libraries reduces the size of the final executable and can also reduce the memory footprint at execution time when the library is shared among several executables.
It is also possible to build multi-language libraries. When using
gprbuild as a builder, multi-language library projects allow naturally
the creation of multi-language libraries . gnatmake, does n ot try to
compile non Ada sources. However, when the project is multi-language, it will
automatically link all object files found in the object directory, whether or
not they were compiled from an Ada source file. This specific behavior does not
apply to Ada-only projects which only take into account the objects
corresponding to the sources of the project.
A non-library project can import a library project. When the builder is invoked
on the former, the library of the latter is only rebuilt when absolutely
necessary. For instance, if a unit of the
library is not up-to-date but non of the executables need this unit, then the
unit is not recompiled and the library is not reassembled.
For instance, let's assume in our example that logging has the following
sources: `log1.ads', `log1.adb', `log2.ads' and
`log2.adb'. If `log1.adb' has been modified, then the library
`liblogging' will be rebuilt when compiling all the sources of
Build only if `proc.ads', `pack.ads' or `pack.adb'
include a "with Log1".
To ensure that all the sources in the Logging library are
up to date, and that all the sources of Build are also up to date,
the following two commands needs to be used:
gnatmake -Plogging.gpr gnatmake -Pbuild.gpr |
All `ALI' files will also be copied from the object directory to the
library directory. To build executables, gnatmake will use the
library rather than the individual object files.
Library projects can also be useful to describe a library that need to be used
but, for some reason, cannot be rebuilt. For instance, it is the case when some
of the library sources are not available. Such library projects need simply to
use the Externally_Built attribute as in the example below:
library project Extern_Lib is
for Languages use ("Ada", "C");
for Source_Dirs use ("lib_src");
for Library_Dir use "lib2";
for Library_Kind use "dynamic";
for Library_Name use "l2";
for Externally_Built use "true"; -- <<<<
end Extern_Lib;
|
In the case of externally built libraries, the Object_Dir
attribute does not need to be specified because it will never be
used.
The main effect of using such an externally built library project is mostly to
affect the linker command in order to reference the desired library. It can
also be achieved by using Linker.Linker_Options or Linker.Switches
in the project corresponding to the subsystem needing this external library.
This latter method is more straightforward in simple cases but when several
subsystems depend upon the same external library, finding the proper place
for the Linker.Linker_Options might not be easy and if it is
not placed properly, the final link command is likely to present ordering issues.
In such a situation, it is better to use the externally built library project
so that all other subsystems depending on it can declare this dependency thanks
to a project with clause, which in turn will trigger the builder to find
the proper order of libraries in the final link command.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 & redeployement of complex systems when localized changes are made.
The most proeminent characteristic of a stand-alone library is that it offers a
distinction between interface units and implementation units. Only the former
are visible to units outside the library. A stand-alone library project is thus
characterised by a third attribute, Library_Interface, in addition to the
two attributes that make a project a Library Project (Library_Name and
Library_Dir).
Library_Interface. Other sources are considered
implementation units.
for Library_Dir use "lib";
for Library_Name use "loggin";
for Library_Interface use ("lib1", "lib2"); -- unit names
|
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.
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_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.
gnatbind.
gcc
when linking the library.
Inline are used, or when there is a generic
units in the spec. This directory cannot point to the object directory or
one of the source directories, but it can point to the library directory,
which is the default value for this attribute.
"autonomous" or "default": exported symbols are not controlled
"compliant": if attribute Library_Reference_Symbol_File
is not defined, then it is equivalent to policy "autonomous". If there
are exported symbols in the reference symbol file that are not in the
object files of the interfaces, the major ID of the library is increased.
If there are symbols in the object files of the interfaces that are not
in the reference symbol file, these symbols are put at the end of the list
in the newly created symbol file and the minor ID is increased.
"controlled": the attribute Library_Reference_Symbol_File must be
defined. The library will fail to build if the exported symbols in the
object files of the interfaces do not match exactly the symbol in the
symbol file.
"restricted": The attribute Library_Symbol_File must be defined.
The library will fail to build if there are symbols in the symbol file that
are not in the exported symbols of the object files of the interfaces.
Additional symbols in the object files are not added to the symbol file.
"direct": The attribute Library_Symbol_File must be defined and
must designate an existing file in the object directory. This symbol file
is passed directly to the underlying linker without any symbol processing.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When using project files, library installation is part of the library build
process. Thus no further action is needed in order to make use of the
libraries that are built as part of the general application build. A usable
version of the library is installed in the directory specified by the
Library_Dir attribute of the library project file.
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. 11.5.2 Using Library Projects
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
During development of a large system, it is sometimes necessary to use modified versions of some of the source files, without changing the original sources. This can be achieved through the project extension facility.
Suppose for instance that our example Build project is build every night
for the whole team, in some shared directory. A developer usually need to work
on a small part of the system, and might not want to have a copy of all the
sources and all the object files (mostly because that would require too much
disk space, time to recompile everything). He prefers to be able to override
some of the source files in his directory, while taking advantage of all the
object files generated at night.
Another example can be taken from large software systems, where it is common to have multiple implementations of a common interface; in Ada terms, multiple versions of a package body for the same spec. For example, one implementation might be safe for use in tasking programs, while another might only be used in sequential applications. This can be modeled in GNAT using the concept of project extension. If one project (the "child") extends another project (the "parent") then by default all source files of the parent project are inherited by the child, but the child project can override any of the parent's source files with new versions, and can also add new files or remove unnecessary ones. This facility is the project analog of a type extension in object-oriented programming. Project hierarchies are permitted (an extending project may itself be extended), and a project that extends a project can also import other projects.
A third example is that of using project extensions to provide different
versions of the same system. For instance, assume that a Common
project is used by two development branches. One of the branches has now
been frozen, and no further change can be done to it or to Common.
However, the other development branch still needs evolution of Common.
Project extensions provide a flexible solution to create a new version
of a subsystem while sharing and reusing as much as possible from the original
one.
A project extension inherits implicitly all the sources and objects from the
project it extends. It is possible to create a new version of some of the
sources in one of the additional source dirs of the extending project. Those new
versions hide the original versions. Adding new sources or removing existing
ones is also possible. Here is an example on how to extend the project
Build from previous examples:
project Work extends "../bld/build.gpr" is end Work; |
The project after extends is the one being extended. As usual, it can be
specified using an absolute path, or a path relative to any of the directories
in the project path (see section 11.3.1 Project Dependencies). This project does not
specify source or object directories, so the default value for these attribute
will be used that is to say the current directory (where project Work is
placed). We can already compile that project with
gnatmake -Pwork |
If no sources have been placed in the current directory, this command
won't do anything, since this project does not change the
sources it inherited from Build, therefore all the object files
in Build and its dependencies are still valid and are reused
automatically.
Suppose we now want to supply an alternate version of `pack.adb'
but use the existing versions of `pack.ads' and `proc.adb'.
We can create the new file Work's current directory (likely
by copying the one from the Build project and making changes to
it. If new packages are needed at the same time, we simply create
new files in the source directory of the extending project.
When we recompile, gnatmake will now automatically recompile
this file (thus creating `pack.o' in the current directory) and
any file that depends on it (thus creating `proc.o'). Finally, the
executable is also linked locally.
Note that we could have obtained the desired behavior using project import
rather than project inheritance. A base project would contain the
sources for `pack.ads' and `proc.adb', and Work would
import base and add `pack.adb'. In this scenario, base
cannot contain the original version of `pack.adb' otherwise there would be
2 versions of the same unit in the closure of the project and this is not
allowed. Generally speaking, it is not recommended to put the spec and the
body of a unit in different projects since this affects their autonomy and
reusability.
In a project file that extends another project, it is possible to indicate that an inherited source is not part of the sources of the extending project. This is necessary sometimes when a package spec has been overridden and no longer requires a body: in this case, it is necessary to indicate that the inherited body is not part of the sources of the project, otherwise there will be a compilation error when compiling the spec.
For that purpose, the attribute Excluded_Source_Files is used.
Its value is a list of file names.
It is also possible to use attribute Excluded_Source_List_File.
Its value is the path of a text file containing one file name per
line.
project Work extends "../bld/build.gpr" is
for Source_Files use ("pack.ads");
-- New spec of Pkg does not need a completion
for Excluded_Source_Files use ("pack.adb");
end Work;
|
An extending project retains all the switches specified in the extended project.
11.6.1 Project Hierarchy Extension
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
One of the fundamental restrictions in project extension is the following: A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors.
By means of example, consider the following hierarchy of projects.
a.gpr contains package A1 b.gpr, imports a.gpr and contains B1, which depends on A1 c.gpr, imports b.gpr and contains C1, which depends on B1 |
If we want to locally extend the packages A1 and C1, we need to
create several extending projects:
a_ext.gpr which extends a.gpr, and overrides A1 b_ext.gpr which extends b.gpr and imports a_ext.gpr c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 |
project A_Ext extends "a.gpr" is
for Source_Files use ("a1.adb", "a1.ads");
end A_Ext;
with "a_ext.gpr";
project B_Ext extends "b.gpr" is
end B_Ext;
with "b_ext.gpr";
project C_Ext extends "c.gpr" is
for Source_Files use ("c1.adb");
end C_Ext;
|
The extension `b_ext.gpr' is required, even though we are not overriding any of the sources of `b.gpr' because otherwise `c_expr.gpr' would import `b.gpr' which itself knows nothing about `a_ext.gpr'.
When extending a large system spanning multiple projects, it is often inconvenient to extend every project in the hierarchy that is impacted by a small change introduced in a low layer. In such cases, it is possible to create an implicit extension of entire hierarchy using extends all relationship.
When the project is extended using extends all inheritance, all projects
that are imported by it, both directly and indirectly, are considered virtually
extended. That is, the project manager creates implicit projects
that extend every project in the hierarchy; all these implicit projects do not
control sources on their own and use the object directory of
the "extending all" project.
It is possible to explicitly extend one or more projects in the hierarchy in order to modify the sources. These extending projects must be imported by the "extending all" project, which will replace the corresponding virtual projects with the explicit ones.
When building such a project hierarchy extension, the project manager will ensure that both modified sources and sources in implicit extending projects that depend on them, are recompiled.
Thus, in our example we could create the following projects instead:
a_ext.gpr, extends a.gpr and overrides A1 c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 |
project A_Ext extends "a.gpr" is
for Source_Files use ("a1.adb", "a1.ads");
end A_Ext;
with "a_ext.gpr";
project C_Ext extends all "c.gpr" is
for Source_Files use ("c1.adb");
end C_Ext;
|
When building project `c_ext.gpr', the entire modified project space is
considered for recompilation, including the sources of `b.gpr' that are
impacted by the changes in A1 and C1.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the syntactic structure of project files, the various constructs that can be used. Finally, it ends with a summary of all available attributes.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Project files have an Ada-like syntax. The minimal project file is:
project Empty is end Empty; |
The identifier Empty is the name of the project.
This project name must be present after the reserved
word end at the end of the project file, followed by a semi-colon.
Identifiers (ie the user-defined names such as project or variable names) have the same syntax as Ada identifiers: they must start with a letter, and be followed by zero or more letters, digits or underscore characters; it is also illegal to have two underscores next to each other. Identifiers are always case-insensitive ("Name" is the same as "name").
simple_name ::= identifier
name ::= simple_name { . simple_name }
|
Strings are used for values of attributes or as indexes for these attributes. They are in general case sensitive, except when noted otherwise (in particular, strings representing file names will be case insensitive on some systems, so that "file.adb" and "File.adb" both represent the same file).
Reserved words are the same as for standard Ada 95, and cannot
be used for identifiers. In particular, the following words are currently
used in project files, but others could be added later on. In bold are the
extra reserved words in project files: all, at, case, end, for, is,
limited, null, others, package, renames, type, use, when, with, extends,
external, project.
Comments in project files have the same syntax as in Ada, two consecutive hyphens through the end of the line.
A project may be an independent project, entirely defined by a single project file. Any source file in an independent project depends only on the predefined library and other source files in the same project. But a project may also depend on other projects, either by importing them through with clauses, or by extending at most one other project. Both types of dependency can be used in the same project.
A path name denotes a project file. It can be absolute or relative. An absolute path name includes a sequence of directories, in the syntax of the host operating system, that identifies uniquely the project file in the file system. A relative path name identifies the project file, relative to the directory that contains the current project, or relative to a directory listed in the environment variables ADA_PROJECT_PATH and GPR_PROJECT_PATH. Path names are case sensitive if file names in the host operating system are case sensitive. As a special case, the directory separator can always be "/" even on Windows systems, so that project files can be made portable across architectures. The syntax of the environment variable ADA_PROJECT_PATH and GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and semicolons on Windows.
A given project name can appear only once in a context clause.
It is illegal for a project imported by a context clause to refer, directly or indirectly, to the project in which this context clause appears (the dependency graph cannot contain cycles), except when one of the with clause in the cycle is a limited with.
with "other_project.gpr"; project My_Project extends "extended.gpr" is end My_Project; |
These dependencies form a directed graph, potentially cyclic when using limited with. The subprogram reflecting the extends relations is a tree.
A project's immediate sources are the source files directly defined by that project, either implicitly by residing in the project source directories, or explicitly through any of the source-related attributes. More generally, a project sources are the immediate sources of the project together with the immediate sources (unless overridden) of any project on which it depends directly or indirectly.
A project hierarchy can be created, where projects are children of
other projects. The name of such a child project must be Parent.Child,
where Parent is the name of the parent project. In particular, this
makes all with clauses of the parent project automatically visible
in the child project.
project ::= context_clause project_declaration
context_clause ::= {with_clause}
with_clause ::= with path_name { , path_name } ;
path_name ::= string_literal
project_declaration ::= simple_project_declaration | project_extension
simple_project_declaration ::=
project <project_>name is
{declarative_item}
end <project_>simple_name;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Before the reserved project, there may be one or two qualifiers, that
is identifiers or reserved words, to qualify the project.
The current list of qualifiers is:
Source_Dirs,
Source_Files, Languages or Source_List_File, or one of
Source_Dirs, Source_Files, or Languages must be declared
as empty. If it extends another project, the project it extends must also be a
qualified abstract project.
Library_Name and Library_Dir.
gprbuild.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Declarations introduce new entities that denote types, variables, attributes, and packages. Some declarations can only appear immediately within a project declaration. Others can appear within a project or within a package.
declarative_item ::= simple_declarative_item | typed_string_declaration | package_declaration simple_declarative_item ::= variable_declaration | typed_variable_declaration | attribute_declaration | case_construction | empty_declaration empty_declaration ::= null ; |
An empty declaration is allowed anywhere a declaration is allowed. It has no effect.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A project file may contain packages, that group attributes (typically all the attributes that are used by one of the GNAT tools).
A package with a given name may only appear once in a project file. The following packages are currently supported in project files (See see section 11.7.9 Attributes for the list of attributes that each can contain).
Binder
gnat driver or when using a builder such as
gnatmake or gprbuild. See section 11.2.3 Main Subprograms.
Builder
Compiler, Binder or Linker packages,
but there are some general options that should be defined in this
package. See section 11.2.3 Main Subprograms, and see section 11.2.6 Executable File Names in
particular.
Check
gnatcheck via the gnat driver. Its attribute
Default_Switches has the same semantics as for the package
Builder. The first string should always be -rules to specify
that all the other options belong to the -rules section of the
parameters to gnatcheck.
Compiler
Cross_Reference
gnatxref via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Eliminate
gnatelim via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Finder
gnatfind via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Gnatls
gnatls via the
gnat driver.
Gnatstub
gnatstub via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
IDE
GPS or Gnatbench.
See section 12.3 The Development Environments.
Linker
Metrics
gnatmetric via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Naming
Pretty_Printer
gnatpp via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Stack
gnatstack via the gnat driver. Its attributes
Default_Switches and Switches have the same semantics as for the
package Builder.
Synchronize
gnatsync via the gnat driver.
In its simplest form, a package may be empty:
project Simple is package Builder is end Builder; end Simple; |
A package may contain attribute declarations, variable declarations and case constructions, as will be described below.
When there is ambiguity between a project name and a package name,
the name always designates the project. To avoid possible confusion, it is
always a good idea to avoid naming a project with one of the
names allowed for packages or any name that starts with gnat.
A package can also be defined by a renaming declaration. The new package
renames a package declared in a different project file, and has the same
attributes as the package it renames. The name of the renamed package
must be the same as the name of the renaming package. The project must
contain a package declaration with this name, and the project
must appear in the context clause of the current project, or be its parent
project. It is not possible to add or override attributes to the renaming
project. If you need to do so, you should declare a standard package, and
assign the value of the attributes one by one (for Switches ("Ada")
use Other_Project.Compiler'Switches ("Ada")).
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_declaration ::= package_spec | package_renaming
package_spec ::=
package <package_>simple_name is
{simple_declarative_item}
end package_identifier ;
package_renaming ::==
package <package_>simple_name renames <project_>simple_name.package_identifier ;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An expression is any value that can be assigned to an attribute or a variable. It is either a litteral value, or a construct requiring runtime computation by the project manager. In a project file, the computed value of an expression is either a string or a list of strings.
A string value is one of:
"comm/my_proj.gpr"
"prefix_" & Var.
A list of strings is one of the following:
(File_Name, "gnat.adc", File_Name & ".orig") or ().
("A", "B") & "C"
The following is the grammar for expressions
string_literal ::= "{string_element}" -- Same as Ada
string_expression ::= string_literal
| variable_name
| external_value
| attribute_reference
| ( string_expression { & string_expression } )
string_list ::= ( string_expression { , string_expression } )
| string_variable_name
| string_attribute_reference
term ::= string_expression | string_list
expression ::= term { & term } -- Concatenation
|
Concatenation involves strings and list of strings. As soon as a list of strings is involved, the result of the concatenation is a list of strings. The following Ada declarations show the existing operators:
function "&" (X : String; Y : String) return String; function "&" (X : String_List; Y : String) return String_List; function "&" (X : String_List; Y : String_List) return String_List; |
Here are some specific examples:
List := () & File_Name; -- One string in this list List2 := List & (File_Name & ".orig"); -- Two strings Big_List := List & Lists2; -- Three strings Illegal := "gnat.adc" & List2; -- Illegal, must start with list |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An external value is an expression whose value is obtained from the command that invoked the processing of the current project file (typically a gnatmake or gprbuild command).
external_value ::= external ( string_literal [, string_literal] ) |
The first string_literal is the string to be used on the command line or in the environment to specify the external value. The second string_literal, if present, is the default to use if there is no specification for this external value either on the command line or in the environment.
Typically, the external value will either exist in the environment variables or be specified on the command line through the `-Xvbl=value' switch. If both are specified, then the command line value is used, so that a user can more easily override the value.
The function external always returns a string, possibly empty if the
value was not found in the environment and no default was specified in the
call to external.
An external reference may be part of a string expression or of a string list expression, and can therefore appear in a variable declaration or an attribute declaration.
Most of the time, this construct is used to initialize typed variables, which are then used in case statements to control the value assigned to attributes in various scenarios. Thus such variables are often called scenario variables.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A type declaration introduces a discrete set of string literals. If a string variable is declared to have this type, its value is restricted to the given set of literals. These are the only named types in project files. A string type may only be declared at the project level, not inside a package.
typed_string_declaration ::=
type <typed_string_>_simple_name is ( string_literal {, string_literal} );
|
The string literals in the list are case sensitive and must all be different. They may include any graphic characters allowed in Ada, including spaces. Here is an example of a string type declaration:
type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
|
Variables of a string type are called typed variables; all other
variables are called untyped variables. Typed variables are
particularly useful in case constructions, to support conditional
attribute declarations. (see section 11.7.10 Case Statements).
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 statements see the same value for the variable. This provides more consistency and makes the project easier to understand. The syntax for its declaration is identical to the Ada syntax for an object declaration. In effect, a typed variable acts as a constant.
An untyped variable can be declared and overridden multiple times within the same project. It is declared implicitly through an Ada assignment. The first declaration establishes the kind of the variable (string or list of strings) and successive declarations must respect the initial kind. Assignments are executed in the order in which they appear, so the new value replaces the old one and any subsequent reference to the variable uses the new value.
A variable may be declared at the project file level, or within a package.
typed_variable_declaration ::= <typed_variable_>simple_name : <typed_string_>name := string_expression; variable_declaration ::= <variable_>simple_name := expression; |
Here are some examples of variable declarations:
This_OS : OS := external ("OS"); -- a typed variable declaration
That_OS := "GNU/Linux"; -- an untyped variable declaration
Name := "readme.txt";
Save_Name := Name & ".saved";
Empty_List := ();
List_With_One_Element := ("-gnaty");
List_With_Two_Elements := List_With_One_Element & "-gnatg";
Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
|
A variable reference may take several forms:
A context may be one of the following:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A project (and its packages) may have attributes that define the project's properties. Some attributes have values that are strings; others have values that are string lists.
attribute_declaration ::= simple_attribute_declaration | indexed_attribute_declaration simple_attribute_declaration ::= for attribute_designator use expression ; indexed_attribute_declaration ::= for <indexed_attribute_>simple_name ( string_literal) use expression ; attribute_designator ::= <simple_attribute_>simple_name | <indexed_attribute_>simple_name ( string_literal ) |
There are two categories of attributes: simple attributes and indexed attributes. Each simple attribute has a default value: the empty string (for string attributes) and the empty list (for string list attributes). An attribute declaration defines a new value for an attribute, and overrides the previous value. The syntax of a simple attribute declaration is similar to that of an attribute definition clause in Ada.
Some attributes are indexed. These attributes are mappings whose domain is a set of strings. They are declared one association at a time, by specifying a point in the domain and the corresponding image of the attribute. Like untyped variables and simple attributes, indexed attributes may be declared several times. Each declaration supplies a new value for the attribute, and replaces the previous setting.
Here are some examples of attribute declarations:
-- simple attributes
for Object_Dir use "objects";
for Source_Dirs use ("units", "test/drivers");
-- indexed attributes
for Body ("main") use "Main.ada";
for Switches ("main.ada") use ("-v", "-gnatv");
for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
-- indexed attributes copy (from package Builder in project Default)
-- The package name must always be specified, even if it is the current
-- package.
for Default_Switches use Default.Builder'Default_Switches;
|
Attributes references may be appear anywhere in expressions, and are used to retrieve the value previously assigned to the attribute. If an attribute has not been set in a given package or project, its value defaults to the empty string or the empty list.
attribute_reference ::= attribute_prefix ' <simple_attribute>_simple_name [ (string_literal) ] attribute_prefix ::= project | <project_>simple_name | package_identifier | <project_>simple_name . package_identifier |
Examples are:
project'Object_Dir
Naming'Dot_Replacement
Imported_Project'Source_Dirs
Imported_Project.Naming'Casing
Builder'Default_Switches ("Ada")
|
The prefix of an attribute may be:
project for an attribute of the current project
Legal attribute names are listed below, including the package in which they must be declared. These names are case-insensitive. The semantics for the attributes is explained in great details in other sections.
The column index indicates whether the attribute is an indexed attribute, and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the system (file). The text is between brackets ([]) if the index is optional.
| Value | Package | Index @headitem General attributes | see section 11.2 Building With Projects | |||
| Name | string | - | (Read-only, name of project) | |||
| Project_Dir | string | - | (Read-only, directory of project) | |||
| Source_Files | list | - | - | |||
| Source_Dirs | list | - | - | |||
| Source_List_File | string | - | - | |||
| Locally_Removed_Files | list | - | - | |||
| Excluded_Source_Files | list | - | - | |||
| Object_Dir | string | - | - | |||
| Exec_Dir | string | - | - | |||
| Excluded_Source_Dirs | list | - | - | |||
| Excluded_Source_Files | list | - | - | |||
| Excluded_Source_List_File | list | - | - | |||
| Inherit_Source_Path | list | - | insensitive | |||
| Languages | list | - | - | |||
| Main | list | - | - | |||
| Main_Language | string | - | - | |||
| Externally_Built | string | - | - | |||
| Roots | list | - | file | @headitem Library-related attributessee section 11.5 Library Projects | ||
| Library_Dir | string | - | - | |||
| Library_Name | string | - | - | |||
| Library_Kind | string | - | - | |||
| Library_Version | string | - | - | |||
| Library_Interface | string | - | - | |||
| Library_Auto_Init | string | - | - | |||
| Library_Options | list | - | - | |||
| Library_Src_Dir | string | - | - | |||
| Library_ALI_Dir | string | - | - | |||
| Library_GCC | string | - | - | |||
| Library_Symbol_File | string | - | - | |||
| Library_Symbol_Policy | string | - | - | |||
| Library_Reference_Symbol_File | string | - | - | |||
| Interfaces | list | - | - | @headitem Namingsee section 11.2.8 Naming Schemes | ||
| Spec_Suffix | string | Naming | insensitive (language) | |||
| Body_Suffix | string | Naming | insensitive (language) | |||
| Separate_Suffix | string | Naming | - | |||
| Casing | string | Naming | - | |||
| Dot_Replacement | string | Naming | - | |||
| Spec | string | Naming | insensitive (Ada unit) | |||
| Body | string | Naming | insensitive (Ada unit) | |||
| Specification_Exceptions | list | Naming | insensitive (language) | |||
| Implementation_Exceptions | list | Naming | insensitive (language) | @headitem Buildingsee section 12.1.2 Switches and Project Files | ||
| Default_Switches | list | Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE | insensitive (language name) | |||
| Switches | list | Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack | [file] (file name) | |||
| Local_Configuration_Pragmas | string | Compiler | - | |||
| Local_Config_File | string | insensitive | - | |||
| Global_Configuration_Pragmas | list | Builder | - | |||
| Global_Compilation_Switches | list | Builder | language | |||
| Executable | string | Builder | [file] | |||
| Executable_Suffix | string | Builder | - | |||
| Global_Config_File | string | Builder | insensitive (language) | @headitem IDE (used and created by GPS)|||
| Remote_Host | string | IDE | - | |||
| Program_Host | string | IDE | - | |||
| Communication_Protocol | string | IDE | - | |||
| Compiler_Command | string | IDE | insensitive (language) | |||
| Debugger_Command | string | IDE | - | |||
| Gnatlist | string | IDE | - | |||
| VCS_Kind | string | IDE | - | |||
| VCS_File_Check | string | IDE | - | |||
| VCS_Log_Check | string | IDE | - | @headitem Configuration filesSee gprbuild manual | ||
| Default_Language | string | - | - | |||
| Run_Path_Option | list | - | - | |||
| Run_Path_Origin | string | - | - | |||
| Separate_Run_Path_Options | string | - | - | |||
| Toolchain_Version | string | - | insensitive | |||
| Toolchain_Description | string | - | insensitive | |||
| Object_Generated | string | - | insensitive | |||
| Objects_Linked | string | - | insensitive | |||
| Target | string | - | - | |||
| Library_Builder | string | - | - | |||
| Library_Support | string | - | - | |||
| Archive_Builder | list | - | - | |||
| Archive_Builder_Append_Option | list | - | - | |||
| Archive_Indexer | list | - | - | |||
| Archive_Suffix | string | - | - | |||
| Library_Partial_Linker | list | - | - | |||
| Shared_Library_Prefix | string | - | - | |||
| Shared_Library_Suffix | string | - | - | |||
| Symbolic_Link_Supported | string | - | - | |||
| Library_Major_Minor_Id_Supported | string | - | - | |||
| Library_Auto_Init_Supported | string | - | - | |||
| Shared_Library_Minimum_Switches | list | - | - | |||
| Library_Version_Switches | list | - | - | |||
| Library_Install_Name_Option | string | - | - | |||
| Runtime_Library_Dir | string | - | insensitive | |||
| Runtime_Source_Dir | string | - | insensitive | |||
| Driver | string | Compiler,Binder,Linker | insensitive (language) | |||
| Required_Switches | list | Compiler,Binder,Linker | insensitive (language) | |||
| Leading_Required_Switches | list | Compiler | insensitive (language) | |||
| Trailing_Required_Switches | list | Compiler | insensitive (language) | |||
| Pic_Options | list | Compiler | insensitive (language) | |||
| Path_Syntax | string | Compiler | insensitive (language) | |||
| Object_File_Suffix | string | Compiler | insensitive (language) | |||
| Object_File_Switches | list | Compiler | insensitive (language) | |||
| Multi_Unit_Switches | list | Compiler | insensitive (language) | |||
| Multi_Unit_Object_Separator | string | Compiler | insensitve (language) | |||
| Mapping_File_Switches | list | Compiler | insensitive (language) | |||
| Mapping_Spec_Suffix | string | Compiler | insensitive (language) | |||
| Mapping_body_Suffix | string | Compiler | insensitive (language) | |||
| Config_File_Switches | list | Compiler | insensitive (language) | |||
| Config_Body_File_Name | string | Compiler | insensitive (language) | |||
| Config_Body_File_Name_Index | string | Compiler | insensitive (language) | |||
| Config_Body_File_Name_Pattern | string | Compiler | insensitive (language) | |||
| Config_Spec_File_Name | string | Compiler | insensitive (language) | |||
| Config_Spec_File_Name_Index | string | Compiler | insensitive (language) | |||
| Config_Spec_File_Name_Pattern | string | Compiler | insensitive (language) | |||
| Config_File_Unique | string | Compiler | insensitive (language) | |||
| Dependency_Switches | list | Compiler | insensitive (language) | |||
| Dependency_Driver | list | Compiler | insensitive (language) | |||
| Include_Switches | list | Compiler | insensitive (language) | |||
| Include_Path | string | Compiler | insensitive (language) | |||
| Include_Path_File | string | Compiler | insensitive (language) | |||
| Prefix | string | Binder | insensitive (language) | |||
| Objects_Path | string | Binder | insensitive (language) | |||
| Objects_Path_File | string | Binder | insensitive (language) | |||
| Linker_Options | list | Linker | - | |||
| Map_File_Options | string | Linker | - | |||
| Executable_Switches | list | Linker | - | |||
| Lib_Dir_Switch | string | Linker | - | |||
| Lib_Name_Switch | string | Linker | - | |||
| Max_Command_Line_Length | string | Linker | - | |||
| Response_File_Format | string | Linker | - | |||
| Response_File_Switches | list | Linker | - |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A case statement is used in a project file to effect conditional behavior. Through this statement, you can set the value of attributes and variables depending on the value previously assigned to a typed variable.
All choices in a choice list must be distinct. Unlike Ada, the choice
lists of all alternatives do not need to include all values of the type.
An others choice must appear last in the list of alternatives.
The syntax of a case construction is based on the Ada case statement
(although the null statement for empty alternatives is optional).
The case expression must be a typed string variable, whose value is often given by an external reference (see section 11.7.6 External Values).
Each alternative starts with the reserved word when, either a list of
literal strings separated by the "|" character or the reserved word
others, and the "=>" token.
Each literal string must belong to the string type that is the type of the
case variable.
After each =>, there are zero or more statements. The only
statements allowed in a case construction are other case statements,
attribute declarations and variable declarations. String type declarations and
package declarations are not allowed. Variable declarations are restricted to
variables that have already been declared before the case construction.
case_statement ::=
case <typed_variable_>name is {case_item} end case ;
case_item ::=
when discrete_choice_list =>
{case_statement
| attribute_declaration
| variable_declaration
| empty_declaration}
discrete_choice_list ::= string_literal {| string_literal} | others
|
Here is a typical example:
project MyProj is
type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
OS : OS_Type := external ("OS", "GNU/Linux");
package Compiler is
case OS is
when "GNU/Linux" | "Unix" =>
for Switches ("Ada") use ("-gnath");
when "NT" =>
for Switches ("Ada") use ("-gnatP");
when others =>
null;
end case;
end Compiler;
end MyProj;
|
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |