| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
12.1 gnatmake and Project Files 12.2 The GNAT Driver and Project Files 12.3 The Development Environments
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section covers several topics related to gnatmake and
project files: defining switches for gnatmake
and for the tools that it invokes; specifying configuration pragmas;
the use of the Main attribute; building and rebuilding library project
files.
12.1.1 Switches Related to Project Files 12.1.2 Switches and Project Files 12.1.3 Specifying Configuration Pragmas 12.1.4 Project Files and Main Subprograms 12.1.5 Library Project Files
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following switches are used by GNAT tools that support project files:
There must be only one `-P' switch on the command line.
Since the Project Manager parses the project file only after all the switches on the command line are checked, the order of the switches `-P', `-vPx' or `-X' is not significant.
external(name) when parsing the project file.
If name or value includes a space, then name=value should be put between quotes.
-XOS=NT -X"user=John Doe" |
Several `-X' switches can be used simultaneously. If several `-X' switches specify the same name, only the last one is used.
An external variable specified with a `-X' switch takes precedence over the value of the same name in the environment.
`-vP0' means Default; `-vP1' means Medium; `-vP2' means High.
The default is Default: no output for syntactically correct project files. If several `-vPx' switches are present, only the last one is used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For each of the packages Builder, Compiler, Binder, and
Linker, you can specify a Default_Switches
attribute, a Switches attribute, or both;
as their names imply, these switch-related
attributes affect the switches that are used for each of these GNAT
components when
gnatmake is invoked. As will be explained below, these
component-specific switches precede
the switches provided on the gnatmake command line.
The Default_Switches attribute is an attribute
indexed by language name (case insensitive) whose value is a string list.
For example:
package Compiler is
for Default_Switches ("Ada")
use ("-gnaty",
"-v");
end Compiler;
|
The Switches attribute is indexed on a file name (which may or may
not be case sensitive, depending
on the operating system) whose value is a string list. For example:
package Builder is
for Switches ("main1.adb")
use ("-O2");
for Switches ("main2.adb")
use ("-g");
end Builder;
|
For the Builder package, the file names must designate source files
for main subprograms. For the Binder and Linker packages, the
file names must designate `ALI' or source files for main subprograms.
In each case just the file name without an explicit extension is acceptable.
For each tool used in a program build (gnatmake, the compiler, the
binder, and the linker), the corresponding package contributes a set of
switches for each file on which the tool is invoked, based on the
switch-related attributes defined in the package.
In particular, the switches
that each of these packages contributes for a given file f comprise:
Switches (f),
if it is specified in the package for the given file,
Default_Switches ("Ada"),
if it is specified in the package.
If neither of these attributes is defined in the package, then the package does not contribute any switches for the given file.
When gnatmake is invoked on a file, the switches comprise
two sets, in the following order: those contributed for the file
by the Builder package;
and the switches passed on the command line.
When gnatmake invokes a tool (compiler, binder, linker) on a file,
the switches passed to the tool comprise three sets,
in the following order:
Builder package in the project file supplied on the command line;
The term applicable switches reflects the fact that
gnatmake switches may or may not be passed to individual
tools, depending on the individual switch.
gnatmake may invoke the compiler on source files from different
projects. The Project Manager will use the appropriate project file to
determine the Compiler package for each source file being compiled.
Likewise for the Binder and Linker packages.
As an example, consider the following package in a project file:
project Proj1 is
package Compiler is
for Default_Switches ("Ada")
use ("-g");
for Switches ("a.adb")
use ("-O1");
for Switches ("b.adb")
use ("-O2",
"-gnaty");
end Compiler;
end Proj1;
|
If gnatmake is invoked with this project file, and it needs to
compile, say, the files `a.adb', `b.adb', and `c.adb', then
`a.adb' will be compiled with the switch
`-O1',
`b.adb' with switches
`-O2'
and `-gnaty',
and `c.adb' with `-g'.
The following example illustrates the ordering of the switches contributed by different packages:
project Proj2 is
package Builder is
for Switches ("main.adb")
use ("-g",
"-O1",
"-f");
end Builder;
package Compiler is
for Switches ("main.adb")
use ("-O2");
end Compiler;
end Proj2;
|
If you issue the command:
gnatmake -Pproj2 -O0 main |
then the compiler will be invoked on `main.adb' with the following sequence of switches
-g -O1 -O2 -O0 |
with the last `-O' switch having precedence over the earlier ones; several other switches (such as `-c') are added implicitly.
The switches
`-g'
and `-O1' are contributed by package
Builder, `-O2' is contributed
by the package Compiler
and `-O0' comes from the command line.
The `-g'
switch will also be passed in the invocation of
Gnatlink.
A final example illustrates switch contributions from packages in different project files:
project Proj3 is
for Source_Files use ("pack.ads", "pack.adb");
package Compiler is
for Default_Switches ("Ada")
use ("-gnata");
end Compiler;
end Proj3;
with "Proj3";
project Proj4 is
for Source_Files use ("foo_main.adb", "bar_main.adb");
package Builder is
for Switches ("foo_main.adb")
use ("-s",
"-g");
end Builder;
end Proj4;
-- Ada source file:
with Pack;
procedure Foo_Main is
...
end Foo_Main;
|
If the command is
gnatmake -PProj4 foo_main.adb -cargs -gnato |
then the switches passed to the compiler for `foo_main.adb' are
`-g' (contributed by the package Proj4.Builder) and
`-gnato' (passed on the command line).
When the imported package Pack is compiled, the switches used
are `-g' from Proj4.Builder,
`-gnata' (contributed from package Proj3.Compiler,
and `-gnato' from the command line.
When using gnatmake with project files, some switches or
arguments may be expressed as relative paths. As the working directory where
compilation occurs may change, these relative paths are converted to absolute
paths. For the switches found in a project file, the relative paths
are relative to the project file directory, for the switches on the command
line, they are relative to the directory where gnatmake is invoked.
The switches for which this occurs are:
-I,
-A,
-L,
-aO,
-aL,
-aI, as well as all arguments that are not switches (arguments to
switch
-o, object files specified in package Linker or after
-largs on the command line). The exception to this rule is the switch
--RTS= for which a relative path argument is never converted.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When using gnatmake with project files, if there exists a file
`gnat.adc' that contains configuration pragmas, this file will be
ignored.
Configuration pragmas can be defined by means of the following attributes in
project files: Global_Configuration_Pragmas in package Builder
and Local_Configuration_Pragmas in package Compiler.
Both these attributes are single string attributes. Their values is the path name of a file containing configuration pragmas. If a path name is relative, then it is relative to the project directory of the project file where the attribute is defined.
When compiling a source, the configuration pragmas used are, in order,
those listed in the file designated by attribute
Global_Configuration_Pragmas in package Builder of the main
project file, if it is specified, and those listed in the file designated by
attribute Local_Configuration_Pragmas in package Compiler of
the project file of the source, if it exists.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When using a project file, you can invoke gnatmake
with one or several main subprograms, by specifying their source files on the
command line.
gnatmake -Pprj main1.adb main2.adb main3.adb |
Each of these needs to be a source file of the same project, except when the switch -u is used.
When -u is not used, all the mains need to be sources of the
same project, one of the project in the tree rooted at the project specified
on the command line. The package Builder of this common project, the
"main project" is the one that is considered by gnatmake.
When -u is used, the specified source files may be in projects
imported directly or indirectly by the project specified on the command line.
Note that if such a source file is not part of the project specified on the
command line, the switches found in package Builder of the
project specified on the command line, if any, that are transmitted
to the compiler will still be used, not those found in the project file of
the source file.
When using a project file, you can also invoke gnatmake without
explicitly specifying any main, and the effect depends on whether you have
defined the Main attribute. This attribute has a string list value,
where each element in the list is the name of a source file (the file
extension is optional) that contains a unit that can be a main subprogram.
If the Main attribute is defined in a project file as a non-empty
string list and the switch `-u' is not used on the command
line, then invoking gnatmake with this project file but without any
main on the command line is equivalent to invoking gnatmake with all
the file names in the Main attribute on the command line.
Example:
project Prj is
for Main use ("main1.adb", "main2.adb", "main3.adb");
end Prj;
|
With this project file, "gnatmake -Pprj"
is equivalent to
"gnatmake -Pprj main1.adb main2.adb main3.adb".
When the project attribute Main is not specified, or is specified
as an empty string list, or when the switch `-u' is used on the command
line, then invoking gnatmake with no main on the command line will
result in all immediate sources of the project file being checked, and
potentially recompiled. Depending on the presence of the switch `-u',
sources from other project files on which the immediate sources of the main
project file depend are also checked and potentially recompiled. In other
words, the `-u' switch is applied to all of the immediate sources of the
main project file.
When no main is specified on the command line and attribute Main exists
and includes several mains, or when several mains are specified on the
command line, the default switches in package Builder will
be used for all mains, even if there are specific switches
specified for one or several mains.
But the switches from package Binder or Linker will be
the specific switches for each main, if they are specified.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When gnatmake is invoked with a main project file that is a library
project file, it is not allowed to specify one or more mains on the command
line.
When a library project file is specified, switches -b and -l have special meanings.
gnatmake that gnatbind should be invoked for the
library.
gnatmake that the binder generated file should be compiled
(in the case of a stand-alone library) and that the library should be built.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A number of GNAT tools, other than gnatmake
can benefit from project files:
(gnatbind,
gnatcheck,
gnatclean,
gnatelim,
gnatfind,
gnatlink,
gnatls,
gnatmetric,
gnatpp,
gnatstub,
and gnatxref). However, none of these tools can be invoked
directly with a project file switch (`-P').
They must be invoked through the gnat driver.
The gnat driver is a wrapper that accepts a number of commands and
calls the corresponding tool. It was designed initially for VMS platforms (to
convert VMS qualifiers to Unix-style switches), but it is now available on all
GNAT platforms.
On non-VMS platforms, the gnat driver accepts the following commands
(case insensitive):
gnatbind
gnatchop
gnatclean
gnatelim
gnatfind
gnatkr
gnatlink
gnatls
gnatmake
gnatname
gnatprep
gnatpp
gnatmetric
gnatstub
gnatxref
(note that the compiler is invoked using the command
gnatmake -f -u -c).
On non-VMS platforms, between gnat and the command, two
special switches may be used:
-v to display the invocation of the tool.
-dn to prevent the gnat driver from removing
the temporary files it has created. These temporary files are
configuration files and temporary file list files.
The command may be followed by switches and arguments for the invoked tool.
gnat bind -C main.ali gnat ls -a main gnat chop foo.txt |
Switches may also be put in text files, one switch per line, and the text files may be specified with their path name preceded by '@'.
gnat bind @args.txt main.ali |
In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK, METRIC, PP or PRETTY, STUB and XREF, the project file related switches (`-P', `-X' and `-vPx') may be used in addition to the switches of the invoking tool.
When GNAT PP or GNAT PRETTY is used with a project file, but with no source
specified on the command line, it invokes gnatpp with all
the immediate sources of the specified project file.
When GNAT METRIC is used with a project file, but with no source
specified on the command line, it invokes gnatmetric
with all the immediate sources of the specified project file and with
`-d' with the parameter pointing to the object directory
of the project.
In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with a project file, no source is specified on the command line and switch -U is specified on the command line, then the underlying tool (gnatpp or gnatmetric) is invoked for all sources of all projects, not only for the immediate sources of the main project. (-U stands for Universal or Union of the project files of the project tree)
For each of the following commands, there is optionally a corresponding package in the main project.
Binder for command BIND (invoking gnatbind)
Check for command CHECK (invoking
gnatcheck)
Compiler for command COMP or COMPILE (invoking the compiler)
Cross_Reference for command XREF (invoking
gnatxref)
Eliminate for command ELIM (invoking
gnatelim)
Finder for command FIND (invoking gnatfind)
Gnatls for command LS or LIST (invoking gnatls)
Gnatstub for command STUB
(invoking gnatstub)
Linker for command LINK (invoking gnatlink)
Check for command CHECK
(invoking gnatcheck)
Metrics for command METRIC
(invoking gnatmetric)
Pretty_Printer for command PP or PRETTY
(invoking gnatpp)
Package Gnatls has a unique attribute Switches,
a simple variable with a string list value. It contains switches
for the invocation of gnatls.
project Proj1 is
package gnatls is
for Switches
use ("-a",
"-v");
end gnatls;
end Proj1;
|
All other packages have two attribute Switches and
Default_Switches.
Switches is an indexed attribute, indexed by the
source file name, that has a string list value: the switches to be
used when the tool corresponding to the package is invoked for the specific
source file.
Default_Switches is an attribute,
indexed by the programming language that has a string list value.
Default_Switches ("Ada") contains the
switches for the invocation of the tool corresponding
to the package, except if a specific Switches attribute
is specified for the source file.
project Proj is
for Source_Dirs use ("**");
package gnatls is
for Switches use
("-a",
"-v");
end gnatls;
package Compiler is
for Default_Switches ("Ada")
use ("-gnatv",
"-gnatwa");
end Binder;
package Binder is
for Default_Switches ("Ada")
use ("-C",
"-e");
end Binder;
package Linker is
for Default_Switches ("Ada")
use ("-C");
for Switches ("main.adb")
use ("-C",
"-v",
"-v");
end Linker;
package Finder is
for Default_Switches ("Ada")
use ("-a",
"-f");
end Finder;
package Cross_Reference is
for Default_Switches ("Ada")
use ("-a",
"-f",
"-d",
"-u");
end Cross_Reference;
end Proj;
|
With the above project file, commands such as
gnat comp -Pproj main gnat ls -Pproj main gnat xref -Pproj main gnat bind -Pproj main.ali gnat link -Pproj main.ali |
will set up the environment properly and invoke the tool with the switches
found in the package corresponding to the tool:
Default_Switches ("Ada") for all tools,
except Switches ("main.adb")
for gnatlink.
It is also possible to invoke some of the tools,
(gnatcheck,
gnatmetric,
and gnatpp)
on a set of project units thanks to the combination of the switches
`-P', `-U' and possibly the main unit when one is interested
in its closure. For instance,
gnat metric -Pproj |
will compute the metrics for all the immediate units of project
proj.
gnat metric -Pproj -U |
will compute the metrics for all the units of the closure of projects
rooted at proj.
gnat metric -Pproj -U main_unit |
will compute the metrics for the closure of units rooted at
main_unit. This last possibility relies implicitly
on gnatbind's option `-R'. But if the argument files for the
tool invoked by the gnat driver are explicitly specified
either directly or through the tool `-files' option, then the tool
is called only for these explicitly specified files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
See the appropriate manuals for more details. These environments will store a number of settings in the project itself, when they are meant to be shared by the whole team working on the project. Here are the attributes defined in the package IDE in projects.
Remote_Host
Program_Host
Communication_Protocol
"wtx" or "vxworks".
Compiler_Command
Compiler_Command ("Ada") is expected to be compatible with
gnatmake, in particular in the handling of switches.
Debugger_Command
Default_Switches
Gnatlist
gnatls utility to be used to retrieve information about the
predefined path; e.g., "gnatls", "powerpc-wrs-vxworks-gnatls".
VCS_Kind
Gnat
gnat utility to be used when executing various tools from
GPS, in particular "gnat pp", "gnat stub",...
VCS_File_Check
VCS_Log_Check
VCS_Repository_Root
URL
as specified to check-out the working copy of the repository.
VCS_Patch_Root
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |