@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 *****************************************
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
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}:
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
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
* External Values::
* Typed String Declaration::
* Variables::
+* Case Constructions::
* Attributes::
-* Case Statements::
@end menu
@c ---------------------------------------------
@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}.
@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
@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
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
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.
whose selector is a package name in that project.
@end itemize
+@c ---------------------------------------------
+@node Case Constructions
+@subsection Case Constructions
+@c ---------------------------------------------
+
+@noindent
+A @b{case} statement is used in a project file to effect conditional
+behavior. Through this statement, you can set the value of attributes
+and variables depending on the value previously assigned to a typed
+variable.
+
+All choices in a choice list must be distinct. Unlike Ada, the choice
+lists of all alternatives do not need to include all values of the type.
+An @code{others} choice must appear last in the list of alternatives.
+
+The syntax of a @code{case} construction is based on the Ada case statement
+(although the @code{null} statement for empty alternatives is optional).
+
+The case expression must be a typed string variable, whose value is often
+given by an external reference (@pxref{External Values}).
+
+Each alternative starts with the reserved word @code{when}, either a list of
+literal strings separated by the @code{"|"} character or the reserved word
+@code{others}, and the @code{"=>"} token.
+Each literal string must belong to the string type that is the type of the
+case variable.
+After each @code{=>}, there are zero or more statements. The only
+statements allowed in a case construction are other case constructions,
+attribute declarations and variable declarations. String type declarations and
+package declarations are not allowed. Variable declarations are restricted to
+variables that have already been declared before the case construction.
+
+@smallexample
+case_statement ::=
+ @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
+
+case_item ::=
+ @i{when} discrete_choice_list =>
+ @{case_statement
+ | attribute_declaration
+ | variable_declaration
+ | empty_declaration@}
+
+discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
+@end smallexample
+
+@noindent
+Here is a typical example:
+
+@smallexample @c projectfile
+@group
+project MyProj is
+ type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
+ OS : OS_Type := external ("OS", "GNU/Linux");
+
+ package Compiler is
+ case OS is
+ when "GNU/Linux" | "Unix" =>
+ for Switches ("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
@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 -
@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
projects / gcc.git / commitdiff