Skip to content

R
riscv-gcc-1
Commit b671e31b by Vincent Celier Committed by Arnaud Charlet
Options

gnat_ugn.texi, [...]: Move chapter "Tools Supporting Project Files" from… 

gnat_ugn.texi, [...]: Move chapter "Tools Supporting Project Files" from projects.texi to gnat_ugn.texi.

2013-04-11  Vincent Celier  <celier@adacore.com>

	* gnat_ugn.texi, projects.texi: Move chapter "Tools Supporting Project
	Files" from projects.texi to gnat_ugn.texi.

From-SVN: r197755
parent ddd38fc1
Showing with 970 additions and 963 deletions
gcc/ada/ChangeLog
2013-04-11 Vincent Celier <celier@adacore.com>
* gnat_ugn.texi, projects.texi: Move chapter "Tools Supporting Project
Files" from projects.texi to gnat_ugn.texi.
2013-04-11 Arnaud Charlet <charlet@adacore.com>
* gcc-interface/Make-lang.in: Update dependencies.
......
gcc/ada/gnat_ugn.texi
......@@ -12491,6 +12491,887 @@ are used in this example.
@include projects.texi
@c ---------------------------------------------
@c Tools Supporting Project Files
@c ---------------------------------------------
@node Tools Supporting Project Files
@chapter Tools Supporting Project Files
@noindent
@menu
* gnatmake and Project Files::
* The GNAT Driver and Project Files::
* The Development Environments::
@end menu
@c ---------------------------------------------
@node gnatmake and Project Files
@section gnatmake and Project Files
@c ---------------------------------------------
@noindent
This section covers several topics related to @command{gnatmake} and
project files: defining ^switches^switches^ for @command{gnatmake}
and for the tools that it invokes; specifying configuration pragmas;
the use of the @code{Main} attribute; building and rebuilding library project
files.
@menu
* Switches Related to Project Files::
* Switches and Project Files::
* Specifying Configuration Pragmas::
* Project Files and Main Subprograms::
* Library Project Files::
@end menu
@c ---------------------------------------------
@node Switches Related to Project Files
@subsection Switches Related to Project Files
@c ---------------------------------------------
@noindent
The following switches are used by GNAT tools that support project files:
@table @option
@item ^-P^/PROJECT_FILE=^@var{project}
@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
if any, and using the external references indicated
by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
@ifclear vms
There may zero, one or more spaces between @option{-P} and @var{project}.
@end ifclear
There must be only one @option{^-P^/PROJECT_FILE^} 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
@option{^-P^/PROJECT_FILE^},
@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
Indicates that external variable @var{name} has the value @var{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
@ifclear vms
If @var{name} or @var{value} includes a space, then @var{name=value} should be
put between quotes.
@smallexample
-XOS=NT
-X"user=John Doe"
@end smallexample
@end ifclear
Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
@var{name}, only the last one is used.
An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
takes precedence over the value of the same name in the environment.
@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
Indicates the verbosity of the parsing of GNAT project files.
@ifclear vms
@option{-vP0} means Default;
@option{-vP1} means Medium;
@option{-vP2} means High.
@end ifclear
@ifset vms
There are three possible options for this qualifier: DEFAULT, MEDIUM and
HIGH.
@end ifset
The default is ^Default^DEFAULT^: no output for syntactically correct
project files.
If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
only the last one is used.
@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
Add directory <dir> at the beginning of the project search path, in order,
after the current working directory.
@ifclear vms
@item -eL
@cindex @option{-eL} (any project-aware tool)
Follow all symbolic links when processing project files.
@end ifclear
@item ^--subdirs^/SUBDIRS^=<subdir>
@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
This switch is recognized by @command{gnatmake} and @command{gnatclean}. It
indicate that the real directories (except the source directories) are the
subdirectories <subdir> of the directories specified in the project files.
This applies in particular to object directories, library directories and
exec directories. If the subdirectories do not exist, they are created
automatically.
@end table
@c ---------------------------------------------
@node Switches and Project Files
@subsection Switches and Project Files
@c ---------------------------------------------
@noindent
@ifset vms
It is not currently possible to specify VMS style qualifiers in the project
files; only Unix style ^switches^switches^ may be specified.
@end ifset
For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
attribute, a @code{Switches} attribute, or both;
as their names imply, these ^switch^switch^-related
attributes affect the ^switches^switches^ that are used for each of these GNAT
components when
@command{gnatmake} is invoked. As will be explained below, these
component-specific ^switches^switches^ precede
the ^switches^switches^ provided on the @command{gnatmake} command line.
The @code{^Default_Switches^Default_Switches^} attribute is an attribute
indexed by language name (case insensitive) whose value is a string list.
For example:
@smallexample @c projectfile
@group
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnaty^-gnaty^",
"^-v^-v^");
end Compiler;
@end group
@end smallexample
@noindent
The @code{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:
@smallexample @c projectfile
@group
package Builder is
for Switches ("main1.adb")
use ("^-O2^-O2^");
for Switches ("main2.adb")
use ("^-g^-g^");
end Builder;
@end group
@end smallexample
@noindent
For the @code{Builder} package, the file names must designate source files
for main subprograms. For the @code{Binder} and @code{Linker} packages, the
file names must designate @file{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 (@command{gnatmake}, the compiler, the
binder, and the linker), the corresponding package @dfn{contributes} a set of
^switches^switches^ for each file on which the tool is invoked, based on the
^switch^switch^-related attributes defined in the package.
In particular, the ^switches^switches^
that each of these packages contributes for a given file @var{f} comprise:
@itemize @bullet
@item the value of attribute @code{Switches (@var{f})},
if it is specified in the package for the given file,
@item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
if it is specified in the package.
@end itemize
@noindent
If neither of these attributes is defined in the package, then the package does
not contribute any ^switches^switches^ for the given file.
When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
two sets, in the following order: those contributed for the file
by the @code{Builder} package;
and the switches passed on the command line.
When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
the ^switches^switches^ passed to the tool comprise three sets,
in the following order:
@enumerate
@item
the applicable ^switches^switches^ contributed for the file
by the @code{Builder} package in the project file supplied on the command line;
@item
those contributed for the file by the package (in the relevant project file --
see below) corresponding to the tool; and
@item
the applicable switches passed on the command line.
@end enumerate
The term @emph{applicable ^switches^switches^} reflects the fact that
@command{gnatmake} ^switches^switches^ may or may not be passed to individual
tools, depending on the individual ^switch^switch^.
@command{gnatmake} may invoke the compiler on source files from different
projects. The Project Manager will use the appropriate project file to
determine the @code{Compiler} package for each source file being compiled.
Likewise for the @code{Binder} and @code{Linker} packages.
As an example, consider the following package in a project file:
@smallexample @c projectfile
@group
project Proj1 is
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-g^-g^");
for Switches ("a.adb")
use ("^-O1^-O1^");
for Switches ("b.adb")
use ("^-O2^-O2^",
"^-gnaty^-gnaty^");
end Compiler;
end Proj1;
@end group
@end smallexample
@noindent
If @command{gnatmake} is invoked with this project file, and it needs to
compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
@file{a.adb} will be compiled with the ^switch^switch^
@option{^-O1^-O1^},
@file{b.adb} with ^switches^switches^
@option{^-O2^-O2^}
and @option{^-gnaty^-gnaty^},
and @file{c.adb} with @option{^-g^-g^}.
The following example illustrates the ordering of the ^switches^switches^
contributed by different packages:
@smallexample @c projectfile
@group
project Proj2 is
package Builder is
for Switches ("main.adb")
use ("^-g^-g^",
"^-O1^-)1^",
"^-f^-f^");
end Builder;
@end group
@group
package Compiler is
for Switches ("main.adb")
use ("^-O2^-O2^");
end Compiler;
end Proj2;
@end group
@end smallexample
@noindent
If you issue the command:
@smallexample
gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
@end smallexample
@noindent
then the compiler will be invoked on @file{main.adb} with the following
sequence of ^switches^switches^
@smallexample
^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
@end smallexample
@noindent
with the last @option{^-O^-O^}
^switch^switch^ having precedence over the earlier ones;
several other ^switches^switches^
(such as @option{^-c^-c^}) are added implicitly.
The ^switches^switches^
@option{^-g^-g^}
and @option{^-O1^-O1^} are contributed by package
@code{Builder}, @option{^-O2^-O2^} is contributed
by the package @code{Compiler}
and @option{^-O0^-O0^} comes from the command line.
The @option{^-g^-g^}
^switch^switch^ will also be passed in the invocation of
@command{Gnatlink.}
A final example illustrates switch contributions from packages in different
project files:
@smallexample @c projectfile
@group
project Proj3 is
for Source_Files use ("pack.ads", "pack.adb");
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnata^-gnata^");
end Compiler;
end Proj3;
@end group
@group
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^-s^",
"^-g^-g^");
end Builder;
end Proj4;
@end group
@group
-- Ada source file:
with Pack;
procedure Foo_Main is
@dots{}
end Foo_Main;
@end group
@end smallexample
@noindent
If the command is
@smallexample
gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
@end smallexample
@noindent
then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
@option{^-gnato^-gnato^} (passed on the command line).
When the imported package @code{Pack} is compiled, the ^switches^switches^ used
are @option{^-g^-g^} from @code{Proj4.Builder},
@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
and @option{^-gnato^-gnato^} from the command line.
When using @command{gnatmake} with project files, some ^switches^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^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 @command{gnatmake} is invoked.
The ^switches^switches^ for which this occurs are:
^-I^-I^,
^-A^-A^,
^-L^-L^,
^-aO^-aO^,
^-aL^-aL^,
^-aI^-aI^, as well as all arguments that are not switches (arguments to
^switch^switch^
^-o^-o^, object files specified in package @code{Linker} or after
-largs on the command line). The exception to this rule is the ^switch^switch^
^--RTS=^--RTS=^ for which a relative path argument is never converted.
@c ---------------------------------------------
@node Specifying Configuration Pragmas
@subsection Specifying Configuration Pragmas
@c ---------------------------------------------
@noindent
When using @command{gnatmake} with project files, if there exists a file
@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: @code{Global_Configuration_Pragmas} in package @code{Builder}
and @code{Local_Configuration_Pragmas} in package @code{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
@code{Global_Configuration_Pragmas} in package @code{Builder} of the main
project file, if it is specified, and those listed in the file designated by
attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
the project file of the source, if it exists.
@c ---------------------------------------------
@node Project Files and Main Subprograms
@subsection Project Files and Main Subprograms
@c ---------------------------------------------
@noindent
When using a project file, you can invoke @command{gnatmake}
with one or several main subprograms, by specifying their source files on the
command line.
@smallexample
gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
@end smallexample
@noindent
Each of these needs to be a source file of the same project, except
when the switch ^-u^/UNIQUE^ is used.
When ^-u^/UNIQUE^ 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 @code{Builder} of this common project, the
"main project" is the one that is considered by @command{gnatmake}.
When ^-u^/UNIQUE^ 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^switches^ found in package @code{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 @command{gnatmake} without
explicitly specifying any main, and the effect depends on whether you have
defined the @code{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 @code{Main} attribute is defined in a project file as a non-empty
string list and the switch @option{^-u^/UNIQUE^} is not used on the command
line, then invoking @command{gnatmake} with this project file but without any
main on the command line is equivalent to invoking @command{gnatmake} with all
the file names in the @code{Main} attribute on the command line.
Example:
@smallexample @c projectfile
@group
project Prj is
for Main use ("main1.adb", "main2.adb", "main3.adb");
end Prj;
@end group
@end smallexample
@noindent
With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
is equivalent to
@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
When the project attribute @code{Main} is not specified, or is specified
as an empty string list, or when the switch @option{-u} is used on the command
line, then invoking @command{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 @option{-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 @option{-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 @code{Main} exists
and includes several mains, or when several mains are specified on the
command line, the default ^switches^switches^ in package @code{Builder} will
be used for all mains, even if there are specific ^switches^switches^
specified for one or several mains.
But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
the specific ^switches^switches^ for each main, if they are specified.
@c ---------------------------------------------
@node Library Project Files
@subsection Library Project Files
@c ---------------------------------------------
@noindent
When @command{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^/ACTION=BIND^ and
^-l^/ACTION=LINK^ have special meanings.
@itemize @bullet
@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
to @command{gnatmake} that @command{gnatbind} should be invoked for the
library.
@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
to @command{gnatmake} that the binder generated file should be compiled
(in the case of a stand-alone library) and that the library should be built.
@end itemize
@c ---------------------------------------------
@node The GNAT Driver and Project Files
@section The GNAT Driver and Project Files
@c ---------------------------------------------
@noindent
A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
can benefit from project files:
(@command{^gnatbind^gnatbind^},
@command{^gnatcheck^gnatcheck^},
@command{^gnatclean^gnatclean^},
@command{^gnatelim^gnatelim^},
@command{^gnatfind^gnatfind^},
@command{^gnatlink^gnatlink^},
@command{^gnatls^gnatls^},
@command{^gnatmetric^gnatmetric^},
@command{^gnatpp^gnatpp^},
@command{^gnatstub^gnatstub^},
and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
They must be invoked through the @command{gnat} driver.
The @command{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 @command{gnat} driver accepts the following commands
(case insensitive):
@itemize @bullet
@item BIND to invoke @command{^gnatbind^gnatbind^}
@item CHOP to invoke @command{^gnatchop^gnatchop^}
@item CLEAN to invoke @command{^gnatclean^gnatclean^}
@item COMP or COMPILE to invoke the compiler
@item ELIM to invoke @command{^gnatelim^gnatelim^}
@item FIND to invoke @command{^gnatfind^gnatfind^}
@item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
@item LINK to invoke @command{^gnatlink^gnatlink^}
@item LS or LIST to invoke @command{^gnatls^gnatls^}
@item MAKE to invoke @command{^gnatmake^gnatmake^}
@item NAME to invoke @command{^gnatname^gnatname^}
@item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
@item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
@item METRIC to invoke @command{^gnatmetric^gnatmetric^}
@item STUB to invoke @command{^gnatstub^gnatstub^}
@item XREF to invoke @command{^gnatxref^gnatxref^}
@end itemize
@noindent
(note that the compiler is invoked using the command
@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
On non-VMS platforms, between @command{gnat} and the command, two
special switches may be used:
@itemize @bullet
@item @command{-v} to display the invocation of the tool.
@item @command{-dn} to prevent the @command{gnat} driver from removing
the temporary files it has created. These temporary files are
configuration files and temporary file list files.
@end itemize
@noindent
The command may be followed by switches and arguments for the invoked
tool.
@smallexample
gnat bind -C main.ali
gnat ls -a main
gnat chop foo.txt
@end smallexample
@noindent
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 '@@'.
@smallexample
gnat bind @@args.txt main.ali
@end smallexample
@noindent
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
(@option{^-P^/PROJECT_FILE^},
@option{^-X^/EXTERNAL_REFERENCE^} and
@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) 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 @command{^gnatpp^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 @command{^gnatmetric^gnatmetric^}
with all the immediate sources of the specified project file and with
@option{^-d^/DIRECTORY^} 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^/ALL_PROJECTS^ is specified on the command line, then
the underlying tool (^gnatpp^gnatpp^ or
^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
not only for the immediate sources of the main project.
@ifclear vms
(-U stands for Universal or Union of the project files of the project tree)
@end ifclear
For each of the following commands, there is optionally a corresponding
package in the main project.
@itemize @bullet
@item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
@item package @code{Check} for command CHECK (invoking
@code{^gnatcheck^gnatcheck^})
@item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
@item package @code{Cross_Reference} for command XREF (invoking
@code{^gnatxref^gnatxref^})
@item package @code{Eliminate} for command ELIM (invoking
@code{^gnatelim^gnatelim^})
@item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
@item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
@item package @code{Gnatstub} for command STUB
(invoking @code{^gnatstub^gnatstub^})
@item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
@item package @code{Check} for command CHECK
(invoking @code{^gnatcheck^gnatcheck^})
@item package @code{Metrics} for command METRIC
(invoking @code{^gnatmetric^gnatmetric^})
@item package @code{Pretty_Printer} for command PP or PRETTY
(invoking @code{^gnatpp^gnatpp^})
@end itemize
@noindent
Package @code{Gnatls} has a unique attribute @code{Switches},
a simple variable with a string list value. It contains ^switches^switches^
for the invocation of @code{^gnatls^gnatls^}.
@smallexample @c projectfile
@group
project Proj1 is
package gnatls is
for Switches
use ("^-a^-a^",
"^-v^-v^");
end gnatls;
end Proj1;
@end group
@end smallexample
@noindent
All other packages have two attribute @code{Switches} and
@code{^Default_Switches^Default_Switches^}.
@code{Switches} is an indexed attribute, indexed by the
source file name, that has a string list value: the ^switches^switches^ to be
used when the tool corresponding to the package is invoked for the specific
source file.
@code{^Default_Switches^Default_Switches^} is an attribute,
indexed by the programming language that has a string list value.
@code{^Default_Switches^Default_Switches^ ("Ada")} contains the
^switches^switches^ for the invocation of the tool corresponding
to the package, except if a specific @code{Switches} attribute
is specified for the source file.
@smallexample @c projectfile
@group
project Proj is
for Source_Dirs use ("**");
package gnatls is
for Switches use
("^-a^-a^",
"^-v^-v^");
end gnatls;
@end group
@group
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnatv^-gnatv^",
"^-gnatwa^-gnatwa^");
end Binder;
@end group
@group
package Binder is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-C^-C^",
"^-e^-e^");
end Binder;
@end group
@group
package Linker is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-C^-C^");
for Switches ("main.adb")
use ("^-C^-C^",
"^-v^-v^",
"^-v^-v^");
end Linker;
@end group
@group
package Finder is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-a^-a^",
"^-f^-f^");
end Finder;
@end group
@group
package Cross_Reference is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-a^-a^",
"^-f^-f^",
"^-d^-d^",
"^-u^-u^");
end Cross_Reference;
end Proj;
@end group
@end smallexample
@noindent
With the above project file, commands such as
@smallexample
^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
@end smallexample
@noindent
will set up the environment properly and invoke the tool with the switches
found in the package corresponding to the tool:
@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
except @code{Switches ("main.adb")}
for @code{^gnatlink^gnatlink^}.
It is also possible to invoke some of the tools,
(@code{^gnatcheck^gnatcheck^},
@code{^gnatmetric^gnatmetric^},
and @code{^gnatpp^gnatpp^})
on a set of project units thanks to the combination of the switches
@option{-P}, @option{-U} and possibly the main unit when one is interested
in its closure. For instance,
@smallexample
gnat metric -Pproj
@end smallexample
@noindent
will compute the metrics for all the immediate units of project
@code{proj}.
@smallexample
gnat metric -Pproj -U
@end smallexample
@noindent
will compute the metrics for all the units of the closure of projects
rooted at @code{proj}.
@smallexample
gnat metric -Pproj -U main_unit
@end smallexample
@noindent
will compute the metrics for the closure of units rooted at
@code{main_unit}. This last possibility relies implicitly
on @command{gnatbind}'s option @option{-R}. But if the argument files for the
tool invoked by the @command{gnat} driver are explicitly specified
either directly or through the tool @option{-files} option, then the tool
is called only for these explicitly specified files.
@c ---------------------------------------------
@node The Development Environments
@section The Development Environments
@c ---------------------------------------------
@noindent
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 @b{IDE} in projects.
@table @code
@item Remote_Host
This is a simple attribute. Its value is a string that designates the remote
host in a cross-compilation environment, to be used for remote compilation and
debugging. This field should not be specified when running on the local
machine.
@item Program_Host
This is a simple attribute. Its value is a string that specifies the
name of IP address of the embedded target in a cross-compilation environment,
on which the program should execute.
@item Communication_Protocol
This is a simple string attribute. Its value is the name of the protocol
to use to communicate with the target in a cross-compilation environment,
e.g.@: @code{"wtx"} or @code{"vxworks"}.
@item Compiler_Command
This is an indexed attribute, whose domain is a language name. Its
value is string that denotes the command to be used to invoke the compiler.
The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
@command{gnatmake}, in particular in the handling of switches.
@item Debugger_Command
This is simple attribute, Its value is a string that specifies the name of
the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
@item Default_Switches
This is an indexed attribute. Its indexes are the name of the
external tools that the GNAT Programming System (GPS) is supporting. Its
value is a list of switches to use when invoking that tool.
@item Gnatlist
This is a simple attribute. Its value is a string that specifies the name
of the @command{gnatls} utility to be used to retrieve information about the
predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
@item VCS_Kind
This is a simple attribute. Its value is a string used to specify the
Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
ClearCase or Perforce.
@item Gnat
This is a simple attribute. Its value is a string that specifies the name
of the @command{gnat} utility to be used when executing various tools from
GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
@item VCS_File_Check
This is a simple attribute. Its value is a string that specifies the
command used by the VCS to check the validity of a file, either
when the user explicitly asks for a check, or as a sanity check before
doing the check-in.
@item VCS_Log_Check
This is a simple attribute. Its value is a string that specifies
the command used by the VCS to check the validity of a log file.
@item VCS_Repository_Root
The VCS repository root path. This is used to create tags or branches
of the repository. For subversion the value should be the @code{URL}
as specified to check-out the working copy of the repository.
@item VCS_Patch_Root
The local root directory to use for building patch file. All patch chunks
will be relative to this path. The root project directory is used if
this value is not defined.
@end table
@c *****************************************
@c * Cross-referencing tools
@c *****************************************
gcc/ada/projects.texi
......@@ -82,7 +82,6 @@ the information on the command line itself). They share common switches
to control the loading of the project (in particular
@option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
@xref{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
......@@ -875,8 +874,7 @@ 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
(@pxref{Specifying Configuration Pragmas}).
paragraph. You can however specify other configuration pragmas.
The following attributes can be defined in package @code{Naming}:
......@@ -1532,13 +1530,13 @@ The second parameter to @code{external} is optional, and is the default
value to use if "mode" is not set from the command line or the environment.
In order to set the switches according to the different scenarios, other
constructs have to be introduced such as typed variables and case statements.
constructs have to be introduced such as typed variables and case constructions.
@cindex typed variable
@cindex case statement
@cindex case construction
A @b{typed variable} is a variable that
can take only a limited number of values, similar to an enumeration in Ada.
Such a variable can then be used in a @b{case statement} and create conditional
Such a variable can then be used in a @b{case construction} and create conditional
sections in the project. The following example shows how this can be done:
@smallexample @c projectfile
......@@ -1565,7 +1563,7 @@ project is considered as invalid.
The @code{Mode} variable is initialized with an external value
defaulting to @code{"debug"}. This default could be omitted and that would
force the user to define the value. Finally, we can use a case statement to set the
force the user to define the value. Finally, we can use a case construction to set the
switches depending on the scenario the user has chosen.
Most aspects of the projects can depend on scenarios. The notable exception
......@@ -2914,8 +2912,8 @@ attributes.
* External Values::
* Typed String Declaration::
* Variables::
* Case Constructions::
* Attributes::
* Case Statements::
@end menu
@c ---------------------------------------------
......@@ -3122,6 +3120,9 @@ The following packages are currently supported in project files
@code{Builder}. The first string should always be @code{-rules} to specify
that all the other options belong to the @code{-rules} section of the
parameters to @command{gnatcheck}.
@item Clean
This package specifies the options used when cleaning a project or a project
tree using the tools @command{gnatclean} or @command{gprclean}.
@item Compiler
This package specifies the compilation options used by the compiler for
each languages. @xref{Tools Options in Project Files}.
......@@ -3151,17 +3152,12 @@ The following packages are currently supported in project files
@item IDE
This package specifies the options used when starting an integrated
development environment, for instance @command{GPS} or @command{Gnatbench}.
@xref{The Development Environments}.
@item Install
This package specifies the options used when installing a project
with @command{gprinstall}. @xref{Installation}.
@item Linker
This package specifies the options used by the linker.
@xref{Main Subprograms}.
@item Makefile
@cindex Makefile package in projects
This package is used by the GPS plugin Makefile.py. See the documentation
in that plugin (from GPS: /Tools/Plug-ins).
@item Metrics
This package specifies the options used when calling the tool
@command{gnatmetric} via the @command{gnat} driver. Its attributes
......@@ -3178,6 +3174,9 @@ The following packages are currently supported in project files
@command{gnatpp} via the @command{gnat} driver. Its attributes
@b{Default_Switches} and @b{Switches} have the same semantics as for the
package @code{Builder}.
@item Remote
This package is used by @command{gprbuild} to describe how distributed
compilation should be done.
@item Stack
This package specifies the options used when calling the tool
@command{gnatstack} via the @command{gnat} driver. Its attributes
......@@ -3430,7 +3429,7 @@ Here is an example of a string type declaration:
Variables of a string type are called @b{typed variables}; all other
variables are called @b{untyped variables}. Typed variables are
particularly useful in @code{case} constructions, to support conditional
attribute declarations. (@pxref{Case Statements}).
attribute declarations. (@pxref{Case Constructions}).
A string type may be referenced by its name if it has been declared in the same
project file, or by an expanded name whose prefix is the name of the project
......@@ -3452,7 +3451,7 @@ string ("").
A @b{typed} variable can be used as part of a @b{case} expression to
compute the value, but it can only be declared once in the project file,
so that all case statements see the same value for the variable. This
so that all case constructions see the same value for the variable. This
provides more consistency and makes the project easier to understand.
The syntax for its declaration is identical to the Ada syntax for an
object declaration. In effect, a typed variable acts as a constant.
......@@ -3514,6 +3513,75 @@ A @b{context} may be one of the following:
@end itemize
@c ---------------------------------------------
@node Case Constructions
@subsection Case Constructions
@c ---------------------------------------------
@noindent
A @b{case} statement is used in a project file to effect conditional
behavior. Through this statement, you can set the value of attributes
and variables depending on the value previously assigned to a typed
variable.
All choices in a choice list must be distinct. Unlike Ada, the choice
lists of all alternatives do not need to include all values of the type.
An @code{others} choice must appear last in the list of alternatives.
The syntax of a @code{case} construction is based on the Ada case statement
(although the @code{null} statement for empty alternatives is optional).
The case expression must be a typed string variable, whose value is often
given by an external reference (@pxref{External Values}).
Each alternative starts with the reserved word @code{when}, either a list of
literal strings separated by the @code{"|"} character or the reserved word
@code{others}, and the @code{"=>"} token.
Each literal string must belong to the string type that is the type of the
case variable.
After each @code{=>}, there are zero or more statements. The only
statements allowed in a case construction are other case constructions,
attribute declarations and variable declarations. String type declarations and
package declarations are not allowed. Variable declarations are restricted to
variables that have already been declared before the case construction.
@smallexample
case_statement ::=
@i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
case_item ::=
@i{when} discrete_choice_list =>
@{case_statement
| attribute_declaration
| variable_declaration
| empty_declaration@}
discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
@end smallexample
@noindent
Here is a typical example:
@smallexample @c projectfile
@group
project MyProj is
type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
OS : OS_Type := external ("OS", "GNU/Linux");
package Compiler is
case OS is
when "GNU/Linux" | "Unix" =>
for Switches ("Ada") use ("-gnath");
when "NT" =>
for Switches ("Ada") use ("-gnatP");
when others =>
null;
end case;
end Compiler;
end MyProj;
@end group
@end smallexample
@c ---------------------------------------------
@node Attributes
@subsection Attributes
@c ---------------------------------------------
......@@ -3666,7 +3734,7 @@ system (file). The text is between brackets ([]) if the index is optional.
@item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
@item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
@headitem
Building @tab @tab @tab @pxref{Switches and Project Files}
Building @tab @tab @tab
@item Default_Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, IDE @tab insensitive (language name)
@item Switches @tab list @tab Builder, Compiler, Binder, Linker, Cross_Reference, Finder, gnatls, Pretty_Printer, gnatstub, Check, Synchronize, Eliminate, Metrics, Stack @tab [file] (file name)
@item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
......@@ -3757,950 +3825,3 @@ system (file). The text is between brackets ([]) if the index is optional.
@item Response_File_Switches @tab list @tab Linker @tab -
@end multitable
@c ---------------------------------------------
@node Case Statements
@subsection Case Statements
@c ---------------------------------------------
@noindent
A @b{case} statement is used in a project file to effect conditional
behavior. Through this statement, you can set the value of attributes
and variables depending on the value previously assigned to a typed
variable.
All choices in a choice list must be distinct. Unlike Ada, the choice
lists of all alternatives do not need to include all values of the type.
An @code{others} choice must appear last in the list of alternatives.
The syntax of a @code{case} construction is based on the Ada case statement
(although the @code{null} statement for empty alternatives is optional).
The case expression must be a typed string variable, whose value is often
given by an external reference (@pxref{External Values}).
Each alternative starts with the reserved word @code{when}, either a list of
literal strings separated by the @code{"|"} character or the reserved word
@code{others}, and the @code{"=>"} token.
Each literal string must belong to the string type that is the type of the
case variable.
After each @code{=>}, there are zero or more statements. The only
statements allowed in a case construction are other case 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.
@smallexample
case_statement ::=
@i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
case_item ::=
@i{when} discrete_choice_list =>
@{case_statement
| attribute_declaration
| variable_declaration
| empty_declaration@}
discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
@end smallexample
@noindent
Here is a typical example:
@smallexample @c projectfile
@group
project MyProj is
type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
OS : OS_Type := external ("OS", "GNU/Linux");
package Compiler is
case OS is
when "GNU/Linux" | "Unix" =>
for Switches ("Ada") use ("-gnath");
when "NT" =>
for Switches ("Ada") use ("-gnatP");
when others =>
null;
end case;
end Compiler;
end MyProj;
@end group
@end smallexample
@c ---------------------------------------------
@node Tools Supporting Project Files
@chapter Tools Supporting Project Files
@c ---------------------------------------------
@noindent
@menu
* gnatmake and Project Files::
* The GNAT Driver and Project Files::
* The Development Environments::
@end menu
@c ---------------------------------------------
@node gnatmake and Project Files
@section gnatmake and Project Files
@c ---------------------------------------------
@noindent
This section covers several topics related to @command{gnatmake} and
project files: defining ^switches^switches^ for @command{gnatmake}
and for the tools that it invokes; specifying configuration pragmas;
the use of the @code{Main} attribute; building and rebuilding library project
files.
@menu
* Switches Related to Project Files::
* Switches and Project Files::
* Specifying Configuration Pragmas::
* Project Files and Main Subprograms::
* Library Project Files::
@end menu
@c ---------------------------------------------
@node Switches Related to Project Files
@subsection Switches Related to Project Files
@c ---------------------------------------------
@noindent
The following switches are used by GNAT tools that support project files:
@table @option
@item ^-P^/PROJECT_FILE=^@var{project}
@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
if any, and using the external references indicated
by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
@ifclear vms
There may zero, one or more spaces between @option{-P} and @var{project}.
@end ifclear
There must be only one @option{^-P^/PROJECT_FILE^} 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
@option{^-P^/PROJECT_FILE^},
@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
Indicates that external variable @var{name} has the value @var{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
@ifclear vms
If @var{name} or @var{value} includes a space, then @var{name=value} should be
put between quotes.
@smallexample
-XOS=NT
-X"user=John Doe"
@end smallexample
@end ifclear
Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
@var{name}, only the last one is used.
An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
takes precedence over the value of the same name in the environment.
@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
Indicates the verbosity of the parsing of GNAT project files.
@ifclear vms
@option{-vP0} means Default;
@option{-vP1} means Medium;
@option{-vP2} means High.
@end ifclear
@ifset vms
There are three possible options for this qualifier: DEFAULT, MEDIUM and
HIGH.
@end ifset
The default is ^Default^DEFAULT^: no output for syntactically correct
project files.
If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
only the last one is used.
@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
Add directory <dir> at the beginning of the project search path, in order,
after the current working directory.
@ifclear vms
@item -eL
@cindex @option{-eL} (any project-aware tool)
Follow all symbolic links when processing project files.
@end ifclear
@item ^--subdirs^/SUBDIRS^=<subdir>
@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
This switch is recognized by @command{gnatmake} and @command{gnatclean}. It
indicate that the real directories (except the source directories) are the
subdirectories <subdir> of the directories specified in the project files.
This applies in particular to object directories, library directories and
exec directories. If the subdirectories do not exist, they are created
automatically.
@end table
@c ---------------------------------------------
@node Switches and Project Files
@subsection Switches and Project Files
@c ---------------------------------------------
@noindent
@ifset vms
It is not currently possible to specify VMS style qualifiers in the project
files; only Unix style ^switches^switches^ may be specified.
@end ifset
For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
attribute, a @code{Switches} attribute, or both;
as their names imply, these ^switch^switch^-related
attributes affect the ^switches^switches^ that are used for each of these GNAT
components when
@command{gnatmake} is invoked. As will be explained below, these
component-specific ^switches^switches^ precede
the ^switches^switches^ provided on the @command{gnatmake} command line.
The @code{^Default_Switches^Default_Switches^} attribute is an attribute
indexed by language name (case insensitive) whose value is a string list.
For example:
@smallexample @c projectfile
@group
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnaty^-gnaty^",
"^-v^-v^");
end Compiler;
@end group
@end smallexample
@noindent
The @code{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:
@smallexample @c projectfile
@group
package Builder is
for Switches ("main1.adb")
use ("^-O2^-O2^");
for Switches ("main2.adb")
use ("^-g^-g^");
end Builder;
@end group
@end smallexample
@noindent
For the @code{Builder} package, the file names must designate source files
for main subprograms. For the @code{Binder} and @code{Linker} packages, the
file names must designate @file{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 (@command{gnatmake}, the compiler, the
binder, and the linker), the corresponding package @dfn{contributes} a set of
^switches^switches^ for each file on which the tool is invoked, based on the
^switch^switch^-related attributes defined in the package.
In particular, the ^switches^switches^
that each of these packages contributes for a given file @var{f} comprise:
@itemize @bullet
@item the value of attribute @code{Switches (@var{f})},
if it is specified in the package for the given file,
@item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
if it is specified in the package.
@end itemize
@noindent
If neither of these attributes is defined in the package, then the package does
not contribute any ^switches^switches^ for the given file.
When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
two sets, in the following order: those contributed for the file
by the @code{Builder} package;
and the switches passed on the command line.
When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
the ^switches^switches^ passed to the tool comprise three sets,
in the following order:
@enumerate
@item
the applicable ^switches^switches^ contributed for the file
by the @code{Builder} package in the project file supplied on the command line;
@item
those contributed for the file by the package (in the relevant project file --
see below) corresponding to the tool; and
@item
the applicable switches passed on the command line.
@end enumerate
The term @emph{applicable ^switches^switches^} reflects the fact that
@command{gnatmake} ^switches^switches^ may or may not be passed to individual
tools, depending on the individual ^switch^switch^.
@command{gnatmake} may invoke the compiler on source files from different
projects. The Project Manager will use the appropriate project file to
determine the @code{Compiler} package for each source file being compiled.
Likewise for the @code{Binder} and @code{Linker} packages.
As an example, consider the following package in a project file:
@smallexample @c projectfile
@group
project Proj1 is
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-g^-g^");
for Switches ("a.adb")
use ("^-O1^-O1^");
for Switches ("b.adb")
use ("^-O2^-O2^",
"^-gnaty^-gnaty^");
end Compiler;
end Proj1;
@end group
@end smallexample
@noindent
If @command{gnatmake} is invoked with this project file, and it needs to
compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
@file{a.adb} will be compiled with the ^switch^switch^
@option{^-O1^-O1^},
@file{b.adb} with ^switches^switches^
@option{^-O2^-O2^}
and @option{^-gnaty^-gnaty^},
and @file{c.adb} with @option{^-g^-g^}.
The following example illustrates the ordering of the ^switches^switches^
contributed by different packages:
@smallexample @c projectfile
@group
project Proj2 is
package Builder is
for Switches ("main.adb")
use ("^-g^-g^",
"^-O1^-)1^",
"^-f^-f^");
end Builder;
@end group
@group
package Compiler is
for Switches ("main.adb")
use ("^-O2^-O2^");
end Compiler;
end Proj2;
@end group
@end smallexample
@noindent
If you issue the command:
@smallexample
gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
@end smallexample
@noindent
then the compiler will be invoked on @file{main.adb} with the following
sequence of ^switches^switches^
@smallexample
^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
@end smallexample
@noindent
with the last @option{^-O^-O^}
^switch^switch^ having precedence over the earlier ones;
several other ^switches^switches^
(such as @option{^-c^-c^}) are added implicitly.
The ^switches^switches^
@option{^-g^-g^}
and @option{^-O1^-O1^} are contributed by package
@code{Builder}, @option{^-O2^-O2^} is contributed
by the package @code{Compiler}
and @option{^-O0^-O0^} comes from the command line.
The @option{^-g^-g^}
^switch^switch^ will also be passed in the invocation of
@command{Gnatlink.}
A final example illustrates switch contributions from packages in different
project files:
@smallexample @c projectfile
@group
project Proj3 is
for Source_Files use ("pack.ads", "pack.adb");
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnata^-gnata^");
end Compiler;
end Proj3;
@end group
@group
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^-s^",
"^-g^-g^");
end Builder;
end Proj4;
@end group
@group
-- Ada source file:
with Pack;
procedure Foo_Main is
@dots{}
end Foo_Main;
@end group
@end smallexample
@noindent
If the command is
@smallexample
gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
@end smallexample
@noindent
then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
@option{^-gnato^-gnato^} (passed on the command line).
When the imported package @code{Pack} is compiled, the ^switches^switches^ used
are @option{^-g^-g^} from @code{Proj4.Builder},
@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
and @option{^-gnato^-gnato^} from the command line.
When using @command{gnatmake} with project files, some ^switches^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^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 @command{gnatmake} is invoked.
The ^switches^switches^ for which this occurs are:
^-I^-I^,
^-A^-A^,
^-L^-L^,
^-aO^-aO^,
^-aL^-aL^,
^-aI^-aI^, as well as all arguments that are not switches (arguments to
^switch^switch^
^-o^-o^, object files specified in package @code{Linker} or after
-largs on the command line). The exception to this rule is the ^switch^switch^
^--RTS=^--RTS=^ for which a relative path argument is never converted.
@c ---------------------------------------------
@node Specifying Configuration Pragmas
@subsection Specifying Configuration Pragmas
@c ---------------------------------------------
@noindent
When using @command{gnatmake} with project files, if there exists a file
@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: @code{Global_Configuration_Pragmas} in package @code{Builder}
and @code{Local_Configuration_Pragmas} in package @code{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
@code{Global_Configuration_Pragmas} in package @code{Builder} of the main
project file, if it is specified, and those listed in the file designated by
attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
the project file of the source, if it exists.
@c ---------------------------------------------
@node Project Files and Main Subprograms
@subsection Project Files and Main Subprograms
@c ---------------------------------------------
@noindent
When using a project file, you can invoke @command{gnatmake}
with one or several main subprograms, by specifying their source files on the
command line.
@smallexample
gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb
@end smallexample
@noindent
Each of these needs to be a source file of the same project, except
when the switch ^-u^/UNIQUE^ is used.
When ^-u^/UNIQUE^ 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 @code{Builder} of this common project, the
"main project" is the one that is considered by @command{gnatmake}.
When ^-u^/UNIQUE^ 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^switches^ found in package @code{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 @command{gnatmake} without
explicitly specifying any main, and the effect depends on whether you have
defined the @code{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 @code{Main} attribute is defined in a project file as a non-empty
string list and the switch @option{^-u^/UNIQUE^} is not used on the command
line, then invoking @command{gnatmake} with this project file but without any
main on the command line is equivalent to invoking @command{gnatmake} with all
the file names in the @code{Main} attribute on the command line.
Example:
@smallexample @c projectfile
@group
project Prj is
for Main use ("main1.adb", "main2.adb", "main3.adb");
end Prj;
@end group
@end smallexample
@noindent
With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
is equivalent to
@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}.
When the project attribute @code{Main} is not specified, or is specified
as an empty string list, or when the switch @option{-u} is used on the command
line, then invoking @command{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 @option{-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 @option{-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 @code{Main} exists
and includes several mains, or when several mains are specified on the
command line, the default ^switches^switches^ in package @code{Builder} will
be used for all mains, even if there are specific ^switches^switches^
specified for one or several mains.
But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
the specific ^switches^switches^ for each main, if they are specified.
@c ---------------------------------------------
@node Library Project Files
@subsection Library Project Files
@c ---------------------------------------------
@noindent
When @command{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^/ACTION=BIND^ and
^-l^/ACTION=LINK^ have special meanings.
@itemize @bullet
@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
to @command{gnatmake} that @command{gnatbind} should be invoked for the
library.
@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
to @command{gnatmake} that the binder generated file should be compiled
(in the case of a stand-alone library) and that the library should be built.
@end itemize
@c ---------------------------------------------
@node The GNAT Driver and Project Files
@section The GNAT Driver and Project Files
@c ---------------------------------------------
@noindent
A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
can benefit from project files:
(@command{^gnatbind^gnatbind^},
@command{^gnatcheck^gnatcheck^},
@command{^gnatclean^gnatclean^},
@command{^gnatelim^gnatelim^},
@command{^gnatfind^gnatfind^},
@command{^gnatlink^gnatlink^},
@command{^gnatls^gnatls^},
@command{^gnatmetric^gnatmetric^},
@command{^gnatpp^gnatpp^},
@command{^gnatstub^gnatstub^},
and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked
directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
They must be invoked through the @command{gnat} driver.
The @command{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 @command{gnat} driver accepts the following commands
(case insensitive):
@itemize @bullet
@item BIND to invoke @command{^gnatbind^gnatbind^}
@item CHOP to invoke @command{^gnatchop^gnatchop^}
@item CLEAN to invoke @command{^gnatclean^gnatclean^}
@item COMP or COMPILE to invoke the compiler
@item ELIM to invoke @command{^gnatelim^gnatelim^}
@item FIND to invoke @command{^gnatfind^gnatfind^}
@item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
@item LINK to invoke @command{^gnatlink^gnatlink^}
@item LS or LIST to invoke @command{^gnatls^gnatls^}
@item MAKE to invoke @command{^gnatmake^gnatmake^}
@item NAME to invoke @command{^gnatname^gnatname^}
@item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
@item PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
@item METRIC to invoke @command{^gnatmetric^gnatmetric^}
@item STUB to invoke @command{^gnatstub^gnatstub^}
@item XREF to invoke @command{^gnatxref^gnatxref^}
@end itemize
@noindent
(note that the compiler is invoked using the command
@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
On non-VMS platforms, between @command{gnat} and the command, two
special switches may be used:
@itemize @bullet
@item @command{-v} to display the invocation of the tool.
@item @command{-dn} to prevent the @command{gnat} driver from removing
the temporary files it has created. These temporary files are
configuration files and temporary file list files.
@end itemize
@noindent
The command may be followed by switches and arguments for the invoked
tool.
@smallexample
gnat bind -C main.ali
gnat ls -a main
gnat chop foo.txt
@end smallexample
@noindent
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 '@@'.
@smallexample
gnat bind @@args.txt main.ali
@end smallexample
@noindent
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
(@option{^-P^/PROJECT_FILE^},
@option{^-X^/EXTERNAL_REFERENCE^} and
@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) 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 @command{^gnatpp^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 @command{^gnatmetric^gnatmetric^}
with all the immediate sources of the specified project file and with
@option{^-d^/DIRECTORY^} 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^/ALL_PROJECTS^ is specified on the command line, then
the underlying tool (^gnatpp^gnatpp^ or
^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
not only for the immediate sources of the main project.
@ifclear vms
(-U stands for Universal or Union of the project files of the project tree)
@end ifclear
For each of the following commands, there is optionally a corresponding
package in the main project.
@itemize @bullet
@item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
@item package @code{Check} for command CHECK (invoking
@code{^gnatcheck^gnatcheck^})
@item package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
@item package @code{Cross_Reference} for command XREF (invoking
@code{^gnatxref^gnatxref^})
@item package @code{Eliminate} for command ELIM (invoking
@code{^gnatelim^gnatelim^})
@item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
@item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
@item package @code{Gnatstub} for command STUB
(invoking @code{^gnatstub^gnatstub^})
@item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
@item package @code{Check} for command CHECK
(invoking @code{^gnatcheck^gnatcheck^})
@item package @code{Metrics} for command METRIC
(invoking @code{^gnatmetric^gnatmetric^})
@item package @code{Pretty_Printer} for command PP or PRETTY
(invoking @code{^gnatpp^gnatpp^})
@end itemize
@noindent
Package @code{Gnatls} has a unique attribute @code{Switches},
a simple variable with a string list value. It contains ^switches^switches^
for the invocation of @code{^gnatls^gnatls^}.
@smallexample @c projectfile
@group
project Proj1 is
package gnatls is
for Switches
use ("^-a^-a^",
"^-v^-v^");
end gnatls;
end Proj1;
@end group
@end smallexample
@noindent
All other packages have two attribute @code{Switches} and
@code{^Default_Switches^Default_Switches^}.
@code{Switches} is an indexed attribute, indexed by the
source file name, that has a string list value: the ^switches^switches^ to be
used when the tool corresponding to the package is invoked for the specific
source file.
@code{^Default_Switches^Default_Switches^} is an attribute,
indexed by the programming language that has a string list value.
@code{^Default_Switches^Default_Switches^ ("Ada")} contains the
^switches^switches^ for the invocation of the tool corresponding
to the package, except if a specific @code{Switches} attribute
is specified for the source file.
@smallexample @c projectfile
@group
project Proj is
for Source_Dirs use ("**");
package gnatls is
for Switches use
("^-a^-a^",
"^-v^-v^");
end gnatls;
@end group
@group
package Compiler is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-gnatv^-gnatv^",
"^-gnatwa^-gnatwa^");
end Binder;
@end group
@group
package Binder is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-C^-C^",
"^-e^-e^");
end Binder;
@end group
@group
package Linker is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-C^-C^");
for Switches ("main.adb")
use ("^-C^-C^",
"^-v^-v^",
"^-v^-v^");
end Linker;
@end group
@group
package Finder is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-a^-a^",
"^-f^-f^");
end Finder;
@end group
@group
package Cross_Reference is
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-a^-a^",
"^-f^-f^",
"^-d^-d^",
"^-u^-u^");
end Cross_Reference;
end Proj;
@end group
@end smallexample
@noindent
With the above project file, commands such as
@smallexample
^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
@end smallexample
@noindent
will set up the environment properly and invoke the tool with the switches
found in the package corresponding to the tool:
@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
except @code{Switches ("main.adb")}
for @code{^gnatlink^gnatlink^}.
It is also possible to invoke some of the tools,
(@code{^gnatcheck^gnatcheck^},
@code{^gnatmetric^gnatmetric^},
and @code{^gnatpp^gnatpp^})
on a set of project units thanks to the combination of the switches
@option{-P}, @option{-U} and possibly the main unit when one is interested
in its closure. For instance,
@smallexample
gnat metric -Pproj
@end smallexample
@noindent
will compute the metrics for all the immediate units of project
@code{proj}.
@smallexample
gnat metric -Pproj -U
@end smallexample
@noindent
will compute the metrics for all the units of the closure of projects
rooted at @code{proj}.
@smallexample
gnat metric -Pproj -U main_unit
@end smallexample
@noindent
will compute the metrics for the closure of units rooted at
@code{main_unit}. This last possibility relies implicitly
on @command{gnatbind}'s option @option{-R}. But if the argument files for the
tool invoked by the @command{gnat} driver are explicitly specified
either directly or through the tool @option{-files} option, then the tool
is called only for these explicitly specified files.
@c ---------------------------------------------
@node The Development Environments
@section The Development Environments
@c ---------------------------------------------
@noindent
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 @b{IDE} in projects.
@table @code
@item Remote_Host
This is a simple attribute. Its value is a string that designates the remote
host in a cross-compilation environment, to be used for remote compilation and
debugging. This field should not be specified when running on the local
machine.
@item Program_Host
This is a simple attribute. Its value is a string that specifies the
name of IP address of the embedded target in a cross-compilation environment,
on which the program should execute.
@item Communication_Protocol
This is a simple string attribute. Its value is the name of the protocol
to use to communicate with the target in a cross-compilation environment,
e.g.@: @code{"wtx"} or @code{"vxworks"}.
@item Compiler_Command
This is an indexed attribute, whose domain is a language name. Its
value is string that denotes the command to be used to invoke the compiler.
The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
@command{gnatmake}, in particular in the handling of switches.
@item Debugger_Command
This is simple attribute, Its value is a string that specifies the name of
the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
@item Default_Switches
This is an indexed attribute. Its indexes are the name of the
external tools that the GNAT Programming System (GPS) is supporting. Its
value is a list of switches to use when invoking that tool.
@item Gnatlist
This is a simple attribute. Its value is a string that specifies the name
of the @command{gnatls} utility to be used to retrieve information about the
predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
@item VCS_Kind
This is a simple attribute. Its value is a string used to specify the
Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
ClearCase or Perforce.
@item Gnat
This is a simple attribute. Its value is a string that specifies the name
of the @command{gnat} utility to be used when executing various tools from
GPS, in particular @code{"gnat pp"}, @code{"gnat stub"},@dots{}
@item VCS_File_Check
This is a simple attribute. Its value is a string that specifies the
command used by the VCS to check the validity of a file, either
when the user explicitly asks for a check, or as a sanity check before
doing the check-in.
@item VCS_Log_Check
This is a simple attribute. Its value is a string that specifies
the command used by the VCS to check the validity of a log file.
@item VCS_Repository_Root
The VCS repository root path. This is used to create tags or branches
of the repository. For subversion the value should be the @code{URL}
as specified to check-out the working copy of the repository.
@item VCS_Patch_Root
The local root directory to use for building patch file. All patch chunks
will be relative to this path. The root project directory is used if
this value is not defined.
@end table
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment