OSDN Git Service

fd0de1bb8f2088feb2f1baaff129caf8e3898fe5
[pf3gnuchains/gcc-fork.git] / gcc / ada / projects.texi
1 @set gprconfig GPRconfig
2
3 @c ------ projects.texi
4 @c Copyright (C) 2002-2012, Free Software Foundation, Inc.
5 @c This file is shared between the GNAT user's guide and gprbuild. It is not
6 @c compilable on its own, you should instead compile the other two manuals.
7 @c For that reason, there is no toplevel @menu
8
9 @c ---------------------------------------------
10 @node GNAT Project Manager
11 @chapter GNAT Project Manager
12 @c ---------------------------------------------
13
14 @noindent
15 @menu
16 * Introduction::
17 * Building With Projects::
18 * Organizing Projects into Subsystems::
19 * Scenarios in Projects::
20 * Library Projects::
21 * Project Extension::
22 * Aggregate Projects::
23 * Aggregate Library Projects::
24 * Project File Reference::
25 @end menu
26
27 @c ---------------------------------------------
28 @node Introduction
29 @section Introduction
30 @c ---------------------------------------------
31
32 @noindent
33 This chapter describes GNAT's @emph{Project Manager}, a facility that allows
34 you to manage complex builds involving a number of source files, directories,
35 and options for different system configurations. In particular,
36 project files allow you to specify:
37
38 @itemize @bullet
39 @item The directory or set of directories containing the source files, and/or the
40   names of the specific source files themselves
41 @item The directory in which the compiler's output
42   (@file{ALI} files, object files, tree files, etc.) is to be placed
43 @item The directory in which the executable programs are to be placed
44 @item Switch settings for any of the project-enabled tools;
45   you can apply these settings either globally or to individual compilation units.
46 @item The source files containing the main subprogram(s) to be built
47 @item The source programming language(s)
48 @item Source file naming conventions; you can specify these either globally or for
49   individual compilation units (@pxref{Naming Schemes}).
50 @item Change any of the above settings depending on external values, thus enabling
51   the reuse of the projects in various @b{scenarios} (@pxref{Scenarios
52   in Projects}).
53 @item Automatically build libraries as part of the build process
54   (@pxref{Library Projects}).
55
56 @end itemize
57
58 @noindent
59 Project files are written in a syntax close to that of Ada, using familiar
60 notions such as packages, context clauses, declarations, default values,
61 assignments, and inheritance (@pxref{Project File Reference}).
62
63 Project files can be built hierarchically from other project files, simplifying
64 complex system integration and project reuse (@pxref{Organizing Projects into
65 Subsystems}).
66
67 @itemize @bullet
68 @item One project can import other projects containing needed source files.
69   More generally, the Project Manager lets you structure large development
70   efforts into hierarchical subsystems, where build decisions are delegated
71   to the subsystem level, and thus different compilation environments
72   (switch settings) used for different subsystems.
73 @item You can organize GNAT projects in a hierarchy: a child project
74   can extend a parent project, inheriting the parent's source files and
75   optionally overriding any of them with alternative versions
76   (@pxref{Project Extension}).
77
78 @end itemize
79
80 @noindent
81 Several tools support project files, generally in addition to specifying
82 the information on the command line itself). They share common switches
83 to control the loading of the project (in particular
84 @option{^-P^/PROJECT_FILE=^@emph{projectfile}} and
85 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}}).
86 @xref{Switches Related to Project Files}.
87
88 The Project Manager supports a wide range of development strategies,
89 for systems of all sizes.  Here are some typical practices that are
90 easily handled:
91
92 @itemize @bullet
93 @item Using a common set of source files and generating object files in different
94   directories via different switch settings. It can be used for instance, for
95   generating separate sets of object files for debugging and for production.
96 @item Using a mostly-shared set of source files with different versions of
97   some units or subunits. It can be used for instance, for grouping and hiding
98 @end itemize
99
100 @noindent
101 all OS dependencies in a small number of implementation units.
102
103 Project files can be used to achieve some of the effects of a source
104 versioning system (for example, defining separate projects for
105 the different sets of sources that comprise different releases) but the
106 Project Manager is independent of any source configuration management tool
107 that might be used by the developers.
108
109 The various sections below introduce the different concepts related to
110 projects. Each section starts with examples and use cases, and then goes into
111 the details of related project file capabilities.
112
113 @c ---------------------------------------------
114 @node Building With Projects
115 @section Building With Projects
116 @c ---------------------------------------------
117
118 @noindent
119 In its simplest form, a unique project is used to build a single executable.
120 This section concentrates on such a simple setup. Later sections will extend
121 this basic model to more complex setups.
122
123 The following concepts are the foundation of project files, and will be further
124 detailed later in this documentation. They are summarized here as a reference.
125
126 @table @asis
127 @item @b{Project file}:
128   A text file using an Ada-like syntax, generally using the @file{.gpr}
129   extension. It defines build-related characteristics of an application.
130   The characteristics include the list of sources, the location of those
131   sources, the location for the generated object files, the name of
132   the main program, and the options for the various tools involved in the
133   build process.
134
135 @item @b{Project attribute}:
136   A specific project characteristic is defined by an attribute clause. Its
137   value is a string or a sequence of strings. All settings in a project
138   are defined through a list of predefined attributes with precise
139   semantics. @xref{Attributes}.
140
141 @item @b{Package in a project}:
142   Global attributes are defined at the top level of a project.
143   Attributes affecting specific tools are grouped in a
144   package whose name is related to tool's function. The most common
145   packages are @code{Builder}, @code{Compiler}, @code{Binder},
146   and @code{Linker}. @xref{Packages}.
147
148 @item @b{Project variables}:
149   In addition to attributes, a project can use variables to store intermediate
150   values and avoid duplication in complex expressions. It can be initialized
151   with a value coming from the environment.
152   A frequent use of variables is to define scenarios.
153   @xref{External Values}, @xref{Scenarios in Projects}, and @xref{Variables}.
154
155 @item @b{Source files} and @b{source directories}:
156   A source file is associated with a language through a naming convention. For
157   instance, @code{foo.c} is typically the name of a C source file;
158   @code{bar.ads} or @code{bar.1.ada} are two common naming conventions for a
159   file containing an Ada spec. A compilation unit is often composed of a main
160   source file and potentially several auxiliary ones, such as header files in C.
161   The naming conventions can be user defined @xref{Naming Schemes}, and will
162   drive the builder to call the appropriate compiler for the given source file.
163   Source files are searched for in the source directories associated with the
164   project through the @b{Source_Dirs} attribute. By default, all the files (in
165   these source directories) following the naming conventions associated with the
166   declared languages are considered to be part of the project. It is also
167   possible to limit the list of source files using the @b{Source_Files} or
168   @b{Source_List_File} attributes. Note that those last two attributes only
169   accept basenames with no directory information.
170
171 @item @b{Object files} and @b{object directory}:
172   An object file is an intermediate file produced by the compiler from a
173   compilation unit. It is used by post-compilation tools to produce
174   final executables or libraries. Object files produced in the context of
175   a given project are stored in a single directory that can be specified by the
176   @b{Object_Dir} attribute. In order to store objects in
177   two or more object directories, the system must be split into
178   distinct subsystems with their own project file.
179
180 @end table
181
182 The following subsections introduce gradually all the attributes of interest
183 for simple build needs. Here is the simple setup that will be used in the
184 following examples.
185
186 The Ada source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are in
187 the @file{common/} directory. The file @file{proc.adb} contains an Ada main
188 subprogram @code{Proc} that @code{with}s package @code{Pack}. We want to compile
189 these source files with the switch @option{-O2}, and put the resulting files in
190 the directory @file{obj/}.
191
192 @smallexample
193 @group
194 ^common/^[COMMON]^
195   pack.ads
196   pack.adb
197   proc.adb
198 @end group
199 @group
200 ^common/release/^[COMMON.RELEASE]^
201   proc.ali, proc.o pack.ali, pack.o
202 @end group
203 @end smallexample
204
205 @noindent
206 Our project is to be called @emph{Build}. The name of the
207 file is the name of the project (case-insensitive) with the
208 @file{.gpr} extension, therefore the project file name is @file{build.gpr}. This
209 is not mandatory, but a warning is issued when this convention is not followed.
210
211 This is a very simple example, and as stated above, a single project
212 file is enough for it. We will thus create a new file, that for now
213 should contain the following code:
214
215 @smallexample
216 @b{project} Build @b{is}
217 @b{end} Build;
218 @end smallexample
219
220 @menu
221 * Source Files and Directories::
222 * Object and Exec Directory::
223 * Main Subprograms::
224 * Tools Options in Project Files::
225 * Compiling with Project Files::
226 * Executable File Names::
227 * Avoid Duplication With Variables::
228 * Naming Schemes::
229 @end menu
230
231 @c ---------------------------------------------
232 @node Source Files and Directories
233 @subsection Source Files and Directories
234 @c ---------------------------------------------
235
236 @noindent
237 When you create a new project, the first thing to describe is how to find the
238 corresponding source files. This is the only settings that are needed by all
239 the tools that will use this project (builder, compiler, binder and linker for
240 the compilation, IDEs to edit the source files,@dots{}).
241
242 @cindex Source directories
243 First step is to declare the source directories, which are the directories
244 to be searched to find source files. In the case of the example,
245 the @file{common} directory is the only source directory.
246
247 @cindex @code{Source_Dirs}
248 There are several ways of defining source directories:
249
250 @itemize @bullet
251 @item When the attribute @b{Source_Dirs} is not used, a project contains a
252   single source directory which is the one where the project file itself
253   resides. In our example, if @file{build.gpr} is placed in the @file{common}
254   directory, the project has the needed implicit source directory.
255
256 @item The attribute @b{Source_Dirs} can be set to a list of path names, one
257   for each of the source directories. Such paths can either be absolute
258   names (for instance @file{"/usr/local/common/"} on UNIX), or relative to the
259   directory in which the project file resides (for instance "." if
260   @file{build.gpr} is inside @file{common/}, or "common" if it is one level up).
261   Each of the source directories must exist and be readable.
262
263 @cindex portability
264   The syntax for directories is platform specific. For portability, however,
265   the project manager will always properly translate UNIX-like path names to
266   the native format of specific platform. For instance, when the same project
267   file is to be used both on Unix and Windows, "/" should be used as the
268   directory separator rather than "\".
269
270 @item The attribute @b{Source_Dirs} can automatically include subdirectories
271   using a special syntax inspired by some UNIX shells. If any of the path in
272   the list ends with @emph{"**"}, then that path and all its subdirectories
273   (recursively) are included in the list of source directories. For instance,
274   @file{**} and @file{./**} represent the complete directory tree rooted at ".".
275 @cindex Source directories, recursive
276
277 @cindex @code{Excluded_Source_Dirs}
278   When using that construct, it can sometimes be convenient to also use the
279   attribute @b{Excluded_Source_Dirs}, which is also a list of paths. Each entry
280   specifies a directory whose immediate content, not including subdirs, is to
281   be excluded. It is also possible to exclude a complete directory subtree
282   using the "**" notation.
283
284 @cindex @code{Ignore_Source_Sub_Dirs}
285   It is often desirable to remove, from the source directories, directory
286   subtrees rooted at some subdirectories. An example is the subdirectories
287   created by a Version Control System such as Subversion that creates directory
288   subtrees .svn/**. To do that, attribute  @b{Ignore_Source_Sub_Dirs} can be
289   used. It specifies the list of simple file names for the root of these
290   undesirable directory subtrees.
291
292 @end itemize
293
294 @noindent
295 When applied to the simple example, and because we generally prefer to have
296 the project file at the toplevel directory rather than mixed with the sources,
297 we will create the following file
298
299 @smallexample
300    build.gpr
301    @b{project} Build @b{is}
302       @b{for} Source_Dirs @b{use} ("common");  --  <<<<
303    @b{end} Build;
304 @end smallexample
305
306 @noindent
307 Once source directories have been specified, one may need to indicate
308 source files of interest. By default, all source files present in the source
309 directories are considered by the project manager. When this is not desired,
310 it is possible to specify the list of sources to consider explicitly.
311 In such a case, only source file base names are indicated and not
312 their absolute or relative path names. The project manager is in charge of
313 locating the specified source files in the specified source directories.
314
315 @itemize @bullet
316 @item By default, the project manager  search for all source files of all
317   specified languages in all the source directories.
318
319   Since the project manager was initially developed for Ada environments, the
320   default language is usually Ada and the above project file is complete: it
321   defines without ambiguity the sources composing the project: that is to say,
322   all the sources in subdirectory "common" for the default language (Ada) using
323   the default naming convention.
324
325 @cindex @code{Languages}
326   However, when compiling a multi-language application, or a pure C
327   application, the project manager must be told which languages are of
328   interest, which is done by setting the @b{Languages} attribute to a list of
329   strings, each of which is the name of a language. Tools like
330   @command{gnatmake} only know about Ada, while other tools like
331   @command{gprbuild} know about many more languages such as C, C++, Fortran,
332   assembly and others can be added dynamically.
333
334 @cindex Naming scheme
335   Even when using only Ada, the default naming might not be suitable. Indeed,
336   how does the project manager recognizes an "Ada file" from any other
337   file? Project files can describe the naming scheme used for source files,
338   and override the default (@pxref{Naming Schemes}). The default is the
339   standard GNAT extension (@file{.adb} for bodies and @file{.ads} for
340   specs), which is what is used in our example, explaining why no naming scheme
341   is explicitly specified.
342   @xref{Naming Schemes}.
343
344 @item @code{Source Files}
345   @cindex @code{Source_Files}
346   In some cases, source directories might contain files that should not be
347   included in a project. One can specify the explicit list of file names to
348   be considered through the @b{Source_Files} attribute.
349   When this attribute is defined, instead of looking at every file in the
350   source directories, the project manager takes only those names into
351   consideration  reports  errors if they cannot be found in the source
352   directories or does not correspond to the naming scheme.
353
354 @item For various reasons, it is sometimes useful to have a project with no
355   sources (most of the time because the attributes defined in the project
356   file will be reused in other projects, as explained in @pxref{Organizing
357   Projects into Subsystems}. To do this, the attribute
358   @emph{Source_Files} is set to the empty list, i.e. @code{()}. Alternatively,
359   @emph{Source_Dirs} can be set to the empty list, with the same
360   result.
361
362 @item @code{Source_List_File}
363 @cindex @code{Source_List_File}
364   If there is a great number of files, it might be more convenient to use
365   the attribute @b{Source_List_File}, which specifies the full path of a file.
366   This file must contain a list of source file names (one per line, no
367   directory information) that are searched as if they had been defined
368   through @emph{Source_Files}. Such a file can easily be created through
369   external tools.
370
371   A warning is issued if both attributes @code{Source_Files} and
372   @code{Source_List_File} are given explicit values. In this case, the
373   attribute @code{Source_Files} prevails.
374
375 @item @code{Excluded_Source_Files}
376 @cindex @code{Excluded_Source_Files}
377 @cindex @code{Locally_Removed_Files}
378 @cindex @code{Excluded_Source_List_File}
379   Specifying an explicit list of files is not always convenient.It might be
380   more convenient to use the default search rules with specific exceptions.
381   This can be done thanks to the attribute @b{Excluded_Source_Files}
382   (or its synonym @b{Locally_Removed_Files}).
383   Its value is the list of file names that should not be taken into account.
384   This attribute is often used when extending a project, @xref{Project
385   Extension}. A similar attribute @b{Excluded_Source_List_File} plays the same
386   role but takes the name of file containing file names similarly to
387   @code{Source_List_File}.
388
389 @end itemize
390
391 @noindent
392 In most simple cases, such as the above example, the default source file search
393 behavior provides the expected result, and we do not need to add anything after
394 setting @code{Source_Dirs}. The project manager automatically finds
395 @file{pack.ads}, @file{pack.adb} and @file{proc.adb} as source files of the
396 project.
397
398 Note that it is considered an error for a project file to have no sources
399 attached to it unless explicitly declared as mentioned above.
400
401 If the order of the source directories is known statically, that is if
402 @code{"**"} is not used in the string list @code{Source_Dirs}, then there may
403 be several files with the same source file name sitting in different
404 directories of the project. In this case, only the file in the first directory
405 is considered as a source of the project and the others are hidden. If
406 @code{"**"} is used in the string list @code{Source_Dirs}, it is an error
407 to have several files with the same source file name in the same directory
408 @code{"**"} subtree, since there would be an ambiguity as to which one should
409 be used. However, two files with the same source file name may exist in two
410 single directories or directory subtrees. In this case, the one in the first
411 directory or directory subtree is a source of the project.
412
413 @c ---------------------------------------------
414 @node Object and Exec Directory
415 @subsection Object and Exec Directory
416 @c ---------------------------------------------
417
418 @noindent
419 The next step when writing a project is to indicate where the compiler should
420 put the object files. In fact, the compiler and other tools might create
421 several different kind of files (for GNAT, there is the object file and the ALI
422 file for instance). One of the important concepts in projects is that most
423 tools may consider source directories as read-only and do not attempt to create
424 new or temporary files there. Instead, all files are created in the object
425 directory. It is of course not true for project-aware IDEs, whose purpose it is
426 to create the source files.
427
428 @cindex @code{Object_Dir}
429 The object directory is specified through the @b{Object_Dir} attribute.
430 Its value is the path to the object directory, either absolute or
431 relative to the directory containing the project file. This
432 directory must already exist and be readable and writable, although
433 some tools have a switch to create the directory if needed (See
434 the switch @code{-p} for @command{gnatmake} and @command{gprbuild}).
435
436 If the attribute @code{Object_Dir} is not specified, it defaults to
437 the project directory, that is the directory containing the project file.
438
439 For our example, we can specify the object dir in this way:
440
441 @smallexample
442    @b{project} Build @b{is}
443       @b{for} Source_Dirs @b{use} ("common");
444       @b{for} Object_Dir @b{use} "obj";   --  <<<<
445    @b{end} Build;
446 @end smallexample
447
448 @noindent
449 As mentioned earlier, there is a single object directory per project. As a
450 result, if you have an existing system where the object files are spread in
451 several directories, you can either move all of them into the same directory if
452 you want to build it with a single project file, or study the section on
453 subsystems (@pxref{Organizing Projects into Subsystems}) to see how each
454 separate object directory can be associated with one of the subsystem
455 constituting the application.
456
457 When the @command{linker} is called, it usually creates an executable. By
458 default, this executable is placed in the object directory of the project. It
459 might be convenient to store it in its own directory.
460
461 @cindex @code{Exec_Dir}
462 This can be done through the @code{Exec_Dir} attribute, which, like
463 @emph{Object_Dir} contains a single absolute or relative path and must point to
464 an existing and writable directory, unless you ask the tool to create it on
465 your behalf. When not specified, It defaults to the object directory and
466 therefore to the project file's directory if neither @emph{Object_Dir} nor
467 @emph{Exec_Dir} was specified.
468
469 In the case of the example, let's place the executable in the root
470 of the hierarchy, ie the same directory as @file{build.gpr}. Hence
471 the project file is now
472
473 @smallexample
474    @b{project} Build @b{is}
475       @b{for} Source_Dirs @b{use} ("common");
476       @b{for} Object_Dir @b{use} "obj";
477       @b{for} Exec_Dir @b{use} ".";  --   <<<<
478    @b{end} Build;
479 @end smallexample
480
481 @c ---------------------------------------------
482 @node Main Subprograms
483 @subsection Main Subprograms
484 @c ---------------------------------------------
485
486 @noindent
487 In the previous section, executables were mentioned. The project manager needs
488 to be taught what they are. In a project file, an executable is indicated by
489 pointing to source file of the main subprogram. In C this is the file that
490 contains the @code{main} function, and in Ada the file that contains the main
491 unit.
492
493 There can be any number of such main files within a given project, and thus
494 several executables can be built in the context of a single project file. Of
495 course, one given executable might not (and in fact will not) need all the
496 source files referenced by the project. As opposed to other build environments
497 such as @command{makefile}, one does not need to specify the list of
498 dependencies of each executable, the project-aware builders knows enough of the
499 semantics of the languages to build ands link only the necessary elements.
500
501 @cindex @code{Main}
502 The list of main files is specified via the @b{Main} attribute. It contains
503 a list of file names (no directories). If a project defines this
504 attribute, it is not necessary to identify  main files on the
505 command line when invoking a builder, and editors like
506 @command{GPS} will be able to create extra menus to spawn or debug the
507 corresponding executables.
508
509 @smallexample
510    @b{project} Build @b{is}
511       @b{for} Source_Dirs @b{use} ("common");
512       @b{for} Object_Dir @b{use} "obj";
513       @b{for} Exec_Dir @b{use} ".";
514       @b{for} Main @b{use} ("proc.adb");  --   <<<<
515    @b{end} Build;
516 @end smallexample
517
518 @noindent
519 If this attribute is defined in the project, then spawning the builder
520 with a command such as
521
522 @smallexample
523    gnatmake ^-Pbuild^/PROJECT_FILE=build^
524 @end smallexample
525
526 @noindent
527 automatically builds all the executables corresponding to the files
528 listed in the @emph{Main} attribute. It is possible to specify one
529 or more executables on the command line to build a subset of them.
530
531 @c ---------------------------------------------
532 @node Tools Options in Project Files
533 @subsection Tools Options in Project Files
534 @c ---------------------------------------------
535
536 @noindent
537 We now have a project file that fully describes our environment, and can be
538 used to build the application with a simple @command{gnatmake} command as seen
539 in the previous section. In fact, the empty project we showed immediately at
540 the beginning (with no attribute at all) could already fulfill that need if it
541 was put in the @file{common} directory.
542
543 Of course, we always want more control. This section will show you how to
544 specify the compilation switches that the various tools involved in the
545 building of the executable should use.
546
547 @cindex command line length
548 Since source names and locations are described into the project file, it is not
549 necessary to use switches on the command line for this purpose (switches such
550 as -I for gcc). This removes a major source of command line length overflow.
551 Clearly, the builders will have to communicate this information one way or
552 another to the underlying compilers and tools they call but they usually use
553 response files for this and thus should not be subject to command line
554 overflows.
555
556 Several tools are participating to the creation of an executable: the compiler
557 produces object files from the source files; the binder (in the Ada case)
558 creates an source file that takes care, among other things, of elaboration
559 issues and global variables initialization; and the linker gathers everything
560 into a single executable that users can execute. All these tools are known by
561 the project manager and will be called with user defined switches from the
562 project files. However, we need to introduce a new project file concept to
563 express which switches to be used for any of the tools involved in the build.
564
565 @cindex project file packages
566 A project file is subdivided into zero or more @b{packages}, each of which
567 contains the attributes specific to one tool (or one set of tools). Project
568 files use an Ada-like syntax for packages. Package names permitted in project
569 files are restricted to a predefined set (@pxref{Packages}), and the contents
570 of packages are limited to a small set of constructs and attributes
571 (@pxref{Attributes}).
572
573 Our example project file can be extended with the following empty packages. At
574 this stage, they could all be omitted since they are empty, but they show which
575 packages would be involved in the build process.
576
577 @smallexample
578    @b{project} Build @b{is}
579       @b{for} Source_Dirs @b{use} ("common");
580       @b{for} Object_Dir @b{use} "obj";
581       @b{for} Exec_Dir @b{use} ".";
582       @b{for} Main @b{use} ("proc.adb");
583
584       @b{package} Builder @b{is}  --<<<  for gnatmake and gprbuild
585       @b{end} Builder;
586
587       @b{package} Compiler @b{is} --<<<  for the compiler
588       @b{end} Compiler;
589
590       @b{package} Binder @b{is}   --<<<  for the binder
591       @b{end} Binder;
592
593       @b{package} Linker @b{is}   --<<<  for the linker
594       @b{end} Linker;
595    @b{end} Build;
596 @end smallexample
597
598 @noindent
599 Let's first examine the compiler switches. As stated in the initial description
600 of the example, we want to compile all files with @option{-O2}. This is a
601 compiler switch, although it is usual, on the command line, to pass it to the
602 builder which then passes it to the compiler. It is recommended to use directly
603 the right package, which will make the setup easier to understand for other
604 people.
605
606 Several attributes can be used to specify the switches:
607
608 @table @asis
609 @item @b{Default_Switches}:
610 @cindex @code{Default_Switches}
611   This is the first mention in this manual of an @b{indexed attribute}. When
612   this attribute is defined, one must supply an @emph{index} in the form of a
613   literal string.
614   In the case of @emph{Default_Switches}, the index is the name of the
615   language to which the switches apply (since a different compiler will
616   likely be used for each language, and each compiler has its own set of
617   switches). The value of the attribute is a list of switches.
618
619   In this example, we want to compile all Ada source files with the
620   @option{-O2} switch, and the resulting project file is as follows
621   (only the @code{Compiler} package is shown):
622
623   @smallexample
624   @b{package} Compiler @b{is}
625     @b{for} Default_Switches ("Ada") @b{use} ("-O2");
626   @b{end} Compiler;
627   @end smallexample
628
629 @item @b{Switches}:
630 @cindex @code{Switches}
631   in some cases, we might want to use specific switches
632   for one or more files. For instance, compiling @file{proc.adb} might not be
633   possible at high level of optimization because of a compiler issue.
634   In such a case, the @emph{Switches}
635   attribute (indexed on the file name) can be used and will override the
636   switches defined by @emph{Default_Switches}. Our project file would
637   become:
638
639   @smallexample
640   @b{package} Compiler @b{is}
641     @b{for} Default_Switches ("Ada") @b{use} ("-O2");
642     @b{for} Switches ("proc.adb") @b{use} ("-O0");
643   @b{end} Compiler;
644   @end smallexample
645
646   @noindent
647   @code{Switches} may take a pattern as an index, such as in:
648
649   @smallexample
650   @b{package} Compiler @b{is}
651     @b{for} Default_Switches ("Ada") @b{use} ("-O2");
652     @b{for} Switches ("pkg*") @b{use} ("-O0");
653   @b{end} Compiler;
654   @end smallexample
655
656   @noindent
657   Sources @file{pkg.adb} and @file{pkg-child.adb} would be compiled with -O0,
658   not -O2.
659
660   @noindent
661   @code{Switches} can also be given a language name as index instead of a file
662   name in which case it has the same semantics as @emph{Default_Switches}.
663   However, indexes with wild cards are never valid for language name.
664
665 @item @b{Local_Configuration_Pragmas}:
666 @cindex @code{Local_Configuration_Pragmas}
667   this attribute may specify the path
668   of a file containing configuration pragmas for use by the Ada compiler,
669   such as @code{pragma Restrictions (No_Tasking)}. These pragmas will be
670   used for all the sources of the project.
671
672 @end table
673
674 The switches for the other tools are defined in a similar manner through the
675 @b{Default_Switches} and @b{Switches} attributes, respectively in the
676 @emph{Builder} package (for @command{gnatmake} and @command{gprbuild}),
677 the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
678 package (for linking executables).
679
680 @c ---------------------------------------------
681 @node Compiling with Project Files
682 @subsection Compiling with Project Files
683 @c ---------------------------------------------
684
685 @noindent
686 Now that our project files are written, let's build our executable.
687 Here is the command we would use from the command line:
688
689 @smallexample
690    gnatmake ^-Pbuild^/PROJECT_FILE=build^
691 @end smallexample
692
693 @noindent
694 This will automatically build the executables specified through the
695 @emph{Main} attribute: for each, it will compile or recompile the
696 sources for which the object file does not exist or is not up-to-date; it
697 will then run the binder; and finally run the linker to create the
698 executable itself.
699
700 @command{gnatmake} only knows how to handle Ada files. By using
701 @command{gprbuild} as a builder, you could automatically manage C files the
702 same way: create the file @file{utils.c} in the @file{common} directory,
703 set the attribute @emph{Languages} to @code{"(Ada, C)"}, and run
704
705 @smallexample
706    gprbuild ^-Pbuild^/PROJECT_FILE=build^
707 @end smallexample
708
709 @noindent
710 Gprbuild knows how to recompile the C files and will
711 recompile them only if one of their dependencies has changed. No direct
712 indication on how to build the various elements is given in the
713 project file, which describes the project properties rather than a
714 set of actions to be executed. Here is the invocation of
715 @command{gprbuild} when building a multi-language program:
716
717 @smallexample
718 $ gprbuild -Pbuild
719 gcc -c proc.adb
720 gcc -c pack.adb
721 gcc -c utils.c
722 gprbind proc
723 ...
724 gcc proc.o -o proc
725 @end smallexample
726
727 @noindent
728 Notice the three steps described earlier:
729
730 @itemize @bullet
731 @item The first three gcc commands correspond to the compilation phase.
732 @item The gprbind command corresponds to the post-compilation phase.
733 @item The last gcc command corresponds to the final link.
734
735 @end itemize
736
737 @noindent
738 @cindex @option{-v} option (for GPRbuild)
739 The default output of GPRbuild's execution is kept reasonably simple and easy
740 to understand. In particular, some of the less frequently used commands are not
741 shown, and some parameters are abbreviated. So it is not possible to rerun the
742 effect of the @command{gprbuild} command by cut-and-pasting its output.
743 GPRbuild's option @code{-v} provides a much more verbose output which includes,
744 among other information, more complete compilation, post-compilation and link
745 commands.
746
747 @c ---------------------------------------------
748 @node Executable File Names
749 @subsection Executable File Names
750 @c ---------------------------------------------
751
752 @noindent
753 @cindex @code{Executable}
754 By default, the executable name corresponding to a main file is
755 computed from the main source file name. Through the attribute
756 @b{Builder.Executable}, it is possible to change this default.
757
758 For instance, instead of building @command{proc} (or @command{proc.exe}
759 on Windows), we could configure our project file to build "proc1"
760 (resp proc1.exe) with the following addition:
761
762 @smallexample @c projectfile
763    project Build is
764       ...  --  same as before
765       package Builder is
766          for Executable ("proc.adb") use "proc1";
767       end Builder
768    end Build;
769 @end smallexample
770
771 @noindent
772 @cindex @code{Executable_Suffix}
773 Attribute @b{Executable_Suffix}, when specified, may change the suffix
774 of the executable files, when no attribute @code{Executable} applies:
775 its value replace the platform-specific executable suffix.
776 The default executable suffix is empty on UNIX and ".exe" on Windows.
777
778 It is also possible to change the name of the produced executable by using the
779 command line switch @option{-o}. When several mains are defined in the project,
780 it is not possible to use the @option{-o} switch and the only way to change the
781 names of the executable is provided by Attributes @code{Executable} and
782 @code{Executable_Suffix}.
783
784 @c ---------------------------------------------
785 @node Avoid Duplication With Variables
786 @subsection Avoid Duplication With Variables
787 @c ---------------------------------------------
788
789 @noindent
790 To illustrate some other project capabilities, here is a slightly more complex
791 project using similar sources and a main program in C:
792
793 @smallexample @c projectfile
794 project C_Main is
795    for Languages    use ("Ada", "C");
796    for Source_Dirs  use ("common");
797    for Object_Dir   use  "obj";
798    for Main         use ("main.c");
799    package Compiler is
800       C_Switches := ("-pedantic");
801       for Default_Switches ("C")   use C_Switches;
802       for Default_Switches ("Ada") use ("-gnaty");
803       for Switches ("main.c") use C_Switches & ("-g");
804    end Compiler;
805 end C_Main;
806 @end smallexample
807
808 @noindent
809 This project has many similarities with the previous one.
810 As expected, its @code{Main} attribute now refers to a C source.
811 The attribute @emph{Exec_Dir} is now omitted, thus the resulting
812 executable will be put in the directory @file{obj}.
813
814 The most noticeable difference is the use of a variable in the
815 @emph{Compiler} package to store settings used in several attributes.
816 This avoids text duplication, and eases maintenance (a single place to
817 modify if we want to add new switches for C files). We will revisit
818 the use of variables in the context of scenarios (@pxref{Scenarios in
819 Projects}).
820
821 In this example, we see how the file @file{main.c} can be compiled with
822 the switches used for all the other C files, plus @option{-g}.
823 In this specific situation the use of a variable could have been
824 replaced by a reference to the @code{Default_Switches} attribute:
825
826 @smallexample @c projectfile
827    for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
828 @end smallexample
829
830 @noindent
831 Note the tick (@emph{'}) used to refer to attributes defined in a package.
832
833 Here is the output of the GPRbuild command using this project:
834
835 @smallexample
836 $gprbuild -Pc_main
837 gcc -c -pedantic -g main.c
838 gcc -c -gnaty proc.adb
839 gcc -c -gnaty pack.adb
840 gcc -c -pedantic utils.c
841 gprbind main.bexch
842 ...
843 gcc main.o -o main
844 @end smallexample
845
846 @noindent
847 The default switches for Ada sources,
848 the default switches for C sources (in the compilation of @file{lib.c}),
849 and the specific switches for @file{main.c} have all been taken into
850 account.
851
852 @c ---------------------------------------------
853 @node Naming Schemes
854 @subsection Naming Schemes
855 @c ---------------------------------------------
856
857 @noindent
858 Sometimes an Ada software system is ported from one compilation environment to
859 another (say GNAT), and the file are not named using the default GNAT
860 conventions. Instead of changing all the file names, which for a variety of
861 reasons might not be possible, you can define the relevant file naming scheme
862 in the @b{Naming} package of your project file.
863
864 The naming scheme has two distinct goals for the project manager: it
865 allows finding of source files when searching in the source
866 directories, and given a source file name it makes it possible to guess
867 the associated language, and thus the compiler to use.
868
869 Note that the use by the Ada compiler of pragmas Source_File_Name is not
870 supported when using project files. You must use the features described in this
871 paragraph. You can however specify other configuration pragmas
872 (@pxref{Specifying Configuration Pragmas}).
873
874 The following attributes can be defined in package @code{Naming}:
875
876 @table @asis
877 @item @b{Casing}:
878 @cindex @code{Casing}
879   Its value must be one of @code{"lowercase"} (the default if
880   unspecified), @code{"uppercase"} or @code{"mixedcase"}. It describes the
881   casing of file names with regards to the Ada unit name. Given an Ada unit
882   My_Unit, the file name will respectively be @file{my_unit.adb} (lowercase),
883   @file{MY_UNIT.ADB} (uppercase) or @file{My_Unit.adb} (mixedcase).
884   On Windows, file names are case insensitive, so this attribute is
885   irrelevant.
886
887 @item @b{Dot_Replacement}:
888 @cindex @code{Dot_Replacement}
889   This attribute specifies the string that should replace the "." in unit
890   names. Its default value is @code{"-"} so that a unit
891   @code{Parent.Child} is expected to be found in the file
892   @file{parent-child.adb}. The replacement string must satisfy the following
893   requirements to avoid ambiguities in the naming scheme:
894
895   @itemize -
896   @item It must not be empty
897   @item It cannot start or end with an alphanumeric character
898   @item It cannot be a single underscore
899   @item It cannot start with an underscore followed by an alphanumeric
900   @item It cannot contain a dot @code{'.'} except if the entire string
901      is @code{"."}
902
903   @end itemize
904
905 @item @b{Spec_Suffix} and @b{Specification_Suffix}:
906 @cindex @code{Spec_Suffix}
907 @cindex @code{Specification_Suffix}
908   For Ada, these attributes give the suffix used in file names that contain
909   specifications. For other languages, they give the extension for files
910   that contain declaration (header files in C for instance). The attribute
911   is indexed on the language.
912   The two attributes are equivalent, but the latter is obsolescent.
913   If @code{Spec_Suffix ("Ada")} is not specified, then the default is
914   @code{"^.ads^.ADS^"}.
915   The value must satisfy the following requirements:
916
917   @itemize -
918   @item It must not be empty
919   @item It cannot start with an alphanumeric character
920   @item It cannot start with an underscore followed by an alphanumeric character
921   @item It must include at least one dot
922
923   @end itemize
924
925 @item @b{Body_Suffix} and @b{Implementation_Suffix}:
926 @cindex @code{Body_Suffix}
927 @cindex @code{Implementation_Suffix}
928   These attributes give the extension used for file names that contain
929   code (bodies in Ada). They are indexed on the language. The second
930   version is obsolescent and fully replaced by the first attribute.
931
932   These attributes must satisfy the same requirements as @code{Spec_Suffix}.
933   In addition, they must be different from any of the values in
934   @code{Spec_Suffix}.
935   If @code{Body_Suffix ("Ada")} is not specified, then the default is
936   @code{"^.adb^.ADB^"}.
937
938   If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
939   same string, then a file name that ends with the longest of these two
940   suffixes will be a body if the longest suffix is @code{Body_Suffix ("Ada")}
941   or a spec if the longest suffix is @code{Spec_Suffix ("Ada")}.
942
943   If the suffix does not start with a '.', a file with a name exactly equal
944   to the suffix will also be part of the project (for instance if you define
945   the suffix as @code{Makefile}, a file called @file{Makefile} will be part
946   of the project. This capability is usually not interesting  when building.
947   However, it might become useful when a project is also used to
948   find the list of source files in an editor, like the GNAT Programming System
949   (GPS).
950
951 @item @b{Separate_Suffix}:
952 @cindex @code{Separate_Suffix}
953   This attribute is specific to Ada. It denotes the suffix used in file names
954   that contain separate bodies. If it is not specified, then it defaults to
955   same value as @code{Body_Suffix ("Ada")}. The same rules apply as for the
956   @code{Body_Suffix} attribute. The only accepted index is "Ada".
957
958 @item @b{Spec} or @b{Specification}:
959 @cindex @code{Spec}
960 @cindex @code{Specification}
961   This attribute @code{Spec} can be used to define the source file name for a
962   given Ada compilation unit's spec. The index is the literal name of the Ada
963   unit (case insensitive). The value is the literal base name of the file that
964   contains this unit's spec (case sensitive or insensitive depending on the
965   operating system). This attribute allows the definition of exceptions to the
966   general naming scheme, in case some files do not follow the usual
967   convention.
968
969   When a source file contains several units, the relative position of the unit
970   can be indicated. The first unit in the file is at position 1
971
972   @smallexample @c projectfile
973    for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
974    for Spec ("top") use "foo.a" at 1;
975    for Spec ("foo") use "foo.a" at 2;
976   @end smallexample
977
978 @item @b{Body} or @b{Implementation}:
979 @cindex @code{Body}
980 @cindex @code{Implementation}
981   These attribute play the same role as @emph{Spec} for Ada bodies.
982
983 @item @b{Specification_Exceptions} and @b{Implementation_Exceptions}:
984 @cindex @code{Specification_Exceptions}
985 @cindex @code{Implementation_Exceptions}
986   These attributes define exceptions to the naming scheme for languages
987   other than Ada. They are indexed on the language name, and contain
988   a list of file names respectively for headers and source code.
989
990 @end table
991
992 @ifclear vms
993 For example, the following package models the Apex file naming rules:
994
995 @smallexample @c projectfile
996 @group
997   package Naming is
998     for Casing               use "lowercase";
999     for Dot_Replacement      use ".";
1000     for Spec_Suffix ("Ada")  use ".1.ada";
1001     for Body_Suffix ("Ada")  use ".2.ada";
1002   end Naming;
1003 @end group
1004 @end smallexample
1005 @end ifclear
1006
1007 @ifset vms
1008 For example, the following package models the DEC Ada file naming rules:
1009
1010 @smallexample @c projectfile
1011 @group
1012   package Naming is
1013     for Casing               use "lowercase";
1014     for Dot_Replacement      use "__";
1015     for Spec_Suffix ("Ada")  use "_.ada";
1016     for Body_Suffix ("Ada")  use ".ada";
1017   end Naming;
1018 @end group
1019 @end smallexample
1020
1021 @noindent
1022 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
1023 names in lower case)
1024 @end ifset
1025
1026 @c ---------------------------------------------
1027 @node Organizing Projects into Subsystems
1028 @section Organizing Projects into Subsystems
1029 @c ---------------------------------------------
1030
1031 @noindent
1032 A @b{subsystem} is a coherent part of the complete system to be built. It is
1033 represented by a set of sources and one single object directory. A system can
1034 be composed of a single subsystem when it is simple as we have seen in the
1035 first section. Complex systems are usually composed of several interdependent
1036 subsystems. A subsystem is dependent on another subsystem if knowledge of the
1037 other one is required to build it, and in particular if visibility on some of
1038 the sources of this other subsystem is required. Each subsystem is usually
1039 represented by its own project file.
1040
1041 In this section, the previous example is being extended. Let's assume some
1042 sources of our @code{Build} project depend on other sources.
1043 For instance, when building a graphical interface, it is usual to depend upon
1044 a graphical library toolkit such as GtkAda. Furthermore, we also need
1045 sources from a logging module we had previously written.
1046
1047 @menu
1048 * Project Dependencies::
1049 * Cyclic Project Dependencies::
1050 * Sharing Between Projects::
1051 * Global Attributes::
1052 @end menu
1053
1054 @c ---------------------------------------------
1055 @node Project Dependencies
1056 @subsection Project Dependencies
1057 @c ---------------------------------------------
1058
1059 @noindent
1060 GtkAda comes with its own project file (appropriately called
1061 @file{gtkada.gpr}), and we will assume we have already built a project
1062 called @file{logging.gpr} for the logging module. With the information provided
1063 so far in @file{build.gpr}, building the application would fail with an error
1064 indicating that the gtkada and logging units that are relied upon by the sources
1065 of this project cannot be found.
1066
1067 This is easily solved by adding the following @b{with} clauses at the beginning
1068 of our project:
1069
1070 @smallexample @c projectfile
1071   with "gtkada.gpr";
1072   with "a/b/logging.gpr";
1073   project Build is
1074      ...  --  as before
1075   end Build;
1076 @end smallexample
1077
1078 @noindent
1079 @cindex @code{Externally_Built}
1080 When such a project is compiled, @command{gnatmake} will automatically
1081 check the other projects and recompile their sources when needed. It will also
1082 recompile the sources from @code{Build} when needed, and finally create the
1083 executable. In some cases, the implementation units needed to recompile a
1084 project are not available, or come from some third-party and you do not want to
1085 recompile it yourself. In this case, the attribute @b{Externally_Built} to
1086 "true" can be set, indicating to the builder that this project can be assumed
1087 to be up-to-date, and should not be considered for recompilation. In Ada, if
1088 the sources of this externally built project were compiled with another version
1089 of the compiler or with incompatible options, the binder will issue an error.
1090
1091 The project's @code{with} clause has several effects. It provides source
1092 visibility between projects during the compilation process. It also guarantees
1093 that the necessary object files from @code{Logging} and @code{GtkAda} are
1094 available when linking @code{Build}.
1095
1096 As can be seen in this example, the syntax for importing projects is similar
1097 to the syntax for importing compilation units in Ada. However, project files
1098 use literal strings instead of names, and the @code{with} clause identifies
1099 project files rather than packages.
1100
1101 Each literal string after @code{with} is the path
1102 (absolute or relative) to a project file. The @code{.gpr} extension is
1103 optional, although we recommend adding it. If no extension is specified,
1104 and no project file with the @file{^.gpr^.GPR^} extension is found, then
1105 the file is searched for exactly as written in the @code{with} clause,
1106 that is with no extension.
1107
1108 As mentioned above, the path after a @code{with} has to be a literal
1109 string, and you cannot use concatenation, or lookup the value of external
1110 variables to change the directories from which a project is loaded.
1111 A solution if you need something like this is to use aggregate projects
1112 (@pxref{Aggregate Projects}).
1113
1114 @cindex project path
1115 When a relative path or a base name is used, the
1116 project files are searched relative to each of the directories in the
1117 @b{project path}. This path includes all the directories found with the
1118 following algorithm, in that order, as soon as a matching file is found,
1119 the search stops:
1120
1121 @itemize @bullet
1122 @item First, the file is searched relative to the directory that contains the
1123   current project file.
1124
1125 @item
1126 @cindex @code{ADA_PROJECT_PATH}
1127 @cindex @code{GPR_PROJECT_PATH}
1128   Then it is searched relative to all the directories specified in the
1129   ^environment variables^logical names^ @b{GPR_PROJECT_PATH} and
1130   @b{ADA_PROJECT_PATH} (in that order) if they exist. The former is
1131   recommended, the latter is kept for backward compatibility.
1132
1133 @item Finally, it is searched relative to the default project directories.
1134   Such directories depends on the tool used. The different locations searched
1135   in the specified order are:
1136
1137   @itemize @bullet
1138   @item @file{<prefix>/<target>/lib/gnat}
1139   (for @command{gnatmake} in all cases, and for @command{gprbuild} if option
1140   @option{--target} is specified)
1141   @item @file{<prefix>/share/gpr/}
1142   (for @command{gnatmake} and @command{gprbuild})
1143   @item @file{<prefix>/lib/gnat/}
1144   (for @command{gnatmake} and @command{gprbuild})
1145   @end itemize
1146
1147   In our example, @file{gtkada.gpr} is found in the predefined directory if
1148   it was installed at the same root as GNAT.
1149 @end itemize
1150
1151 @noindent
1152 Some tools also support extending the project path from the command line,
1153 generally through the @option{-aP}. You can see the value of the project
1154 path by using the @command{gnatls -v} command.
1155
1156 Any symbolic link will be fully resolved in the directory of the
1157 importing project file before the imported project file is examined.
1158
1159 Any source file in the imported project can be used by the sources of the
1160 importing project, transitively.
1161 Thus if @code{A} imports @code{B}, which imports @code{C}, the sources of
1162 @code{A} may depend on the sources of @code{C}, even if @code{A} does not
1163 import @code{C} explicitly. However, this is not recommended, because if
1164 and when @code{B} ceases to import @code{C}, some sources in @code{A} will
1165 no longer compile. @command{gprbuild} has a switch @option{--no-indirect-imports}
1166 that will report such indirect dependencies.
1167
1168 One very important aspect of a project hierarchy is that
1169 @b{a given source can only belong to one project} (otherwise the project manager
1170 would not know which settings apply to it and when to recompile it). It means
1171 that different project files do not usually share source directories or
1172 when they do, they need to specify precisely which project owns which sources
1173 using attribute @code{Source_Files} or equivalent. By contrast, 2 projects
1174 can each own a source with the same base file name as long as they live in
1175 different directories. The latter is not true for Ada Sources because of the
1176 correlation between source files and Ada units.
1177
1178 @c ---------------------------------------------
1179 @node Cyclic Project Dependencies
1180 @subsection Cyclic Project Dependencies
1181 @c ---------------------------------------------
1182
1183 @noindent
1184 Cyclic dependencies are mostly forbidden:
1185 if @code{A} imports @code{B} (directly or indirectly) then @code{B}
1186 is not allowed to import @code{A}. However, there are cases when cyclic
1187 dependencies would be beneficial. For these cases, another form of import
1188 between projects exists: the @b{limited with}.  A project @code{A} that
1189 imports a project @code{B} with a straight @code{with} may also be imported,
1190 directly or indirectly, by @code{B} through a @code{limited with}.
1191
1192 The difference between straight @code{with} and @code{limited with} is that
1193 the name of a project imported with a @code{limited with} cannot be used in the
1194 project importing it. In particular, its packages cannot be renamed and
1195 its variables cannot be referred to.
1196
1197 @smallexample @c 0projectfile
1198 with "b.gpr";
1199 with "c.gpr";
1200 project A is
1201     For Exec_Dir use B'Exec_Dir; -- ok
1202 end A;
1203
1204 limited with "a.gpr";   --  Cyclic dependency: A -> B -> A
1205 project B is
1206    For Exec_Dir use A'Exec_Dir; -- not ok
1207 end B;
1208
1209 with "d.gpr";
1210 project C is
1211 end C;
1212
1213 limited with "a.gpr";  --  Cyclic dependency: A -> C -> D -> A
1214 project D is
1215    For Exec_Dir use A'Exec_Dir; -- not ok
1216 end D;
1217 @end smallexample
1218
1219 @c ---------------------------------------------
1220 @node Sharing Between Projects
1221 @subsection Sharing Between Projects
1222 @c ---------------------------------------------
1223
1224 @noindent
1225 When building an application, it is common to have similar needs in several of
1226 the projects corresponding to the subsystems under construction. For instance,
1227 they will all have the same compilation switches.
1228
1229 As seen before (@pxref{Tools Options in Project Files}), setting compilation
1230 switches for all sources of a subsystem is simple: it is just a matter of
1231 adding a @code{Compiler.Default_Switches} attribute to each project files with
1232 the same value. Of course, that means duplication of data, and both places need
1233 to be changed in order to recompile the whole application with different
1234 switches. It can become a real problem if there are many subsystems and thus
1235 many project files to edit.
1236
1237 There are two main approaches to avoiding this duplication:
1238
1239 @itemize @bullet
1240 @item Since @file{build.gpr} imports @file{logging.gpr}, we could change it
1241   to reference the attribute in Logging, either through a package renaming,
1242   or by referencing the attribute. The following example shows both cases:
1243
1244   @smallexample @c projectfile
1245   project Logging is
1246      package Compiler is
1247         for Switches ("Ada") use ("-O2");
1248      end Compiler;
1249      package Binder is
1250         for Switches ("Ada") use ("-E");
1251      end Binder;
1252   end Logging;
1253
1254   with "logging.gpr";
1255   project Build is
1256      package Compiler renames Logging.Compiler;
1257      package Binder is
1258         for Switches ("Ada") use Logging.Binder'Switches ("Ada");
1259      end Binder;
1260   end Build;
1261   @end smallexample
1262
1263   @noindent
1264   The solution used for @code{Compiler} gets the same value for all
1265   attributes of the package, but you cannot modify anything from the
1266   package (adding extra switches or some exceptions). The second
1267   version is more flexible, but more verbose.
1268
1269   If you need to refer to the value of a variable in an imported
1270   project, rather than an attribute, the syntax is similar but uses
1271   a "." rather than an apostrophe. For instance:
1272
1273   @smallexample @c projectfile
1274   with "imported";
1275   project Main is
1276      Var1 := Imported.Var;
1277   end Main;
1278   @end smallexample
1279
1280 @item The second approach is to define the switches in a third project.
1281   That project is setup without any sources (so that, as opposed to
1282   the first example, none of the project plays a special role), and
1283   will only be used to define the attributes. Such a project is
1284   typically called @file{shared.gpr}.
1285
1286   @smallexample @c projectfile
1287   abstract project Shared is
1288      for Source_Files use ();   --  no project
1289      package Compiler is
1290         for Switches ("Ada") use ("-O2");
1291      end Compiler;
1292   end Shared;
1293
1294   with "shared.gpr";
1295   project Logging is
1296      package Compiler renames Shared.Compiler;
1297   end Logging;
1298
1299   with "shared.gpr";
1300   project Build is
1301      package Compiler renames Shared.Compiler;
1302   end Build;
1303   @end smallexample
1304
1305   @noindent
1306   As for the first example, we could have chosen to set the attributes
1307   one by one rather than to rename a package. The reason we explicitly
1308   indicate that @code{Shared} has no sources is so that it can be created
1309   in any directory and we are sure it shares no sources with @code{Build}
1310   or @code{Logging}, which of course would be invalid.
1311
1312 @cindex project qualifier
1313   Note the additional use of the @b{abstract} qualifier in @file{shared.gpr}.
1314   This qualifier is optional, but helps convey the message that we do not
1315   intend this project to have sources (@pxref{Qualified Projects} for
1316   more qualifiers).
1317 @end itemize
1318
1319 @c ---------------------------------------------
1320 @node Global Attributes
1321 @subsection Global Attributes
1322 @c ---------------------------------------------
1323
1324 @noindent
1325 We have already seen many examples of attributes used to specify a special
1326 option of one of the tools involved in the build process. Most of those
1327 attributes are project specific. That it to say, they only affect the invocation
1328 of tools on the sources of the project where they are defined.
1329
1330 There are a few additional attributes that apply to all projects in a
1331 hierarchy as long as they are defined on the "main" project.
1332 The main project is the project explicitly mentioned on the command-line.
1333 The project hierarchy is the "with"-closure of the main project.
1334
1335 Here is a list of commonly used global attributes:
1336
1337 @table @asis
1338 @item @b{Builder.Global_Configuration_Pragmas}:
1339 @cindex @code{Global_Configuration_Pragmas}
1340   This attribute points to a file that contains configuration pragmas
1341   to use when building executables. These pragmas apply for all
1342   executables build from this project hierarchy. As we have seen before,
1343   additional pragmas can be specified on a per-project basis by setting the
1344   @code{Compiler.Local_Configuration_Pragmas} attribute.
1345
1346 @item @b{Builder.Global_Compilation_Switches}:
1347 @cindex @code{Global_Compilation_Switches}
1348   This attribute is a list of compiler switches to use when compiling any
1349   source file in the project hierarchy. These switches are used in addition
1350   to the ones defined in the @code{Compiler} package, which only apply to
1351   the sources of the corresponding project. This attribute is indexed on
1352   the name of the language.
1353
1354 @end table
1355
1356 Using such global capabilities is convenient. It can also lead to unexpected
1357 behavior. Especially when several subsystems are shared among different main
1358 projects and the different global attributes are not
1359 compatible. Note that using aggregate projects can be a safer and more powerful
1360 replacement to global attributes.
1361
1362 @c ---------------------------------------------
1363 @node Scenarios in Projects
1364 @section Scenarios in Projects
1365 @c ---------------------------------------------
1366
1367 @noindent
1368 Various aspects of the projects can be modified based on @b{scenarios}. These
1369 are user-defined modes that change the behavior of a project. Typical
1370 examples are the setup of platform-specific compiler options, or the use of
1371 a debug and a release mode (the former would activate the generation of debug
1372 information, when the second will focus on improving code optimization).
1373
1374 Let's enhance our example to support a debug and a release modes.The issue is to
1375 let the user choose what kind of system he is building:
1376 use @option{-g} as compiler switches in debug mode and @option{-O2}
1377 in release mode. We will also setup the projects so that we do not share the
1378 same object directory in both modes, otherwise switching from one to the other
1379 might trigger more recompilations than needed or mix objects from the 2 modes.
1380
1381 One naive approach is to create two different project files, say
1382 @file{build_debug.gpr} and @file{build_release.gpr}, that set the appropriate
1383 attributes as explained in previous sections. This solution does not scale well,
1384 because in presence of multiple projects depending on each other,
1385 you will also have to duplicate the complete hierarchy and adapt the project
1386 files to point to the right copies.
1387
1388 @cindex scenarios
1389 Instead, project files support the notion of scenarios controlled
1390 by external values. Such values can come from several sources (in decreasing
1391 order of priority):
1392
1393 @table @asis
1394 @item @b{Command line}:
1395 @cindex @option{-X}
1396   When launching @command{gnatmake} or @command{gprbuild}, the user can pass
1397   extra @option{-X} switches to define the external value. In
1398   our case, the command line might look like
1399
1400   @smallexample
1401        gnatmake -Pbuild.gpr -Xmode=debug
1402    or  gnatmake -Pbuild.gpr -Xmode=release
1403   @end smallexample
1404
1405 @item @b{^Environment variables^Logical names^}:
1406   When the external value does not come from the command line, it can come from
1407   the value of ^environment variables^logical names^ of the appropriate name.
1408   In our case, if ^an environment variable^a logical name^ called "mode"
1409   exist, its value will be taken into account.
1410
1411 @item @b{External function second parameter}
1412
1413 @end table
1414
1415 @cindex @code{external}
1416 We now need to get that value in the project. The general form is to use
1417 the predefined function @b{external} which returns the current value of
1418 the external. For instance, we could setup the object directory to point to
1419 either @file{obj/debug} or @file{obj/release} by changing our project to
1420
1421 @smallexample @c projectfile
1422    project Build is
1423        for Object_Dir use "obj/" & external ("mode", "debug");
1424        ... --  as before
1425    end Build;
1426 @end smallexample
1427
1428 @noindent
1429 The second parameter to @code{external} is optional, and is the default
1430 value to use if "mode" is not set from the command line or the environment.
1431
1432 In order to set the switches according to the different scenarios, other
1433 constructs have to be introduced such as typed variables and case statements.
1434
1435 @cindex typed variable
1436 @cindex case statement
1437 A @b{typed variable} is a variable that
1438 can take only a limited number of values, similar to an enumeration in Ada.
1439 Such a variable can then be used in a @b{case statement} and create conditional
1440 sections in the project. The following example shows how this can be done:
1441
1442 @smallexample @c projectfile
1443    project Build is
1444       type Mode_Type is ("debug", "release");  --  all possible values
1445       Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
1446
1447       package Compiler is
1448          case Mode is
1449             when "debug" =>
1450                for Switches ("Ada") use ("-g");
1451             when "release" =>
1452                for Switches ("Ada") use ("-O2");
1453          end case;
1454       end Compiler;
1455    end Build;
1456 @end smallexample
1457
1458 @noindent
1459 The project has suddenly grown in size, but has become much more flexible.
1460 @code{Mode_Type} defines the only valid values for the @code{mode} variable. If
1461 any other value is read from the environment, an error is reported and the
1462 project is considered as invalid.
1463
1464 The @code{Mode} variable is initialized with an external value
1465 defaulting to @code{"debug"}. This default could be omitted and that would
1466 force the user to define the value. Finally, we can use a case statement to set the
1467 switches depending on the scenario the user has chosen.
1468
1469 Most aspects of the projects can depend on scenarios. The notable exception
1470 are project dependencies (@code{with} clauses), which may not depend on a scenario.
1471
1472 Scenarios work the same way with @b{project hierarchies}: you can either
1473 duplicate a variable similar to @code{Mode} in each of the project (as long
1474 as the first argument to @code{external} is always the same and the type is
1475 the same), or simply set the variable in the @file{shared.gpr} project
1476 (@pxref{Sharing Between Projects}).
1477
1478 @c ---------------------------------------------
1479 @node Library Projects
1480 @section Library Projects
1481 @c ---------------------------------------------
1482
1483 @noindent
1484 So far, we have seen examples of projects that create executables. However,
1485 it is also possible to create libraries instead. A @b{library} is a specific
1486 type of subsystem where, for convenience, objects are grouped together
1487 using system-specific means such as archives or windows DLLs.
1488
1489 Library projects provide a system- and language-independent way of building both @b{static}
1490 and @b{dynamic} libraries. They also support the concept of @b{standalone
1491 libraries} (SAL) which offers two significant properties: the elaboration
1492 (e.g. initialization) of the library is either automatic or very simple;
1493 a change in the
1494 implementation part of the library implies minimal post-compilation actions on
1495 the complete system and potentially no action at all for the rest of the
1496 system in the case of dynamic SALs.
1497
1498 The GNAT Project Manager takes complete care of the library build, rebuild and
1499 installation tasks, including recompilation of the source files for which
1500 objects do not exist or are not up to date, assembly of the library archive, and
1501 installation of the library (i.e., copying associated source, object and
1502 @file{ALI} files to the specified location).
1503
1504 @menu
1505 * Building Libraries::
1506 * Using Library Projects::
1507 * Stand-alone Library Projects::
1508 * Installing a library with project files::
1509 @end menu
1510
1511 @c ---------------------------------------------
1512 @node Building Libraries
1513 @subsection Building Libraries
1514 @c ---------------------------------------------
1515
1516 @noindent
1517 Let's enhance our example and transform the @code{logging} subsystem into a
1518 library.  In order to do so, a few changes need to be made to @file{logging.gpr}.
1519 A number of specific attributes needs to be defined: at least @code{Library_Name}
1520 and @code{Library_Dir}; in addition, a number of other attributes can be used
1521 to specify specific aspects of the library. For readability, it is also
1522 recommended (although not mandatory), to use the qualifier @code{library} in
1523 front of the @code{project} keyword.
1524
1525 @table @asis
1526 @item @b{Library_Name}:
1527 @cindex @code{Library_Name}
1528   This attribute is the name of the library to be built. There is no
1529   restriction on the name of a library imposed by the project manager, except
1530   for stand-alone libraries whose names must follow the syntax of Ada
1531   identifiers; however, there may be system specific restrictions on the name.
1532   In general, it is recommended to stick to alphanumeric characters (and
1533   possibly single underscores) to help portability.
1534
1535 @item @b{Library_Dir}:
1536 @cindex @code{Library_Dir}
1537   This attribute  is the path (absolute or relative) of the directory where
1538   the library is to be installed. In the process of building a library,
1539   the sources are compiled, the object files end up  in the explicit or
1540   implicit @code{Object_Dir} directory. When all sources of a library
1541   are compiled, some of the compilation artifacts, including the library itself,
1542   are copied to the library_dir directory. This directory must exists and be
1543   writable. It must also be different from the object directory so that cleanup
1544   activities in the Library_Dir do not affect recompilation needs.
1545
1546 @end table
1547
1548 Here is the new version of @file{logging.gpr} that makes it a library:
1549
1550 @smallexample @c projectfile
1551 library project Logging is          --  "library" is optional
1552    for Library_Name use "logging";  --  will create "liblogging.a" on Unix
1553    for Object_Dir   use "obj";
1554    for Library_Dir  use "lib";      --  different from object_dir
1555 end Logging;
1556 @end smallexample
1557
1558 @noindent
1559 Once the above two attributes are defined, the library project is valid and
1560 is enough for building a library with default characteristics.
1561 Other library-related attributes can be used to change the defaults:
1562
1563 @table @asis
1564 @item @b{Library_Kind}:
1565 @cindex @code{Library_Kind}
1566   The value of this attribute must be either @code{"static"}, @code{"dynamic"} or
1567   @code{"relocatable"} (the latter is a synonym for dynamic). It indicates
1568   which kind of library should be build (the default is to build a
1569   static library, that is an archive of object files that can potentially
1570   be linked into a static executable). When the library is set to be dynamic,
1571   a separate image is created that will be loaded independently, usually
1572   at the start of the main program execution. Support for dynamic libraries is
1573   very platform specific, for instance on Windows it takes the form of a DLL
1574   while on GNU/Linux, it is a dynamic elf image whose suffix is usually
1575   @file{.so}. Library project files, on the other hand, can be written in
1576   a platform independent way so that the same project file can be used to build
1577   a library on different operating systems.
1578
1579   If you need to build both a static and a dynamic library, it is recommended
1580   use two different object directories, since in some cases some extra code
1581   needs to be generated for the latter. For such cases, one can
1582   either define two different project files, or a single one which uses scenarios
1583   to indicate at the various kinds of library to be build and their
1584   corresponding object_dir.
1585
1586 @cindex @code{Library_ALI_Dir}
1587 @item @b{Library_ALI_Dir}:
1588   This attribute may be specified to indicate the directory where the ALI
1589   files of the library are installed. By default, they are copied into the
1590   @code{Library_Dir} directory, but as for the executables where we have a
1591   separate @code{Exec_Dir} attribute, you might want to put them in a separate
1592   directory since there can be hundreds of them. The same restrictions as for
1593   the @code{Library_Dir} attribute apply.
1594
1595 @cindex @code{Library_Version}
1596 @item @b{Library_Version}:
1597   This attribute is platform dependent, and has no effect on VMS and Windows.
1598   On Unix, it is used only for dynamic libraries as the internal
1599   name of the library (the @code{"soname"}). If the library file name (built
1600   from the @code{Library_Name}) is different from the @code{Library_Version},
1601   then the library file will be a symbolic link to the actual file whose name
1602   will be @code{Library_Version}. This follows the usual installation schemes
1603   for dynamic libraries on many Unix systems.
1604
1605 @smallexample @c projectfile
1606 @group
1607   project Logging is
1608      Version := "1";
1609      for Library_Dir use "lib";
1610      for Library_Name use "logging";
1611      for Library_Kind use "dynamic";
1612      for Library_Version use "liblogging.so." & Version;
1613   end Logging;
1614 @end group
1615 @end smallexample
1616
1617   @noindent
1618   After the compilation, the directory @file{lib} will contain both a
1619   @file{libdummy.so.1} library and a symbolic link to it called
1620   @file{libdummy.so}.
1621
1622 @cindex @code{Library_GCC}
1623 @item @b{Library_GCC}:
1624   This attribute is the name of the tool to use instead of "gcc" to link shared
1625   libraries. A common use of this attribute is to define a wrapper script that
1626   accomplishes specific actions before calling gcc (which itself is calling the
1627   linker to build the library image).
1628
1629 @item @b{Library_Options}:
1630 @cindex @code{Library_Options}
1631   This attribute may be used to specify additional switches (last switches)
1632   when linking a shared library.
1633
1634 @item @b{Leading_Library_Options}:
1635 @cindex @code{Leading_Library_Options}
1636   This attribute, that is taken into account only by @command{gprbuild}, may be
1637   used to specified leading options (first switches) when linking a shared
1638   library.
1639
1640 @cindex @code{Linker_Options}
1641 @item @b{Linker.Linker_Options}:
1642   This attribute specifies additional switches to be given to the linker when
1643   linking an executable. It is ignored when defined in the main project and
1644   taken into account in all other projects that are imported directly or
1645   indirectly. These switches complement the @code{Linker.Switches}
1646   defined in the main project. This is useful when a particular subsystem
1647   depends on an external library: adding this dependency as a
1648   @code{Linker_Options} in the project of the subsystem is more convenient than
1649   adding it to all the @code{Linker.Switches} of the main projects that depend
1650   upon this subsystem.
1651 @end table
1652
1653 @c ---------------------------------------------
1654 @node Using Library Projects
1655 @subsection Using Library Projects
1656 @c ---------------------------------------------
1657
1658 @noindent
1659 When the builder detects that a project file is a library project file, it
1660 recompiles all sources of the project that need recompilation and rebuild the
1661 library if any of the sources have been recompiled. It then groups all object
1662 files into a single file, which is a shared or a static library. This library
1663 can later on be linked with multiple executables. Note that the use
1664 of shard libraries reduces the size of the final executable and can also reduce
1665 the memory footprint at execution time when the library is shared among several
1666 executables.
1667
1668 It is also possible to build @b{multi-language libraries}. When using
1669 @command{gprbuild} as a builder, multi-language library projects allow naturally
1670 the creation of multi-language libraries . @command{gnatmake}, does not try to
1671 compile non Ada sources. However, when the project is multi-language, it will
1672 automatically link all object files found in the object directory, whether or
1673 not they were compiled from an Ada source file. This specific behavior does not
1674 apply to Ada-only projects which only take into account the objects
1675 corresponding to the sources of the project.
1676
1677 A non-library project can import a library project. When the builder is invoked
1678 on the former, the library of the latter is only rebuilt when absolutely
1679 necessary. For instance, if a unit of the
1680 library is not up-to-date but non of the executables need this unit, then the
1681 unit is not recompiled and the library is not reassembled.
1682 For instance, let's assume in our example that logging has the following
1683 sources: @file{log1.ads}, @file{log1.adb}, @file{log2.ads} and
1684 @file{log2.adb}. If @file{log1.adb} has been modified, then the library
1685 @file{liblogging} will be rebuilt when compiling all the sources of
1686 @code{Build} only if @file{proc.ads}, @file{pack.ads} or @file{pack.adb}
1687 include a @code{"with Log1"}.
1688
1689 To ensure that all the sources in the @code{Logging} library are
1690 up to date, and that all the sources of @code{Build} are also up to date,
1691 the following two commands needs to be used:
1692
1693 @smallexample
1694 gnatmake -Plogging.gpr
1695 gnatmake -Pbuild.gpr
1696 @end smallexample
1697
1698 @noindent
1699 All @file{ALI} files will also be copied from the object directory to the
1700 library directory. To build executables, @command{gnatmake} will use the
1701 library rather than the individual object files.
1702
1703 @ifclear vms
1704 Library projects can also be useful to describe a library that need to be used
1705 but, for some reason, cannot be rebuilt. For instance, it is the case when some
1706 of the library sources are not available. Such library projects need simply to
1707 use the @code{Externally_Built} attribute as in the example below:
1708
1709 @smallexample @c projectfile
1710 library project Extern_Lib is
1711    for Languages    use ("Ada", "C");
1712    for Source_Dirs  use ("lib_src");
1713    for Library_Dir  use "lib2";
1714    for Library_Kind use "dynamic";
1715    for Library_Name use "l2";
1716    for Externally_Built use "true";  --  <<<<
1717 end Extern_Lib;
1718 @end smallexample
1719
1720 @noindent
1721 In the case of externally built libraries, the @code{Object_Dir}
1722 attribute does not need to be specified because it will never be
1723 used.
1724
1725 The main effect of using such an externally built library project is mostly to
1726 affect the linker command in order to reference the desired library. It can
1727 also be achieved by using @code{Linker.Linker_Options} or @code{Linker.Switches}
1728 in the project corresponding to the subsystem needing this external library.
1729 This latter method is more straightforward in simple cases but when several
1730 subsystems depend upon the same external library, finding the proper place
1731 for the @code{Linker.Linker_Options} might not be easy and if it is
1732 not placed properly, the final link command is likely to present ordering issues.
1733 In such a situation, it is better to use the externally built library project
1734 so that all other subsystems depending on it can declare this dependency thanks
1735 to a project @code{with} clause, which in turn will trigger the builder to find
1736 the proper order of libraries in the final link command.
1737 @end ifclear
1738
1739 @c ---------------------------------------------
1740 @node Stand-alone Library Projects
1741 @subsection Stand-alone Library Projects
1742 @c ---------------------------------------------
1743
1744 @noindent
1745 @cindex standalone libraries
1746 A @b{stand-alone library} is a library that contains the necessary code to
1747 elaborate the Ada units that are included in the library. A stand-alone
1748 library is a convenient way to add an Ada subsystem to a more global system
1749 whose main is not in Ada since it makes the elaboration of the Ada part mostly
1750 transparent. However, stand-alone libraries are also useful when the main is in
1751 Ada: they provide a means for minimizing relinking & redeployment of complex
1752 systems when localized changes are made.
1753
1754 The name of a stand-alone library, specified with attribute
1755 @code{Library_Name}, must have the syntax of an Ada identifier.
1756
1757 The most prominent characteristic of a stand-alone library is that it offers a
1758 distinction between interface units and implementation units. Only the former
1759 are visible to units outside the library. A stand-alone library project is thus
1760 characterised by a third attribute, usually @b{Library_Interface}, in addition
1761 to the two attributes that make a project a Library Project
1762 (@code{Library_Name} and @code{Library_Dir}). This third attribute may also be
1763 @b{Interfaces}. @b{Library_Interface} only works when the interface is in Ada
1764 and takes a list of units as parameter. @b{Interfaces} works for any supported
1765 language and takes a list of sources as parameter.
1766
1767 @table @asis
1768 @item @b{Library_Interface}:
1769 @cindex @code{Library_Interface}
1770   This attribute defines an explicit subset of the units of the project. Units
1771   from projects importing this library project may only "with" units whose
1772   sources are listed in the @code{Library_Interface}. Other sources are
1773   considered implementation units.
1774
1775 @smallexample @c projectfile
1776 @group
1777      for Library_Dir use "lib";
1778      for Library_Name use "loggin";
1779      for Library_Interface use ("lib1", "lib2");  --  unit names
1780 @end group
1781 @end smallexample
1782
1783 @item @b{Interfaces}
1784   This attribute defines an explicit subset of the source files of a project.
1785   Sources from projects importing this project, can only depend on sources from
1786   this subset. This attribute can be used on non library projects. It can also
1787   be used as a replacement for attribute @code{Library_Interface}, in which
1788   case, units have to be replaced by source files. For multi-language library
1789   projects, it is the only way to make the project a Stand-Alone Library project
1790   whose interface is not purely Ada.
1791
1792 @item @b{Library_Standalone}:
1793 @cindex @code{Library_Standalone}
1794   This attribute defines the kind of standalone library to
1795   build. Values are either @code{standard} (the default), @code{no} or
1796   @code{encapsulated}. When @code{standard} is used the code to elaborate and
1797   finalize the library is embedded, when @code{encapsulated} is used the
1798   library can furthermore only depends on static libraries (including
1799   the GNAT runtime). This attribute can be set to @code{no} to make it clear
1800   that the library should not be standalone in which case the
1801   @code{Library_Interface} should not defined.
1802
1803 @smallexample @c projectfile
1804 @group
1805      for Library_Dir use "lib";
1806      for Library_Name use "loggin";
1807      for Library_Interface use ("lib1", "lib2");  --  unit names
1808      for Library_Standalone use "encapsulated";
1809 @end group
1810 @end smallexample
1811
1812 @end table
1813
1814 In order to include the elaboration code in the stand-alone library, the binder
1815 is invoked on the closure of the library units creating a package whose name
1816 depends on the library name (^b~logging.ads/b^B$LOGGING.ADS/B^ in the example).
1817 This binder-generated package includes @b{initialization} and @b{finalization}
1818 procedures whose names depend on the library name (@code{logginginit} and
1819 @code{loggingfinal} in the example). The object corresponding to this package is
1820 included in the library.
1821
1822 @table @asis
1823 @item @b{Library_Auto_Init}:
1824 @cindex @code{Library_Auto_Init}
1825   A dynamic stand-alone Library is automatically initialized
1826   if automatic initialization of Stand-alone Libraries is supported on the
1827   platform and if attribute @b{Library_Auto_Init} is not specified or
1828   is specified with the value "true". A static Stand-alone Library is never
1829   automatically initialized. Specifying "false" for this attribute
1830   prevent automatic initialization.
1831
1832   When a non-automatically initialized stand-alone library is used in an
1833   executable, its initialization procedure must be called before any service of
1834   the library is used. When the main subprogram is in Ada, it may mean that the
1835   initialization procedure has to be called during elaboration of another
1836   package.
1837
1838 @item @b{Library_Dir}:
1839 @cindex @code{Library_Dir}
1840   For a stand-alone library, only the @file{ALI} files of the interface units
1841   (those that are listed in attribute @code{Library_Interface}) are copied to
1842   the library directory. As a consequence, only the interface units may be
1843   imported from Ada units outside of the library. If other units are imported,
1844   the binding phase will fail.
1845
1846 @item @b{Binder.Default_Switches}:
1847   When a stand-alone library is bound, the switches that are specified in
1848   the attribute @b{Binder.Default_Switches ("Ada")} are
1849   used in the call to @command{gnatbind}.
1850
1851 @item @b{Library_Src_Dir}:
1852 @cindex @code{Library_Src_Dir}
1853   This attribute defines the location (absolute or relative to the project
1854   directory) where the sources of the interface units are copied at
1855   installation time.
1856   These sources includes the specs of the interface units along with the closure
1857   of sources necessary to compile them successfully. That may include bodies and
1858   subunits, when pragmas @code{Inline} are used, or when there is a generic
1859   units in the spec. This directory cannot point to the object directory or
1860   one of the source directories, but it can point to the library directory,
1861   which is the default value for this attribute.
1862
1863 @item @b{Library_Symbol_Policy}:
1864 @cindex @code{Library_Symbol_Policy}
1865   This attribute controls the export of symbols and, on some platforms (like
1866   VMS) that have the notions of major and minor IDs built in the library
1867   files, it controls the setting of these IDs. It is not supported on all
1868   platforms (where it will just have no effect). It may have one of the
1869   following values:
1870
1871   @itemize -
1872   @item @code{"autonomous"} or @code{"default"}: exported symbols are not controlled
1873   @item @code{"compliant"}: if attribute @b{Library_Reference_Symbol_File}
1874      is not defined, then it is equivalent to policy "autonomous". If there
1875      are exported symbols in the reference symbol file that are not in the
1876      object files of the interfaces, the major ID of the library is increased.
1877      If there are symbols in the object files of the interfaces that are not
1878      in the reference symbol file, these symbols are put at the end of the list
1879      in the newly created symbol file and the minor ID is increased.
1880   @item @code{"controlled"}: the attribute @b{Library_Reference_Symbol_File} must be
1881      defined. The library will fail to build if the exported symbols in the
1882      object files of the interfaces do not match exactly the symbol in the
1883      symbol file.
1884   @item @code{"restricted"}: The attribute @b{Library_Symbol_File} must be defined.
1885      The library will fail to build if there are symbols in the symbol file that
1886      are not in the exported symbols of the object files of the interfaces.
1887      Additional symbols in the object files are not added to the symbol file.
1888   @item @code{"direct"}: The attribute @b{Library_Symbol_File} must be defined and
1889      must designate an existing file in the object directory. This symbol file
1890      is passed directly to the underlying linker without any symbol processing.
1891
1892   @end itemize
1893
1894 @item @b{Library_Reference_Symbol_File}
1895 @cindex @code{Library_Reference_Symbol_File}
1896   This attribute may define the path name of a reference symbol file that is
1897   read when the symbol policy is either "compliant" or "controlled", on
1898   platforms that support symbol control, such as VMS, when building a
1899   stand-alone library. The path may be an absolute path or a path relative
1900   to the project directory.
1901
1902 @item @b{Library_Symbol_File}
1903 @cindex @code{Library_Symbol_File}
1904   This attribute may define the name of the symbol file to be created when
1905   building a stand-alone library when the symbol policy is either "compliant",
1906   "controlled" or "restricted", on platforms that support symbol control,
1907   such as VMS. When symbol policy is "direct", then a file with this name
1908   must exist in the object directory.
1909 @end table
1910
1911 @c ---------------------------------------------
1912 @node Installing a library with project files
1913 @subsection Installing a library with project files
1914 @c ---------------------------------------------
1915
1916 @noindent
1917 When using project files, library installation is part of the library build
1918 process. Thus no further action is needed in order to make use of the
1919 libraries that are built as part of the general application build. A usable
1920 version of the library is installed in the directory specified by the
1921 @code{Library_Dir} attribute of the library project file.
1922
1923 You may want to install a library in a context different from where the library
1924 is built. This situation arises with third party suppliers, who may want
1925 to distribute a library in binary form where the user is not expected to be
1926 able to recompile the library. The simplest option in this case is to provide
1927 a project file slightly different from the one used to build the library, by
1928 using the @code{externally_built} attribute. @ref{Using Library Projects}
1929
1930 @c ---------------------------------------------
1931 @node Project Extension
1932 @section Project Extension
1933 @c ---------------------------------------------
1934
1935 @noindent
1936 During development of a large system, it is sometimes necessary to use
1937 modified versions of some of the source files, without changing the original
1938 sources. This can be achieved through the @b{project extension} facility.
1939
1940 Suppose for instance that our example @code{Build} project is build every night
1941 for the whole team, in some shared directory. A developer usually need to work
1942 on a small part of the system, and might not want to have a copy of all the
1943 sources and all the object files (mostly because that would require too much
1944 disk space, time to recompile everything). He prefers to be able to override
1945 some of the source files in his directory, while taking advantage of all the
1946 object files generated at night.
1947
1948 Another example can be taken from large software systems, where it is common to have
1949 multiple implementations of a common interface; in Ada terms, multiple
1950 versions of a package body for the same spec.  For example, one implementation
1951 might be safe for use in tasking programs, while another might only be used
1952 in sequential applications.  This can be modeled in GNAT using the concept
1953 of @emph{project extension}.  If one project (the ``child'') @emph{extends}
1954 another project (the ``parent'') then by default all source files of the
1955 parent project are inherited by the child, but the child project can
1956 override any of the parent's source files with new versions, and can also
1957 add new files or remove unnecessary ones.
1958 This facility is the project analog of a type extension in
1959 object-oriented programming.  Project hierarchies are permitted (an extending
1960 project may itself be extended), and a project that
1961 extends a project can also import other projects.
1962
1963 A third example is that of using project extensions to provide different
1964 versions of the same system. For instance, assume that a @code{Common}
1965 project is used by two development branches. One of the branches has now
1966 been frozen, and no further change can be done to it or to @code{Common}.
1967 However, the other development branch still needs evolution of @code{Common}.
1968 Project extensions provide a flexible solution to create a new version
1969 of a subsystem while sharing and reusing as much as possible from the original
1970 one.
1971
1972 A project extension inherits implicitly all the sources and objects from the
1973 project it extends. It is possible to create a new version of some of the
1974 sources in one of the additional source dirs of the extending project. Those new
1975 versions hide the original versions. Adding new sources or removing existing
1976 ones is also possible. Here is an example on how to extend the project
1977 @code{Build} from previous examples:
1978
1979 @smallexample @c projectfile
1980    project Work extends "../bld/build.gpr" is
1981    end Work;
1982 @end smallexample
1983
1984 @noindent
1985 The project after @b{extends} is the one being extended. As usual, it can be
1986 specified using an absolute path, or a path relative to any of the directories
1987 in the project path (@pxref{Project Dependencies}). This project does not
1988 specify source or object directories, so the default value for these attribute
1989 will be used that is to say the current directory (where project @code{Work} is
1990 placed). We can already compile that project with
1991
1992 @smallexample
1993    gnatmake -Pwork
1994 @end smallexample
1995
1996 @noindent
1997 If no sources have been placed in the current directory, this command
1998 won't do anything, since this project does not change the
1999 sources it inherited from @code{Build}, therefore all the object files
2000 in @code{Build} and its dependencies are still valid and are reused
2001 automatically.
2002
2003 Suppose we now want to supply an alternate version of @file{pack.adb}
2004 but use the existing versions of @file{pack.ads} and @file{proc.adb}.
2005 We can create the new file Work's current directory  (likely
2006 by copying the one from the @code{Build} project and making changes to
2007 it. If new packages are needed at the same time, we simply create
2008 new files in the source directory of the extending project.
2009
2010 When we recompile, @command{gnatmake} will now automatically recompile
2011 this file (thus creating @file{pack.o} in the current directory) and
2012 any file that depends on it (thus creating @file{proc.o}). Finally, the
2013 executable is also linked locally.
2014
2015 Note that we could have obtained the desired behavior using project import
2016 rather than project inheritance. A @code{base} project would contain the
2017 sources for @file{pack.ads} and @file{proc.adb}, and @code{Work} would
2018 import @code{base} and add @file{pack.adb}. In this scenario,  @code{base}
2019 cannot contain the original version of @file{pack.adb} otherwise there would be
2020 2 versions of the same unit in the closure of the project and this is not
2021 allowed. Generally speaking, it is not recommended to put the spec and the
2022 body of a unit in different projects since this affects their autonomy and
2023 reusability.
2024
2025 In a project file that extends another project, it is possible to
2026 indicate that an inherited source is @b{not part} of the sources of the
2027 extending project. This is necessary sometimes when a package spec has
2028 been overridden and no longer requires a body: in this case, it is
2029 necessary to indicate that the inherited body is not part of the sources
2030 of the project, otherwise there will be a compilation error
2031 when compiling the spec.
2032
2033 @cindex @code{Excluded_Source_Files}
2034 @cindex @code{Excluded_Source_List_File}
2035 For that purpose, the attribute @b{Excluded_Source_Files} is used.
2036 Its value is a list of file names.
2037 It is also possible to use attribute @code{Excluded_Source_List_File}.
2038 Its value is the path of a text file containing one file name per
2039 line.
2040
2041 @smallexample @c @projectfile
2042 project Work extends "../bld/build.gpr" is
2043    for Source_Files use ("pack.ads");
2044    --  New spec of Pkg does not need a completion
2045    for Excluded_Source_Files use ("pack.adb");
2046 end Work;
2047 @end smallexample
2048
2049 @noindent
2050 All packages that are not declared in the extending project are inherited from
2051 the project being extended, with their attributes, with the exception of
2052 @code{Linker'Linker_Options} which is never inherited. In particular, an
2053 extending project retains all the switches specified in the project being
2054 extended.
2055
2056 At the project level, if they are not declared in the extending project, some
2057 attributes are inherited from the project being extended. They are:
2058 @code{Languages}, @code{Main} (for a root non library project) and
2059 @code{Library_Name} (for a project extending a library project)
2060
2061 @menu
2062 * Project Hierarchy Extension::
2063 @end menu
2064
2065 @c ---------------------------------------------
2066 @node Project Hierarchy Extension
2067 @subsection Project Hierarchy Extension
2068 @c ---------------------------------------------
2069
2070 @noindent
2071 One of the fundamental restrictions in project extension is the following:
2072 @b{A project is not allowed to import directly or indirectly at the same time an
2073 extending project and one of its ancestors}.
2074
2075 By means of example, consider the following hierarchy of projects.
2076
2077 @smallexample
2078    a.gpr  contains package A1
2079    b.gpr, imports a.gpr and contains B1, which depends on A1
2080    c.gpr, imports b.gpr and contains C1, which depends on B1
2081 @end smallexample
2082
2083 @noindent
2084 If we want to locally extend the packages @code{A1} and @code{C1}, we need to
2085 create several extending projects:
2086
2087 @smallexample
2088    a_ext.gpr which extends a.gpr, and overrides A1
2089    b_ext.gpr which extends b.gpr and imports a_ext.gpr
2090    c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
2091 @end smallexample
2092
2093 @noindent
2094 @smallexample @c projectfile
2095    project A_Ext extends "a.gpr" is
2096       for Source_Files use ("a1.adb", "a1.ads");
2097    end A_Ext;
2098
2099    with "a_ext.gpr";
2100    project B_Ext extends "b.gpr" is
2101    end B_Ext;
2102
2103    with "b_ext.gpr";
2104    project C_Ext extends "c.gpr" is
2105       for Source_Files use ("c1.adb");
2106    end C_Ext;
2107 @end smallexample
2108
2109 @noindent
2110 The extension @file{b_ext.gpr} is required, even though we are not overriding
2111 any of the sources of @file{b.gpr} because otherwise @file{c_expr.gpr} would
2112 import @file{b.gpr} which itself knows nothing about @file{a_ext.gpr}.
2113
2114 @cindex extends all
2115 When extending a large system spanning multiple projects, it is often
2116 inconvenient to extend every project in the hierarchy that is impacted by a
2117 small change introduced in a low layer. In such cases, it is possible to create
2118 an @b{implicit extension} of entire hierarchy using @b{extends all}
2119 relationship.
2120
2121 When the project is extended using @code{extends all} inheritance, all projects
2122 that are imported by it, both directly and indirectly, are considered virtually
2123 extended. That is, the project manager creates implicit projects
2124 that extend every project in the hierarchy; all these implicit projects do not
2125 control sources on their own and use the object directory of
2126 the "extending all" project.
2127
2128 It is possible to explicitly extend one or more projects in the hierarchy
2129 in order to modify the sources. These extending projects must be imported by
2130 the "extending all" project, which will replace the corresponding virtual
2131 projects with the explicit ones.
2132
2133 When building such a project hierarchy extension, the project manager will
2134 ensure that both modified sources and sources in implicit extending projects
2135 that depend on them, are recompiled.
2136
2137 Thus, in our example we could create the following projects instead:
2138
2139 @smallexample
2140    a_ext.gpr, extends a.gpr and overrides A1
2141    c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
2142
2143 @end smallexample
2144
2145 @noindent
2146 @smallexample @c projectfile
2147    project A_Ext extends "a.gpr" is
2148       for Source_Files use ("a1.adb", "a1.ads");
2149    end A_Ext;
2150
2151    with "a_ext.gpr";
2152    project C_Ext extends all "c.gpr" is
2153      for Source_Files use ("c1.adb");
2154    end C_Ext;
2155 @end smallexample
2156
2157 @noindent
2158 When building project @file{c_ext.gpr}, the entire modified project space is
2159 considered for recompilation, including the sources of @file{b.gpr} that are
2160 impacted by the changes in @code{A1} and @code{C1}.
2161
2162 @c ---------------------------------------------
2163 @node Aggregate Projects
2164 @section Aggregate Projects
2165 @c ---------------------------------------------
2166
2167 @noindent
2168
2169 Aggregate projects are an extension of the project paradigm, and are
2170 meant to solve a few specific use cases that cannot be solved directly
2171 using standard projects. This section will go over a few of these use
2172 cases to try and explain what you can use aggregate projects for.
2173
2174 @menu
2175 * Building all main programs from a single project tree::
2176 * Building a set of projects with a single command::
2177 * Define a build environment::
2178 * Performance improvements in builder::
2179 * Syntax of aggregate projects::
2180 * package Builder in aggregate projects::
2181 @end menu
2182
2183 @c -----------------------------------------------------------
2184 @node Building all main programs from a single project tree
2185 @subsection Building all main programs from a single project tree
2186 @c -----------------------------------------------------------
2187
2188 Most often, an application is organized into modules and submodules,
2189 which are very conveniently represented as a project tree or graph
2190 (the root project A @code{with}s the projects for each modules (say B and C),
2191 which in turn @code{with} projects for submodules.
2192
2193 Very often, modules will build their own executables (for testing
2194 purposes for instance), or libraries (for easier reuse in various
2195 contexts).
2196
2197 However, if you build your project through gnatmake or gprbuild, using
2198 a syntax similar to
2199
2200 @smallexample
2201    gprbuild -PA.gpr
2202 @end smallexample
2203
2204 this will only rebuild the main programs of project A, not those of the
2205 imported projects B and C. Therefore you have to spawn several
2206 gnatmake commands, one per project, to build all executables.
2207 This is a little inconvenient, but more importantly is inefficient
2208 (since gnatmake needs to do duplicate work to ensure that sources are
2209 up-to-date, and cannot easily compile things in parallel when using
2210 the -j switch).
2211
2212 Also libraries are always rebuild when building a project.
2213
2214 You could therefore define an aggregate project Agg that groups A, B
2215 and C. Then, when you build with
2216
2217 @smallexample
2218     gprbuild -PAgg.gpr
2219 @end smallexample
2220
2221 this will build all mains from A, B and C.
2222
2223 @smallexample @c projectfile
2224    aggregate project Agg is
2225       for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2226    end Agg;
2227 @end smallexample
2228
2229 If B or C do not define any main program (through their Main
2230 attribute), all their sources are build. When you do not group them
2231 in the aggregate project, only those sources that are needed by A
2232 will be build.
2233
2234 If you add a main to a project P not already explicitly referenced in the
2235 aggregate project, you will need to add "p.gpr" in the list of project
2236 files for the aggregate project, or the main will not be built when
2237 building the aggregate project.
2238
2239 @c ---------------------------------------------------------
2240 @node Building a set of projects with a single command
2241 @subsection Building a set of projects with a single command
2242 @c ---------------------------------------------------------
2243
2244 One other case is when you have multiple applications and libraries
2245 that are build independently from each other (but they can be build in
2246 parallel). For instance, you have a project tree rooted at A, and
2247 another one (which might share some subprojects) rooted at B.
2248
2249 Using only gprbuild, you could do
2250
2251 @smallexample
2252   gprbuild -PA.gpr
2253   gprbuild -PB.gpr
2254 @end smallexample
2255
2256 to build both. But again, gprbuild has to do some duplicate work for
2257 those files that are shared between the two, and cannot truly build
2258 things in parallel efficiently.
2259
2260 If the two projects are really independent, share no sources other
2261 than through a common subproject, and have no source files with a
2262 common basename, you could create a project C that imports A and
2263 B. But these restrictions are often too strong, and one has to build
2264 them independently. An aggregate project does not have these
2265 limitations, and can aggregate two project trees that have common
2266 sources.
2267
2268 @smallexample
2269 Aggregate projects can group projects with duplicate file names
2270 @end smallexample
2271
2272 This scenario is particularly useful in environment like VxWork 653
2273 where the applications running in the multiple partitions can be build
2274 in parallel through a single gprbuild command. This also works nicely
2275 with Annex E.
2276
2277 @smallexample
2278    Aggregate projects can be used to build multiple partitions
2279 @end smallexample
2280
2281 @c ---------------------------------------------
2282 @node Define a build environment
2283 @subsection Define a build environment
2284 @c ---------------------------------------------
2285
2286 The environment variables at the time you launch gprbuild or gprbuild
2287 will influence the view these tools have of the project (PATH to find
2288 the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
2289 projects, environment variables that are referenced in project files
2290 through the "external" statement,...). Several command line switches
2291 can be used to override those (-X or -aP), but on some systems and
2292 with some projects, this might make the command line too long, and on
2293 all systems often make it hard to read.
2294
2295 An aggregate project can be used to set the environment for all
2296 projects build through that aggregate. One of the nice aspects is that
2297 you can put the aggregate project under configuration management, and
2298 make sure all your user have a consistent environment when
2299 building. The syntax looks like
2300
2301 @smallexample @c projectfile
2302    aggregate project Agg is
2303       for Project_Files use ("A.gpr", "B.gpr");
2304       for Project_Path use ("../dir1", "../dir1/dir2");
2305       for External ("BUILD") use "PRODUCTION";
2306
2307       package Builder is
2308          for Switches ("Ada") use ("-q");
2309       end Builder;
2310    end Agg;
2311 @end smallexample
2312
2313 One of the often requested features in projects is to be able to
2314 reference external variables in @code{with} statements, as in
2315
2316 @smallexample @c projectfile
2317   with external("SETUP") & "path/prj.gpr";   --  ILLEGAL
2318   project MyProject is
2319      ...
2320   end MyProject;
2321 @end smallexample
2322
2323 For various reasons, this isn't authorized. But using aggregate
2324 projects provide an elegant solution. For instance, you could
2325 use a project file like:
2326
2327 @smallexample @c projectfile
2328 aggregate project Agg is
2329     for Project_Path use (external("SETUP") % "path");
2330     for Project_Files use ("myproject.gpr");
2331 end Agg;
2332
2333 with "prj.gpr";  --  searched on Agg'Project_Path
2334 project MyProject is
2335    ...
2336 end MyProject;
2337 @end smallexample
2338
2339 @c --------------------------------------------
2340 @node Performance improvements in builder
2341 @subsection Performance improvements in builder
2342 @c --------------------------------------------
2343
2344 The loading of aggregate projects is optimized in gprbuild and
2345 gnatmake, so that all files are searched for only once on the disk
2346 (thus reducing the number of system calls and contributing to faster
2347 compilation times especially on systems with sources on remote
2348 servers). As part of the loading, gprbuild and gnatmake compute how
2349 and where a source file should be compiled, and even if it is found
2350 several times in the aggregated projects it will be compiled only
2351 once.
2352
2353 Since there is no ambiguity as to which switches should be used, files
2354 can be compiled in parallel (through the usual -j switch) and this can
2355 be done while maximizing the use of CPUs (compared to launching
2356 multiple gprbuild and gnatmake commands in parallel).
2357
2358 @c -------------------------------------
2359 @node Syntax of aggregate projects
2360 @subsection Syntax of aggregate projects
2361 @c -------------------------------------
2362
2363 An aggregate project follows the general syntax of project files. The
2364 recommended extension is still @file{.gpr}. However, a special
2365 @code{aggregate} qualifier must be put before the keyword
2366 @code{project}.
2367
2368 An aggregate project cannot @code{with} any other project (standard or
2369 aggregate), except an abstract project which can be used to share
2370 attribute values. Building other aggregate projects from an aggregate
2371 project is done through the Project_Files attribute (see below).
2372
2373 An aggregate project does not have any source files directly (only
2374 through other standard projects). Therefore a number of the standard
2375 attributes and packages are forbidden in an aggregate project. Here is the
2376 (non exhaustive) list:
2377
2378 @itemize @bullet
2379 @item Languages
2380 @item Source_Files, Source_List_File and other attributes dealing with
2381   list of sources.
2382 @item Source_Dirs, Exec_Dir and Object_Dir
2383 @item Library_Dir, Library_Name and other library-related attributes
2384 @item Main
2385 @item Roots
2386 @item Externally_Built
2387 @item Inherit_Source_Path
2388 @item Excluded_Source_Dirs
2389 @item Locally_Removed_Files
2390 @item Excluded_Source_Files
2391 @item Excluded_Source_List_File
2392 @item Interfaces
2393 @end itemize
2394
2395 The only package that is authorized (albeit optional) is
2396 Builder. Other packages (in particular Compiler, Binder and Linker)
2397 are forbidden. It is an error to have any of these
2398 (and such an error prevents the proper loading of the aggregate
2399 project).
2400
2401 Three new attributes have been created, which can only be used in the
2402 context of aggregate projects:
2403
2404 @table @asis
2405 @item @b{Project_Files}:
2406 @cindex @code{Project_Files}
2407
2408 This attribute is compulsory (or else we are not aggregating any project,
2409 and thus not doing anything). It specifies a list of @file{.gpr} files
2410 that are grouped in the aggregate. The list may be empty. The project
2411 files can be either other aggregate projects, or standard projects. When
2412 grouping standard projects, you can have both the root of a project tree
2413 (and you do not need to specify all its imported projects), and any project
2414 within the tree.
2415
2416 Basically, the idea is to specify all those projects that have
2417 main programs you want to build and link, or libraries you want to
2418 build. You can even specify projects that do not use the Main
2419 attribute nor the @code{Library_*} attributes, and the result will be to
2420 build all their source files (not just the ones needed by other
2421 projects).
2422
2423 The file can include paths (absolute or relative). Paths are
2424 relative to the location of the aggregate project file itself (if
2425 you use a base name, we expect to find the .gpr file in the same
2426 directory as the aggregate project file). The extension @file{.gpr} is
2427 mandatory, since this attribute contains file names, not project names.
2428
2429 Paths can also include the @code{"*"} and @code{"**"} globbing patterns. The
2430 latter indicates that any subdirectory (recursively) will be
2431 searched for matching files. The latter (@code{"**"}) can only occur at the
2432 last position in the directory part (ie @code{"a/**/*.gpr"} is supported, but
2433 not @code{"**/a/*.gpr"}). Starting the pattern with @code{"**"} is equivalent
2434 to starting with @code{"./**"}.
2435
2436 For now, the pattern @code{"*"} is only allowed in the filename part, not
2437 in the directory part. This is mostly for efficiency reasons to limit the
2438 number of system calls that are needed.
2439
2440 Here are a few valid examples:
2441
2442 @smallexample @c projectfile
2443     for Project_Files use ("a.gpr", "subdir/b.gpr");
2444     --  two specific projects relative to the directory of agg.gpr
2445
2446     for Project_Files use ("**/*.gpr");
2447     --  all projects recursively
2448 @end smallexample
2449
2450 @item @b{Project_Path}:
2451 @cindex @code{Project_Path}
2452
2453 This attribute can be used to specify a list of directories in
2454 which to look for project files in @code{with} statements.
2455
2456 When you specify a project in Project_Files
2457 say @code{"x/y/a.gpr"}), and this projects imports a project "b.gpr", only
2458 b.gpr is searched in the project path. a.gpr must be exactly at
2459 <dir of the aggregate>/x/y/a.gpr.
2460
2461 This attribute, however, does not affect the search for the aggregated
2462 project files specified with @code{Project_Files}.
2463
2464 Each aggregate project has its own (that is if agg1.gpr includes
2465 agg2.gpr, they can potentially both have a different project path).
2466 This project path is defined as the concatenation, in that order, of
2467 the current directory, followed by the command line -aP switches,
2468 then the directories from the Project_Path attribute, then the
2469 directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH env.
2470 variables, and finally the predefined directories.
2471
2472 In the example above, agg2.gpr's project path is not influenced by
2473 the attribute agg1'Project_Path, nor is agg1 influenced by
2474 agg2'Project_Path.
2475
2476 This can potentially lead to errors. In the following example:
2477
2478 @smallexample
2479      +---------------+                  +----------------+
2480      | Agg1.gpr      |-=--includes--=-->| Agg2.gpr       |
2481      |  'project_path|                  |  'project_path |
2482      |               |                  |                |
2483      +---------------+                  +----------------+
2484            :                                   :
2485            includes                        includes
2486            :                                   :
2487            v                                   v
2488        +-------+                          +---------+
2489        | P.gpr |<---------- withs --------|  Q.gpr  |
2490        +-------+---------\                +---------+
2491            |             |
2492            withs         |
2493            |             |
2494            v             v
2495        +-------+      +---------+
2496        | R.gpr |      | R'.gpr  |
2497        +-------+      +---------+
2498 @end smallexample
2499
2500 When looking for p.gpr, both aggregates find the same physical file on
2501 the disk. However, it might happen that with their different project
2502 paths, both aggregate projects would in fact find a different r.gpr.
2503 Since we have a common project (p.gpr) "with"ing two different r.gpr,
2504 this will be reported as an error by the builder.
2505
2506 Directories are relative to the location of the aggregate project file.
2507
2508 Here are a few valid examples:
2509
2510 @smallexample @c projectfile
2511    for Project_Path use ("/usr/local/gpr", "gpr/");
2512 @end smallexample
2513
2514 @item @b{External}:
2515 @cindex @code{External}
2516
2517 This attribute can be used to set the value of environment
2518 variables as retrieved through the @code{external} statement
2519 in projects. It does not affect the environment variables
2520 themselves (so for instance you cannot use it to change the value
2521 of your PATH as seen from the spawned compiler).
2522
2523 This attribute affects the external values as seen in the rest of
2524 the aggreate projects, and in the aggregated projects.
2525
2526 The exact value of external a variable comes from one of three
2527 sources (each level overrides the previous levels):
2528
2529 @itemize @bullet
2530 @item An External attribute in aggregate project, for instance
2531     @code{for External ("BUILD_MODE") use "DEBUG"};
2532
2533 @item Environment variables
2534
2535 These override the value given by the attribute, so that
2536 users can override the value set in the (presumably shared
2537 with others in his team) aggregate project.
2538
2539 @item The -X command line switch to gprbuild and gnatmake
2540
2541 This always takes precedence.
2542
2543 @end itemize
2544
2545 This attribute is only taken into account in the main aggregate
2546 project (i.e. the one specified on the command line to gprbuild or
2547 natmake), and ignored in other aggregate projects. It is invalid
2548 in standard projects.
2549 The goal is to have a consistent value in all
2550 projects that are build through the aggregate, which would not
2551 be the case in the diamond case: A groups the aggregate
2552 projects B and C, which both (either directly or indirectly)
2553 build the project P. If B and C could set different values for
2554 the environment variables, we would have two different views of
2555 P, which in particular might impact the list of source files in P.
2556
2557 @end table
2558
2559 @c ----------------------------------------------
2560 @node package Builder in aggregate projects
2561 @subsection package Builder in aggregate projects
2562 @c ----------------------------------------------
2563
2564 As we mentioned before, only the package Builder can be specified in
2565 an aggregate project. In this package, only the following attributes
2566 are valid:
2567
2568 @table @asis
2569 @item @b{Switches}:
2570 @cindex @code{Switches}
2571 This attribute gives the list of switches to use for the builder
2572 (gprbuild or gnatmake), depending on the language of the main file.
2573 For instance,
2574
2575 @smallexample @c projectfile
2576 for Switches ("Ada") use ("-d", "-p");
2577 for Switches ("C")   use ("-p");
2578 @end smallexample
2579
2580 These switches are only read from the main aggregate project (the
2581 one passed on the command line), and ignored in all other aggregate
2582 projects or projects.
2583
2584 It can only contain builder switches, not compiler switches.
2585
2586 @item @b{Global_Compilation_Switches}
2587 @cindex @code{Global_Compilation_Switches}
2588
2589 This attribute gives the list of compiler switches for the various
2590 languages. For instance,
2591
2592 @smallexample @c projectfile
2593 for Global_Compilation_Switches ("Ada") use ("-O1", "-g");
2594 for Global_Compilation_Switches ("C")   use ("-O2");
2595 @end smallexample
2596
2597 This attribute is only taken into account in the aggregate project
2598 specified on the command line, not in other aggregate projects.
2599
2600 In the projects grouped by that aggregate, the attribute
2601 Builder.Global_Compilation_Switches is also ignored. However, the
2602 attribute Compiler.Default_Switches will be taken into account (but
2603 that of the aggregate have higher priority). The attribute
2604 Compiler.Switches is also taken into account and can be used to
2605 override the switches for a specific file. As a result, it always
2606 has priority.
2607
2608 The rules are meant to avoid ambiguities when compiling. For
2609 instance, aggregate project Agg groups the projects A and B, that
2610 both depend on C. Here is an extra for all of these projects:
2611
2612 @smallexample @c projectfile
2613       aggregate project Agg is
2614           for Project_Files use ("a.gpr", "b.gpr");
2615           package Builder is
2616              for Global_Compilation_Switches ("Ada") use ("-O2");
2617           end Builder;
2618       end Agg;
2619
2620       with "c.gpr";
2621       project A is
2622           package Builder is
2623              for Global_Compilation_Switches ("Ada") use ("-O1");
2624              --  ignored
2625           end Builder;
2626
2627           package Compiler is
2628              for Default_Switches ("Ada") use ("-O1", "-g");
2629              for Switches ("a_file1.adb") use ("-O0");
2630           end Compiler;
2631       end A;
2632
2633       with "c.gpr";
2634       project B is
2635           package Compiler is
2636              for Default_Switches ("Ada") use ("-O0");
2637           end Compiler;
2638       end B;
2639
2640       project C is
2641           package Compiler is
2642              for Default_Switches ("Ada") use ("-O3", "-gnatn");
2643              for Switches ("c_file1.adb") use ("-O0", "-g");
2644           end Compiler;
2645       end C;
2646 @end smallexample
2647
2648 then the following switches are used:
2649
2650 @itemize @bullet
2651 @item all files from project A except a_file1.adb are compiled
2652       with "-O2 -g", since the aggregate project has priority.
2653 @item the file a_file1.adb is compiled with
2654       "-O0", since the Compiler.Switches has priority
2655 @item all files from project B are compiled with
2656       "-O2", since the aggregate project has priority
2657 @item all files from C are compiled with "-O2 -gnatn", except for
2658       c_file1.adb which is compiled with "-O0 -g"
2659 @end itemize
2660
2661 Even though C is seen through two paths (through A and through
2662 B), the switches used by the compiler are unambiguous.
2663
2664 @item @b{Global_Configuration_Pragmas}
2665 @cindex @code{Global_Configuration_Pragmas}
2666
2667 This attribute can be used to specify a file containing
2668 configuration pragmas, to be passed to the compiler.  Since we
2669 ignore the package Builder in other aggregate projects and projects,
2670 only those pragmas defined in the main aggregate project will be
2671 taken into account.
2672
2673 Projects can locally add to those by using the
2674 @code{Compiler.Local_Configuration_Pragmas} attribute if they need.
2675
2676 @end table
2677
2678 For projects that are build through the aggregate, the package Builder
2679 is ignored, except for the Executable attribute which specifies the
2680 name of the executables resulting from the link of the main programs, and
2681 for the Executable_Suffix.
2682
2683 @c ---------------------------------------------
2684 @node Aggregate Library Projects
2685 @section Aggregate Library Projects
2686 @c ---------------------------------------------
2687
2688 @noindent
2689
2690 Aggregate library projects make it possible to build a single library
2691 using object files built using other standard or library
2692 projects. This gives the flexibility to describe an application as
2693 having multiple modules (a GUI, database access, ...) using different
2694 project files (so possibly built with different compiler options) and
2695 yet create a single library (static or relocatable) out of the
2696 corresponding object files.
2697
2698 @menu
2699 * Building aggregate library projects::
2700 * Syntax of aggregate library projects::
2701 @end menu
2702
2703 @c ---------------------------------------------
2704 @node Building aggregate library projects
2705 @subsection Building aggregate library projects
2706 @c ---------------------------------------------
2707
2708 For example, we can define an aggregate project Agg that groups A, B
2709 and C:
2710
2711 @smallexample @c projectfile
2712    aggregate library project Agg is
2713       for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2714       for Library_Name use ("agg");
2715       for Library_Dir use ("lagg");
2716    end Agg;
2717 @end smallexample
2718
2719 Then, when you build with:
2720
2721 @smallexample
2722     gprbuild agg.gpr
2723 @end smallexample
2724
2725 This will build all units from projects A, B and C and will create a
2726 static library named @file{libagg.a} into the @file{lagg}
2727 directory. An aggregate library project has the same set of
2728 restriction as a standard library project.
2729
2730 Note that a shared aggregate library project cannot aggregates a
2731 static library project. In platforms where a compiler option is
2732 required to create relocatable object files, a Builder package in the
2733 aggregate library project may be used:
2734
2735 @smallexample @c projectfile
2736    aggregate library project Agg is
2737       for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
2738       for Library_Name use ("agg");
2739       for Library_Dir use ("lagg");
2740       for Library_Kind use "relocatable";
2741
2742       package Builder is
2743          for Global_Compilation_Switches ("Ada") use ("-fPIC");
2744       end Builder;
2745    end Agg;
2746 @end smallexample
2747
2748 With the above aggregate library Builder package, the @code{-fPIC}
2749 option will be passed to the compiler when building any source code
2750 from projects @file{a.gpr}, @file{b.gpr} and @file{c.gpr}.
2751
2752 @c ---------------------------------------------
2753 @node Syntax of aggregate library projects
2754 @subsection Syntax of aggregate library projects
2755 @c ---------------------------------------------
2756
2757 An aggregate library project follows the general syntax of project
2758 files. The recommended extension is still @file{.gpr}. However, a special
2759 @code{aggregate library} qualifier must be put before the keyword
2760 @code{project}.
2761
2762 An aggregate library project cannot @code{with} any other project
2763 (standard or aggregate), except an abstract project which can be used
2764 to share attribute values.
2765
2766 An aggregate library project does not have any source files directly (only
2767 through other standard projects). Therefore a number of the standard
2768 attributes and packages are forbidden in an aggregate library
2769 project. Here is the (non exhaustive) list:
2770
2771 @itemize @bullet
2772 @item Languages
2773 @item Source_Files, Source_List_File and other attributes dealing with
2774   list of sources.
2775 @item Source_Dirs, Exec_Dir and Object_Dir
2776 @item Main
2777 @item Roots
2778 @item Externally_Built
2779 @item Inherit_Source_Path
2780 @item Excluded_Source_Dirs
2781 @item Locally_Removed_Files
2782 @item Excluded_Source_Files
2783 @item Excluded_Source_List_File
2784 @item Interfaces
2785 @end itemize
2786
2787 The only package that is authorized (albeit optional) is Builder.
2788
2789 The Project_Files attribute (See @pxref{Aggregate Projects}) is used to
2790 described the aggregated projects whose object files have to be
2791 included into the aggregate library.
2792
2793 @c ---------------------------------------------
2794 @node Project File Reference
2795 @section Project File Reference
2796 @c ---------------------------------------------
2797
2798 @noindent
2799 This section describes the syntactic structure of project files, the various
2800 constructs that can be used. Finally, it ends with a summary of all available
2801 attributes.
2802
2803 @menu
2804 * Project Declaration::
2805 * Qualified Projects::
2806 * Declarations::
2807 * Packages::
2808 * Expressions::
2809 * External Values::
2810 * Typed String Declaration::
2811 * Variables::
2812 * Attributes::
2813 * Case Statements::
2814 @end menu
2815
2816 @c ---------------------------------------------
2817 @node Project Declaration
2818 @subsection Project Declaration
2819 @c ---------------------------------------------
2820
2821 @noindent
2822 Project files have an Ada-like syntax. The minimal project file is:
2823
2824 @smallexample @c projectfile
2825 @group
2826 project Empty is
2827 end Empty;
2828 @end group
2829 @end smallexample
2830
2831 @noindent
2832 The identifier @code{Empty} is the name of the project.
2833 This project name must be present after the reserved
2834 word @code{end} at the end of the project file, followed by a semi-colon.
2835
2836 @b{Identifiers} (i.e.@: the user-defined names such as project or variable names)
2837 have the same syntax as Ada identifiers: they must start with a letter,
2838 and be followed by zero or more letters, digits or underscore characters;
2839 it is also illegal to have two underscores next to each other. Identifiers
2840 are always case-insensitive ("Name" is the same as "name").
2841
2842 @smallexample
2843 simple_name ::= identifier
2844 name        ::= simple_name @{ . simple_name @}
2845 @end smallexample
2846
2847 @noindent
2848 @b{Strings} are used for values of attributes or as indexes for these
2849 attributes. They are in general case sensitive, except when noted
2850 otherwise (in particular, strings representing file names will be case
2851 insensitive on some systems, so that "file.adb" and "File.adb" both
2852 represent the same file).
2853
2854 @b{Reserved words} are the same as for standard Ada 95, and cannot
2855 be used for identifiers. In particular, the following words are currently
2856 used in project files, but others could be added later on. In bold are the
2857 extra reserved words in project files: @code{all, at, case, end, for, is,
2858 limited, null, others, package, renames, type, use, when, with, @b{extends},
2859 @b{external}, @b{project}}.
2860
2861 @b{Comments} in project files have the same syntax as in Ada, two consecutive
2862 hyphens through the end of the line.
2863
2864 A project may be an @b{independent project}, entirely defined by a single
2865 project file. Any source file in an independent project depends only
2866 on the predefined library and other source files in the same project.
2867 But a project may also depend on other projects, either by importing them
2868 through @b{with clauses}, or by @b{extending} at most one other project. Both
2869 types of dependency can be used in the same project.
2870
2871 A path name denotes a project file. It can be absolute or relative.
2872 An absolute path name includes a sequence of directories, in the syntax of
2873 the host operating system, that identifies uniquely the project file in the
2874 file system. A relative path name identifies the project file, relative
2875 to the directory that contains the current project, or relative to a
2876 directory listed in the environment variables ADA_PROJECT_PATH and
2877 GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
2878 operating system are case sensitive. As a special case, the directory
2879 separator can always be "/" even on Windows systems, so that project files
2880 can be made portable across architectures.
2881 The syntax of the environment variable ADA_PROJECT_PATH and
2882 GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
2883 semicolons on Windows.
2884
2885 A given project name can appear only once in a context clause.
2886
2887 It is illegal for a project imported by a context clause to refer, directly
2888 or indirectly, to the project in which this context clause appears (the
2889 dependency graph cannot contain cycles), except when one of the with clause
2890 in the cycle is a @b{limited with}.
2891 @c ??? Need more details here
2892
2893 @smallexample @c projectfile
2894 with "other_project.gpr";
2895 project My_Project extends "extended.gpr" is
2896 end My_Project;
2897 @end smallexample
2898
2899 @noindent
2900 These dependencies form a @b{directed graph}, potentially cyclic when using
2901 @b{limited with}. The subprogram reflecting the @b{extends} relations is a
2902 tree.
2903
2904 A project's @b{immediate sources} are the source files directly defined by
2905 that project, either implicitly by residing in the project source directories,
2906 or explicitly through any of the source-related attributes.
2907 More generally, a project sources are the immediate sources of the project
2908 together with the immediate sources (unless overridden) of any
2909 project on which it depends directly or indirectly.
2910
2911 A @b{project hierarchy} can be created, where projects are children of
2912 other projects. The name of such a child project must be @code{Parent.Child},
2913 where @code{Parent} is the name of the parent project. In particular, this
2914 makes all @code{with} clauses of the parent project automatically visible
2915 in the child project.
2916
2917 @smallexample
2918 project        ::= context_clause project_declaration
2919
2920 context_clause ::= @{with_clause@}
2921 with_clause    ::= @i{with} path_name @{ , path_name @} ;
2922 path_name      ::= string_literal
2923
2924 project_declaration ::= simple_project_declaration | project_extension
2925 simple_project_declaration ::=
2926   @i{project} @i{<project_>}name @i{is}
2927     @{declarative_item@}
2928   @i{end} <project_>simple_name;
2929 @end smallexample
2930
2931 @c ---------------------------------------------
2932 @node Qualified Projects
2933 @subsection Qualified Projects
2934 @c ---------------------------------------------
2935
2936 @noindent
2937 Before the reserved @code{project}, there may be one or two @b{qualifiers}, that
2938 is identifiers or reserved words, to qualify the project.
2939 The current list of qualifiers is:
2940
2941 @table @asis
2942 @item @b{abstract}: qualifies a project with no sources. Such a
2943   project must either have no declaration of attributes @code{Source_Dirs},
2944   @code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
2945   @code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
2946   as empty. If it extends another project, the project it extends must also be a
2947   qualified abstract project.
2948 @item @b{standard}: a standard project is a non library project with sources.
2949   This is the default (implicit) qualifier.
2950 @item @b{aggregate}: a project whose sources are aggregated from other
2951 project files.
2952 @item @b{aggregate library}: a library whose sources are aggregated
2953 from other project or library project files.
2954 @item @b{library}: a library project must declare both attributes
2955   @code{Library_Name} and @code{Library_Dir}.
2956 @item @b{configuration}: a configuration project cannot be in a project tree.
2957   It describes compilers and other tools to @code{gprbuild}.
2958 @end table
2959
2960 @c ---------------------------------------------
2961 @node Declarations
2962 @subsection Declarations
2963 @c ---------------------------------------------
2964
2965 @noindent
2966 Declarations introduce new entities that denote types, variables, attributes,
2967 and packages. Some declarations can only appear immediately within a project
2968 declaration. Others can appear within a project or within a package.
2969
2970 @smallexample
2971 declarative_item ::= simple_declarative_item
2972   | typed_string_declaration
2973   | package_declaration
2974
2975 simple_declarative_item ::= variable_declaration
2976   | typed_variable_declaration
2977   | attribute_declaration
2978   | case_construction
2979   | empty_declaration
2980
2981 empty_declaration ::= @i{null} ;
2982 @end smallexample
2983
2984 @noindent
2985 An empty declaration is allowed anywhere a declaration is allowed. It has
2986 no effect.
2987
2988 @c ---------------------------------------------
2989 @node Packages
2990 @subsection Packages
2991 @c ---------------------------------------------
2992
2993 @noindent
2994 A project file may contain @b{packages}, that group attributes (typically
2995 all the attributes that are used by one of the GNAT tools).
2996
2997 A package with a given name may only appear once in a project file.
2998 The following packages are currently supported in project files
2999 (See @pxref{Attributes} for the list of attributes that each can contain).
3000
3001 @table @code
3002 @item Binder
3003   This package specifies characteristics useful when invoking the binder either
3004   directly via the @command{gnat} driver or when using a builder such as
3005   @command{gnatmake} or @command{gprbuild}. @xref{Main Subprograms}.
3006 @item Builder
3007   This package specifies the compilation options used when building an
3008   executable or a library for a project. Most of the options should be
3009   set in one of @code{Compiler}, @code{Binder} or @code{Linker} packages,
3010   but there are some general options that should be defined in this
3011   package. @xref{Main Subprograms}, and @pxref{Executable File Names} in
3012   particular.
3013 @item Check
3014   This package specifies the options used when calling the checking tool
3015   @command{gnatcheck} via the @command{gnat} driver. Its attribute
3016   @b{Default_Switches} has the same semantics as for the package
3017   @code{Builder}. The first string should always be @code{-rules} to specify
3018   that all the other options belong to the @code{-rules} section of the
3019   parameters to @command{gnatcheck}.
3020 @item Compiler
3021   This package specifies the compilation options used by the compiler for
3022   each languages. @xref{Tools Options in Project Files}.
3023 @item Cross_Reference
3024   This package specifies the options used when calling the library tool
3025   @command{gnatxref} via the @command{gnat} driver. Its attributes
3026   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3027   package @code{Builder}.
3028 @item Eliminate
3029   This package specifies the options used when calling the tool
3030   @command{gnatelim} via the @command{gnat} driver. Its attributes
3031   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3032   package @code{Builder}.
3033 @item Finder
3034   This package specifies the options used when calling the search tool
3035   @command{gnatfind} via the @command{gnat} driver. Its attributes
3036   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3037   package @code{Builder}.
3038 @item Gnatls
3039   This package the options to use when invoking @command{gnatls} via the
3040   @command{gnat} driver.
3041 @item Gnatstub
3042   This package specifies the options used when calling the tool
3043   @command{gnatstub} via the @command{gnat} driver. Its attributes
3044   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3045   package @code{Builder}.
3046 @item IDE
3047   This package specifies the options used when starting an integrated
3048   development environment, for instance @command{GPS} or @command{Gnatbench}.
3049   @xref{The Development Environments}.
3050 @item Linker
3051   This package specifies the options used by the linker.
3052   @xref{Main Subprograms}.
3053 @item Makefile
3054 @cindex Makefile package in projects
3055   This package is used by the GPS plugin Makefile.py. See the documentation
3056   in that plugin (from GPS: /Tools/Plug-ins).
3057 @item Metrics
3058   This package specifies the options used when calling the tool
3059   @command{gnatmetric} via the @command{gnat} driver. Its attributes
3060   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3061   package @code{Builder}.
3062 @item Naming
3063   This package specifies the naming conventions that apply
3064   to the source files in a project. In particular, these conventions are
3065   used to automatically find all source files in the source directories,
3066   or given a file name to find out its language for proper processing.
3067   @xref{Naming Schemes}.
3068 @item Pretty_Printer
3069   This package specifies the options used when calling the formatting tool
3070   @command{gnatpp} via the @command{gnat} driver. Its attributes
3071   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3072   package @code{Builder}.
3073 @item Stack
3074   This package specifies the options used when calling the tool
3075   @command{gnatstack} via the @command{gnat} driver. Its attributes
3076   @b{Default_Switches} and @b{Switches} have the same semantics as for the
3077   package @code{Builder}.
3078 @item Synchronize
3079   This package specifies the options used when calling the tool
3080   @command{gnatsync} via the @command{gnat} driver.
3081
3082 @end table
3083
3084 In its simplest form, a package may be empty:
3085
3086 @smallexample @c projectfile
3087 @group
3088 project Simple is
3089   package Builder is
3090   end Builder;
3091 end Simple;
3092 @end group
3093 @end smallexample
3094
3095 @noindent
3096 A package may contain @b{attribute declarations},
3097 @b{variable declarations} and @b{case constructions}, as will be
3098 described below.
3099
3100 When there is ambiguity between a project name and a package name,
3101 the name always designates the project. To avoid possible confusion, it is
3102 always a good idea to avoid naming a project with one of the
3103 names allowed for packages or any name that starts with @code{gnat}.
3104
3105 A package can also be defined by a @b{renaming declaration}. The new package
3106 renames a package declared in a different project file, and has the same
3107 attributes as the package it renames. The name of the renamed package
3108 must be the same as the name of the renaming package. The project must
3109 contain a package declaration with this name, and the project
3110 must appear in the context clause of the current project, or be its parent
3111 project. It is not possible to add or override attributes to the renaming
3112 project. If you need to do so, you should use an @b{extending declaration}
3113 (see below).
3114
3115 Packages that are renamed in other project files often come from project files
3116 that have no sources: they are just used as templates. Any modification in the
3117 template will be reflected automatically in all the project files that rename
3118 a package from the template. This is a very common way to share settings
3119 between projects.
3120
3121 Finally, a package can also be defined by an @b{extending declaration}. This is
3122 similar to a @b{renaming declaration}, except that it is possible to add or
3123 override attributes.
3124
3125 @smallexample
3126 package_declaration ::= package_spec | package_renaming | package_extension
3127 package_spec ::=
3128   @i{package} @i{<package_>}simple_name @i{is}
3129     @{simple_declarative_item@}
3130   @i{end} package_identifier ;
3131 package_renaming ::==
3132   @i{package} @i{<package_>}simple_name @i{renames} @i{<project_>}simple_name.package_identifier ;
3133 package_extension ::==
3134   @i{package} @i{<package_>}simple_name @i{extends} @i{<project_>}simple_name.package_identifier @i{is}
3135     @{simple_declarative_item@}
3136   @i{end} package_identifier ;
3137 @end smallexample
3138
3139 @c ---------------------------------------------
3140 @node Expressions
3141 @subsection Expressions
3142 @c ---------------------------------------------
3143
3144 @noindent
3145 An expression is any value that can be assigned to an attribute or a
3146 variable. It is either a literal value, or a construct requiring runtime
3147 computation by the project manager. In a project file, the computed value of
3148 an expression is either a string or a list of strings.
3149
3150 A string value is one of:
3151 @itemize @bullet
3152 @item A literal string, for instance @code{"comm/my_proj.gpr"}
3153 @item The name of a variable that evaluates to a string (@pxref{Variables})
3154 @item The name of an attribute that evaluates to a string (@pxref{Attributes})
3155 @item An external reference (@pxref{External Values})
3156 @item A concatenation of the above, as in @code{"prefix_" & Var}.
3157
3158 @end itemize
3159
3160 @noindent
3161 A list of strings is one of the following:
3162
3163 @itemize @bullet
3164 @item A parenthesized comma-separated list of zero or more string expressions, for
3165   instance @code{(File_Name, "gnat.adc", File_Name & ".orig")} or @code{()}.
3166 @item The name of a variable that evaluates to a list of strings
3167 @item The name of an attribute that evaluates to a list of strings
3168 @item A concatenation of a list of strings and a string (as defined above), for
3169   instance @code{("A", "B") & "C"}
3170 @item A concatenation of two lists of strings
3171
3172 @end itemize
3173
3174 @noindent
3175 The following is the grammar for expressions
3176
3177 @smallexample
3178 string_literal ::= "@{string_element@}"  --  Same as Ada
3179 string_expression ::= string_literal
3180     | @i{variable_}name
3181     | external_value
3182     | attribute_reference
3183     | ( string_expression @{ & string_expression @} )
3184 string_list  ::= ( string_expression @{ , string_expression @} )
3185    | @i{string_variable}_name
3186    | @i{string_}attribute_reference
3187 term ::= string_expression | string_list
3188 expression ::= term @{ & term @}     --  Concatenation
3189 @end smallexample
3190
3191 @noindent
3192 Concatenation involves strings and list of strings. As soon as a list of
3193 strings is involved, the result of the concatenation is a list of strings. The
3194 following Ada declarations show the existing operators:
3195
3196 @smallexample @c ada
3197   function "&" (X : String;      Y : String)      return String;
3198   function "&" (X : String_List; Y : String)      return String_List;
3199   function "&" (X : String_List; Y : String_List) return String_List;
3200 @end smallexample
3201
3202 @noindent
3203 Here are some specific examples:
3204
3205 @smallexample @c projectfile
3206 @group
3207    List := () & File_Name; --  One string in this list
3208    List2 := List & (File_Name & ".orig"); -- Two strings
3209    Big_List := List & Lists2;  --  Three strings
3210    Illegal := "gnat.adc" & List2;  --  Illegal, must start with list
3211 @end group
3212 @end smallexample
3213
3214 @c ---------------------------------------------
3215 @node External Values
3216 @subsection External Values
3217 @c ---------------------------------------------
3218
3219 @noindent
3220 An external value is an expression whose value is obtained from the command
3221 that invoked the processing of the current project file (typically a
3222 gnatmake or gprbuild command).
3223
3224 There are two kinds of external values, one that returns a single string, and
3225 one that returns a string list.
3226
3227 The syntax of a single string external value is:
3228
3229 @smallexample
3230 external_value ::= @i{external} ( string_literal [, string_literal] )
3231 @end smallexample
3232
3233 @noindent
3234 The first string_literal is the string to be used on the command line or
3235 in the environment to specify the external value. The second string_literal,
3236 if present, is the default to use if there is no specification for this
3237 external value either on the command line or in the environment.
3238
3239 Typically, the external value will either exist in the
3240 ^environment variables^logical name^
3241 or be specified on the command line through the
3242 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. If both
3243 are specified, then the command line value is used, so that a user can more
3244 easily override the value.
3245
3246 The function @code{external} always returns a string. It is an error if the
3247 value was not found in the environment and no default was specified in the
3248 call to @code{external}.
3249
3250 An external reference may be part of a string expression or of a string
3251 list expression, and can therefore appear in a variable declaration or
3252 an attribute declaration.
3253
3254 Most of the time, this construct is used to initialize typed variables, which
3255 are then used in @b{case} statements to control the value assigned to
3256 attributes in various scenarios. Thus such variables are often called
3257 @b{scenario variables}.
3258
3259 The syntax for a string list external value is:
3260
3261 @smallexample
3262 external_value ::= @i{external_as_list} ( string_literal , string_literal )
3263 @end smallexample
3264
3265 @noindent
3266 The first string_literal is the string to be used on the command line or
3267 in the environment to specify the external value. The second string_literal is
3268 the separator between each component of the string list.
3269
3270 If the external value does not exist in the environment or on the command line,
3271 the result is an empty list. This is also the case, if the separator is an
3272 empty string or if the external value is only one separator.
3273
3274 Any separator at the beginning or at the end of the external value is
3275 discarded. Then, if there is no separator in the external value, the result is
3276 a string list with only one string. Otherwise, any string between the beginning
3277 and the first separator, between two consecutive separators and between the
3278 last separator and the end are components of the string list.
3279
3280 @smallexample
3281    @i{external_as_list} ("SWITCHES", ",")
3282 @end smallexample
3283
3284 @noindent
3285 If the external value is "-O2,-g", the result is ("-O2", "-g").
3286
3287 If the external value is ",-O2,-g,", the result is also ("-O2", "-g").
3288
3289 if the external value is "-gnav", the result is ("-gnatv").
3290
3291 If the external value is ",,", the result is ("").
3292
3293 If the external value is ",", the result is (), the empty string list.
3294
3295 @c ---------------------------------------------
3296 @node Typed String Declaration
3297 @subsection Typed String Declaration
3298 @c ---------------------------------------------
3299
3300 @noindent
3301 A @b{type declaration} introduces a discrete set of string literals.
3302 If a string variable is declared to have this type, its value
3303 is restricted to the given set of literals. These are the only named
3304 types in project files. A string type may only be declared at the project
3305 level, not inside a package.
3306
3307 @smallexample
3308 typed_string_declaration ::=
3309   @i{type} @i{<typed_string_>}_simple_name @i{is} ( string_literal @{, string_literal@} );
3310 @end smallexample
3311
3312 @noindent
3313 The string literals in the list are case sensitive and must all be different.
3314 They may include any graphic characters allowed in Ada, including spaces.
3315 Here is an example of a string type declaration:
3316
3317 @smallexample @c projectfile
3318    type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
3319 @end smallexample
3320
3321 @noindent
3322 Variables of a string type are called @b{typed variables}; all other
3323 variables are called @b{untyped variables}. Typed variables are
3324 particularly useful in @code{case} constructions, to support conditional
3325 attribute declarations. (@pxref{Case Statements}).
3326
3327 A string type may be referenced by its name if it has been declared in the same
3328 project file, or by an expanded name whose prefix is the name of the project
3329 in which it is declared.
3330
3331 @c ---------------------------------------------
3332 @node Variables
3333 @subsection Variables
3334 @c ---------------------------------------------
3335
3336 @noindent
3337 @b{Variables} store values (strings or list of strings) and can appear
3338 as part of an expression. The declaration of a variable creates the
3339 variable and assigns the value of the expression to it. The name of the
3340 variable is available immediately after the assignment symbol, if you
3341 need to reuse its old value to compute the new value. Before the completion
3342 of its first declaration, the value of a variable defaults to the empty
3343 string ("").
3344
3345 A @b{typed} variable can be used as part of a @b{case} expression to
3346 compute the value, but it can only be declared once in the project file,
3347 so that all case statements see the same value for the variable. This
3348 provides more consistency and makes the project easier to understand.
3349 The syntax for its declaration is identical to the Ada syntax for an
3350 object declaration. In effect, a typed variable acts as a constant.
3351
3352 An @b{untyped} variable can be declared and overridden multiple times
3353 within the same project. It is declared implicitly through an Ada
3354 assignment. The first declaration establishes the kind of the variable
3355 (string or list of strings) and successive declarations must respect
3356 the initial kind. Assignments are executed in the order in which they
3357 appear, so the new value replaces the old one and any subsequent reference
3358 to the variable uses the new value.
3359
3360 A variable may be declared at the project file level, or within a package.
3361
3362 @smallexample
3363 typed_variable_declaration ::=
3364   @i{<typed_variable_>}simple_name : @i{<typed_string_>}name := string_expression;
3365 variable_declaration ::= @i{<variable_>}simple_name := expression;
3366 @end smallexample
3367
3368 @noindent
3369 Here are some examples of variable declarations:
3370
3371 @smallexample @c projectfile
3372 @group
3373    This_OS : OS := external ("OS"); --  a typed variable declaration
3374    That_OS := "GNU/Linux";          --  an untyped variable declaration
3375
3376    Name      := "readme.txt";
3377    Save_Name := Name & ".saved";
3378
3379    Empty_List := ();
3380    List_With_One_Element := ("-gnaty");
3381    List_With_Two_Elements := List_With_One_Element & "-gnatg";
3382    Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
3383 @end group
3384 @end smallexample
3385
3386 @noindent
3387 A @b{variable reference} may take several forms:
3388
3389 @itemize @bullet
3390 @item The simple variable name, for a variable in the current package (if any)
3391   or in the current project
3392 @item An expanded name, whose prefix is a context name.
3393
3394 @end itemize
3395
3396 @noindent
3397 A @b{context} may be one of the following:
3398
3399 @itemize @bullet
3400 @item The name of an existing package in the current project
3401 @item The name of an imported project of the current project
3402 @item The name of an ancestor project (i.e., a project extended by the current
3403   project, either directly or indirectly)
3404 @item An expanded name whose prefix is an imported/parent project name, and
3405   whose selector is a package name in that project.
3406 @end itemize
3407
3408 @c ---------------------------------------------
3409 @node Attributes
3410 @subsection Attributes
3411 @c ---------------------------------------------
3412
3413 @noindent
3414 A project (and its packages) may have @b{attributes} that define
3415 the project's properties.  Some attributes have values that are strings;
3416 others have values that are string lists.
3417
3418 @smallexample
3419 attribute_declaration ::=
3420    simple_attribute_declaration | indexed_attribute_declaration
3421 simple_attribute_declaration ::= @i{for} attribute_designator @i{use} expression ;
3422 indexed_attribute_declaration ::=
3423   @i{for} @i{<indexed_attribute_>}simple_name ( string_literal) @i{use} expression ;
3424 attribute_designator ::=
3425   @i{<simple_attribute_>}simple_name
3426   | @i{<indexed_attribute_>}simple_name ( string_literal )
3427 @end smallexample
3428
3429 @noindent
3430 There are two categories of attributes: @b{simple attributes}
3431 and @b{indexed attributes}.
3432 Each simple attribute has a default value: the empty string (for string
3433 attributes) and the empty list (for string list attributes).
3434 An attribute declaration defines a new value for an attribute, and overrides
3435 the previous value. The syntax of a simple attribute declaration is similar to
3436 that of an attribute definition clause in Ada.
3437
3438 Some attributes are indexed. These attributes are mappings whose
3439 domain is a set of strings. They are declared one association
3440 at a time, by specifying a point in the domain and the corresponding image
3441 of the attribute.
3442 Like untyped variables and simple attributes, indexed attributes
3443 may be declared several times. Each declaration supplies a new value for the
3444 attribute, and replaces the previous setting.
3445
3446 Here are some examples of attribute declarations:
3447
3448 @smallexample @c projectfile
3449    --  simple attributes
3450    for Object_Dir use "objects";
3451    for Source_Dirs use ("units", "test/drivers");
3452
3453    --  indexed attributes
3454    for Body ("main") use "Main.ada";
3455    for Switches ("main.ada") use ("-v", "-gnatv");
3456    for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
3457
3458    --  indexed attributes copy (from package Builder in project Default)
3459    --  The package name must always be specified, even if it is the current
3460    --  package.
3461    for Default_Switches use Default.Builder'Default_Switches;
3462 @end smallexample
3463
3464 @noindent
3465 Attributes references may be appear anywhere in expressions, and are used
3466 to retrieve the value previously assigned to the attribute. If an attribute
3467 has not been set in a given package or project, its value defaults to the
3468 empty string or the empty list.
3469
3470 @smallexample
3471 attribute_reference ::= attribute_prefix ' @i{<simple_attribute>_}simple_name [ (string_literal) ]
3472 attribute_prefix ::= @i{project}
3473   | @i{<project_>}simple_name
3474   | package_identifier
3475   | @i{<project_>}simple_name . package_identifier
3476 @end smallexample
3477
3478 @noindent
3479 Examples are:
3480
3481 @smallexample @c projectfile
3482   project'Object_Dir
3483   Naming'Dot_Replacement
3484   Imported_Project'Source_Dirs
3485   Imported_Project.Naming'Casing
3486   Builder'Default_Switches ("Ada")
3487 @end smallexample
3488
3489 @noindent
3490 The prefix of an attribute may be:
3491
3492 @itemize @bullet
3493 @item @code{project} for an attribute of the current project
3494 @item The name of an existing package of the current project
3495 @item The name of an imported project
3496 @item The name of a parent project that is extended by the current project
3497 @item An expanded name whose prefix is imported/parent project name,
3498   and whose selector is a package name
3499
3500 @end itemize
3501
3502 @noindent
3503 Legal attribute names are listed below, including the package in
3504 which they must be declared. These names are case-insensitive. The
3505 semantics for the attributes is explained in great details in other sections.
3506
3507 The column @emph{index} indicates whether the attribute is an indexed attribute,
3508 and when it is whether its index is case sensitive (sensitive) or not (insensitive), or if case sensitivity depends is the same as file names sensitivity on the
3509 system (file). The text is between brackets ([]) if the index is optional.
3510
3511 @multitable @columnfractions .3 .1 .2 .4
3512 @headitem Attribute Name @tab Value @tab Package @tab Index
3513 @headitem General attributes @tab @tab @tab @pxref{Building With Projects}
3514 @item Name @tab string @tab - @tab (Read-only, name of project)
3515 @item Project_Dir @tab string @tab - @tab (Read-only, directory of project)
3516 @item Source_Files @tab list @tab - @tab -
3517 @item Source_Dirs  @tab list @tab - @tab -
3518 @item Source_List_File @tab string @tab - @tab -
3519 @item Locally_Removed_Files @tab list @tab - @tab -
3520 @item Excluded_Source_Files @tab list @tab - @tab -
3521 @item Object_Dir   @tab string @tab - @tab -
3522 @item Exec_Dir     @tab string @tab - @tab -
3523 @item Excluded_Source_Dirs @tab list @tab - @tab -
3524 @item Excluded_Source_Files @tab list @tab - @tab -
3525 @item Excluded_Source_List_File @tab list @tab - @tab -
3526 @item Inherit_Source_Path  @tab list @tab - @tab insensitive
3527 @item Languages @tab list @tab - @tab -
3528 @item Main      @tab list @tab - @tab -
3529 @item Main_Language @tab string @tab - @tab -
3530 @item Externally_Built      @tab string @tab - @tab -
3531 @item Roots      @tab list @tab - @tab file
3532 @headitem
3533    Library-related attributes @tab @tab @tab @pxref{Library Projects}
3534 @item Library_Dir @tab string @tab - @tab -
3535 @item Library_Name @tab string @tab - @tab -
3536 @item Library_Kind @tab string @tab - @tab -
3537 @item Library_Version @tab string @tab - @tab -
3538 @item Library_Interface @tab string @tab - @tab -
3539 @item Library_Auto_Init @tab string @tab - @tab -
3540 @item Library_Options @tab list @tab - @tab -
3541 @item Leading_Library_Options @tab list @tab - @tab -
3542 @item Library_Src_Dir @tab string @tab - @tab -
3543 @item Library_ALI_Dir @tab string @tab - @tab -
3544 @item Library_GCC @tab string @tab - @tab -
3545 @item Library_Symbol_File @tab string @tab - @tab -
3546 @item Library_Symbol_Policy @tab string @tab - @tab -
3547 @item Library_Reference_Symbol_File @tab string @tab - @tab -
3548 @item Interfaces @tab list @tab - @tab -
3549 @headitem
3550    Naming @tab @tab @tab @pxref{Naming Schemes}
3551 @item Spec_Suffix @tab string @tab Naming @tab insensitive (language)
3552 @item Body_Suffix @tab string @tab Naming @tab insensitive (language)
3553 @item Separate_Suffix @tab string @tab Naming @tab -
3554 @item Casing @tab string @tab Naming @tab -
3555 @item Dot_Replacement @tab string @tab Naming @tab -
3556 @item Spec @tab string @tab Naming @tab insensitive (Ada unit)
3557 @item Body @tab string @tab Naming @tab insensitive (Ada unit)
3558 @item Specification_Exceptions @tab list @tab Naming @tab insensitive (language)
3559 @item Implementation_Exceptions @tab list @tab Naming @tab insensitive (language)
3560 @headitem
3561    Building @tab @tab @tab @pxref{Switches and Project Files}
3562 @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)
3563 @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)
3564 @item Local_Configuration_Pragmas @tab string @tab Compiler @tab -
3565 @item Local_Config_File @tab string @tab insensitive @tab -
3566 @item Global_Configuration_Pragmas @tab list @tab Builder @tab -
3567 @item Global_Compilation_Switches @tab list @tab Builder @tab language
3568 @item Executable @tab string @tab Builder @tab [file]
3569 @item Executable_Suffix @tab string @tab Builder @tab -
3570 @item Global_Config_File @tab string @tab Builder @tab insensitive (language)
3571 @headitem
3572    IDE (used and created by GPS) @tab @tab @tab
3573 @item Remote_Host @tab string @tab IDE @tab -
3574 @item Program_Host @tab string @tab IDE @tab -
3575 @item Communication_Protocol @tab string @tab IDE @tab -
3576 @item Compiler_Command @tab string @tab IDE @tab insensitive (language)
3577 @item Debugger_Command @tab string @tab IDE @tab -
3578 @item Gnatlist @tab string @tab IDE @tab -
3579 @item Gnat @tab string @tab IDE @tab -
3580 @item VCS_Kind @tab string @tab IDE @tab -
3581 @item VCS_File_Check @tab string @tab IDE @tab -
3582 @item VCS_Log_Check @tab string @tab IDE @tab -
3583 @item Documentation_Dir @tab string @tab IDE @tab -
3584 @headitem
3585    Configuration files @tab @tab @tab See gprbuild manual
3586 @item Default_Language @tab string @tab - @tab -
3587 @item Run_Path_Option @tab list @tab - @tab -
3588 @item Run_Path_Origin @tab string @tab - @tab -
3589 @item Separate_Run_Path_Options @tab string @tab - @tab -
3590 @item Toolchain_Version @tab string @tab - @tab insensitive
3591 @item Toolchain_Description @tab string @tab - @tab insensitive
3592 @item Object_Generated @tab string @tab - @tab insensitive
3593 @item Objects_Linked @tab string @tab - @tab insensitive
3594 @item Target @tab string @tab - @tab -
3595 @item Library_Builder @tab string @tab - @tab -
3596 @item Library_Support @tab string @tab - @tab -
3597 @item Archive_Builder @tab list @tab - @tab -
3598 @item Archive_Builder_Append_Option @tab list @tab - @tab -
3599 @item Archive_Indexer @tab list @tab - @tab -
3600 @item Archive_Suffix @tab string @tab - @tab -
3601 @item Library_Partial_Linker @tab list @tab - @tab -
3602 @item Shared_Library_Prefix @tab string @tab - @tab -
3603 @item Shared_Library_Suffix @tab string @tab - @tab -
3604 @item Symbolic_Link_Supported @tab string @tab - @tab -
3605 @item Library_Major_Minor_Id_Supported @tab string @tab - @tab -
3606 @item Library_Auto_Init_Supported @tab string @tab - @tab -
3607 @item Shared_Library_Minimum_Switches @tab list @tab - @tab -
3608 @item Library_Version_Switches @tab list @tab - @tab -
3609 @item Library_Install_Name_Option @tab string @tab - @tab -
3610 @item Runtime_Library_Dir @tab string @tab - @tab insensitive
3611 @item Runtime_Source_Dir @tab string @tab - @tab insensitive
3612 @item Driver @tab string @tab Compiler,Binder,Linker @tab insensitive (language)
3613 @item Required_Switches @tab list @tab Compiler,Binder,Linker @tab insensitive (language)
3614 @item Leading_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3615 @item Trailing_Required_Switches @tab list @tab Compiler @tab insensitive (language)
3616 @item Pic_Options @tab list @tab Compiler @tab insensitive (language)
3617 @item Path_Syntax @tab string @tab Compiler @tab insensitive (language)
3618 @item Object_File_Suffix @tab string @tab Compiler @tab insensitive (language)
3619 @item Object_File_Switches @tab list @tab Compiler @tab insensitive (language)
3620 @item Multi_Unit_Switches @tab list @tab Compiler @tab insensitive (language)
3621 @item Multi_Unit_Object_Separator @tab string @tab Compiler @tab insensitive (language)
3622 @item Mapping_File_Switches @tab list @tab Compiler @tab insensitive (language)
3623 @item Mapping_Spec_Suffix @tab string @tab Compiler @tab insensitive (language)
3624 @item Mapping_body_Suffix @tab string @tab Compiler @tab insensitive (language)
3625 @item Config_File_Switches @tab list @tab Compiler @tab insensitive (language)
3626 @item Config_Body_File_Name @tab string @tab Compiler @tab insensitive (language)
3627 @item Config_Body_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3628 @item Config_Body_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3629 @item Config_Spec_File_Name @tab string @tab Compiler @tab insensitive (language)
3630 @item Config_Spec_File_Name_Index @tab string @tab Compiler @tab insensitive (language)
3631 @item Config_Spec_File_Name_Pattern @tab string @tab Compiler @tab insensitive (language)
3632 @item Config_File_Unique @tab string @tab Compiler @tab insensitive (language)
3633 @item Dependency_Switches @tab list @tab Compiler @tab insensitive (language)
3634 @item Dependency_Driver @tab list @tab Compiler @tab insensitive (language)
3635 @item Include_Switches @tab list @tab Compiler @tab insensitive (language)
3636 @item Include_Path @tab string @tab Compiler @tab insensitive (language)
3637 @item Include_Path_File @tab string @tab Compiler @tab insensitive (language)
3638 @item Prefix @tab string @tab Binder @tab insensitive (language)
3639 @item Objects_Path @tab string @tab Binder @tab insensitive (language)
3640 @item Objects_Path_File @tab string @tab Binder @tab insensitive (language)
3641 @item Linker_Options @tab list @tab Linker @tab -
3642 @item Leading_Switches @tab list @tab Linker @tab -
3643 @item Map_File_Options @tab string @tab Linker @tab -
3644 @item Executable_Switches @tab list @tab Linker @tab -
3645 @item Lib_Dir_Switch @tab string @tab Linker @tab -
3646 @item Lib_Name_Switch @tab string @tab Linker @tab -
3647 @item Max_Command_Line_Length @tab string @tab Linker @tab -
3648 @item Response_File_Format @tab string @tab Linker @tab -
3649 @item Response_File_Switches @tab list @tab Linker @tab -
3650 @end multitable
3651
3652 @c ---------------------------------------------
3653 @node Case Statements
3654 @subsection Case Statements
3655 @c ---------------------------------------------
3656
3657 @noindent
3658 A @b{case} statement is used in a project file to effect conditional
3659 behavior. Through this statement, you can set the value of attributes
3660 and variables depending on the value previously assigned to a typed
3661 variable.
3662
3663 All choices in a choice list must be distinct. Unlike Ada, the choice
3664 lists of all alternatives do not need to include all values of the type.
3665 An @code{others} choice must appear last in the list of alternatives.
3666
3667 The syntax of a @code{case} construction is based on the Ada case statement
3668 (although the @code{null} statement for empty alternatives is optional).
3669
3670 The case expression must be a typed string variable, whose value is often
3671 given by an external reference (@pxref{External Values}).
3672
3673 Each alternative starts with the reserved word @code{when}, either a list of
3674 literal strings separated by the @code{"|"} character or the reserved word
3675 @code{others}, and the @code{"=>"} token.
3676 Each literal string must belong to the string type that is the type of the
3677 case variable.
3678 After each @code{=>}, there are zero or more statements.  The only
3679 statements allowed in a case construction are other case statements,
3680 attribute declarations and variable declarations. String type declarations and
3681 package declarations are not allowed. Variable declarations are restricted to
3682 variables that have already been declared before the case construction.
3683
3684 @smallexample
3685 case_statement ::=
3686   @i{case} @i{<typed_variable_>}name @i{is} @{case_item@} @i{end case} ;
3687
3688 case_item ::=
3689   @i{when} discrete_choice_list =>
3690     @{case_statement
3691       | attribute_declaration
3692       | variable_declaration
3693       | empty_declaration@}
3694
3695 discrete_choice_list ::= string_literal @{| string_literal@} | @i{others}
3696 @end smallexample
3697
3698 @noindent
3699 Here is a typical example:
3700
3701 @smallexample @c projectfile
3702 @group
3703 project MyProj is
3704    type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
3705    OS : OS_Type := external ("OS", "GNU/Linux");
3706
3707    package Compiler is
3708      case OS is
3709        when "GNU/Linux" | "Unix" =>
3710          for Switches ("Ada") use ("-gnath");
3711        when "NT" =>
3712          for Switches ("Ada") use ("-gnatP");
3713        when others =>
3714          null;
3715      end case;
3716    end Compiler;
3717 end MyProj;
3718 @end group
3719 @end smallexample
3720
3721 @c ---------------------------------------------
3722 @node Tools Supporting Project Files
3723 @chapter Tools Supporting Project Files
3724 @c ---------------------------------------------
3725
3726 @noindent
3727
3728 @menu
3729 * gnatmake and Project Files::
3730 * The GNAT Driver and Project Files::
3731 * The Development Environments::
3732 @end menu
3733
3734 @c ---------------------------------------------
3735 @node gnatmake and Project Files
3736 @section gnatmake and Project Files
3737 @c ---------------------------------------------
3738
3739 @noindent
3740 This section covers several topics related to @command{gnatmake} and
3741 project files: defining ^switches^switches^ for @command{gnatmake}
3742 and for the tools that it invokes; specifying configuration pragmas;
3743 the use of the @code{Main} attribute; building and rebuilding library project
3744 files.
3745
3746 @menu
3747 * Switches Related to Project Files::
3748 * Switches and Project Files::
3749 * Specifying Configuration Pragmas::
3750 * Project Files and Main Subprograms::
3751 * Library Project Files::
3752 @end menu
3753
3754 @c ---------------------------------------------
3755 @node Switches Related to Project Files
3756 @subsection Switches Related to Project Files
3757 @c ---------------------------------------------
3758
3759 @noindent
3760 The following switches are used by GNAT tools that support project files:
3761
3762 @table @option
3763
3764 @item ^-P^/PROJECT_FILE=^@var{project}
3765 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
3766 Indicates the name of a project file. This project file will be parsed with
3767 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
3768 if any, and using the external references indicated
3769 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
3770 @ifclear vms
3771 There may zero, one or more spaces between @option{-P} and @var{project}.
3772 @end ifclear
3773
3774 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
3775
3776 Since the Project Manager parses the project file only after all the switches
3777 on the command line are checked, the order of the switches
3778 @option{^-P^/PROJECT_FILE^},
3779 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
3780 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
3781
3782 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
3783 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
3784 Indicates that external variable @var{name} has the value @var{value}.
3785 The Project Manager will use this value for occurrences of
3786 @code{external(name)} when parsing the project file.
3787
3788 @ifclear vms
3789 If @var{name} or @var{value} includes a space, then @var{name=value} should be
3790 put between quotes.
3791 @smallexample
3792   -XOS=NT
3793   -X"user=John Doe"
3794 @end smallexample
3795 @end ifclear
3796
3797 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
3798 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
3799 @var{name}, only the last one is used.
3800
3801 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
3802 takes precedence over the value of the same name in the environment.
3803
3804 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
3805 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
3806 Indicates the verbosity of the parsing of GNAT project files.
3807
3808 @ifclear vms
3809 @option{-vP0} means Default;
3810 @option{-vP1} means Medium;
3811 @option{-vP2} means High.
3812 @end ifclear
3813
3814 @ifset vms
3815 There are three possible options for this qualifier: DEFAULT, MEDIUM and
3816 HIGH.
3817 @end ifset
3818
3819 The default is ^Default^DEFAULT^: no output for syntactically correct
3820 project files.
3821 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
3822 only the last one is used.
3823
3824 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
3825 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
3826 Add directory <dir> at the beginning of the project search path, in order,
3827 after the current working directory.
3828
3829 @ifclear vms
3830 @item -eL
3831 @cindex @option{-eL} (any project-aware tool)
3832 Follow all symbolic links when processing project files.
3833 @end ifclear
3834
3835 @item ^--subdirs^/SUBDIRS^=<subdir>
3836 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
3837 This switch is recognized by gnatmake and gnatclean. It indicate that the real
3838 directories (except the source directories) are the subdirectories <subdir>
3839 of the directories specified in the project files. This applies in particular
3840 to object directories, library directories and exec directories. If the
3841 subdirectories do not exist, they are created automatically.
3842
3843 @end table
3844
3845 @c ---------------------------------------------
3846 @node Switches and Project Files
3847 @subsection Switches and Project Files
3848 @c ---------------------------------------------
3849
3850 @noindent
3851 @ifset vms
3852 It is not currently possible to specify VMS style qualifiers in the project
3853 files; only Unix style ^switches^switches^ may be specified.
3854 @end ifset
3855
3856 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
3857 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
3858 attribute, a @code{Switches} attribute, or both;
3859 as their names imply, these ^switch^switch^-related
3860 attributes affect the ^switches^switches^ that are used for each of these GNAT
3861 components when
3862 @command{gnatmake} is invoked.  As will be explained below, these
3863 component-specific ^switches^switches^ precede
3864 the ^switches^switches^ provided on the @command{gnatmake} command line.
3865
3866 The @code{^Default_Switches^Default_Switches^} attribute is an attribute
3867 indexed by language name (case insensitive) whose value is a string list.
3868 For example:
3869
3870 @smallexample @c projectfile
3871 @group
3872 package Compiler is
3873   for ^Default_Switches^Default_Switches^ ("Ada")
3874       use ("^-gnaty^-gnaty^",
3875            "^-v^-v^");
3876 end Compiler;
3877 @end group
3878 @end smallexample
3879
3880 @noindent
3881 The @code{Switches} attribute is indexed on a file name (which may or may
3882 not be case sensitive, depending
3883 on the operating system) whose value is a string list.  For example:
3884
3885 @smallexample @c projectfile
3886 @group
3887 package Builder is
3888    for Switches ("main1.adb")
3889        use ("^-O2^-O2^");
3890    for Switches ("main2.adb")
3891        use ("^-g^-g^");
3892 end Builder;
3893 @end group
3894 @end smallexample
3895
3896 @noindent
3897 For the @code{Builder} package, the file names must designate source files
3898 for main subprograms.  For the @code{Binder} and @code{Linker} packages, the
3899 file names must designate @file{ALI} or source files for main subprograms.
3900 In each case just the file name without an explicit extension is acceptable.
3901
3902 For each tool used in a program build (@command{gnatmake}, the compiler, the
3903 binder, and the linker), the corresponding package @dfn{contributes} a set of
3904 ^switches^switches^ for each file on which the tool is invoked, based on the
3905 ^switch^switch^-related attributes defined in the package.
3906 In particular, the ^switches^switches^
3907 that each of these packages contributes for a given file @var{f} comprise:
3908
3909 @itemize @bullet
3910 @item the value of attribute @code{Switches (@var{f})},
3911   if it is specified in the package for the given file,
3912 @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
3913   if it is specified in the package.
3914
3915 @end itemize
3916
3917 @noindent
3918 If neither of these attributes is defined in the package, then the package does
3919 not contribute any ^switches^switches^ for the given file.
3920
3921 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
3922 two sets, in the following order: those contributed for the file
3923 by the @code{Builder} package;
3924 and the switches passed on the command line.
3925
3926 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
3927 the ^switches^switches^ passed to the tool comprise three sets,
3928 in the following order:
3929
3930 @enumerate
3931 @item
3932 the applicable ^switches^switches^ contributed for the file
3933 by the @code{Builder} package in the project file supplied on the command line;
3934
3935 @item
3936 those contributed for the file by the package (in the relevant project file --
3937 see below) corresponding to the tool; and
3938
3939 @item
3940 the applicable switches passed on the command line.
3941 @end enumerate
3942
3943 The term @emph{applicable ^switches^switches^} reflects the fact that
3944 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
3945 tools, depending on the individual ^switch^switch^.
3946
3947 @command{gnatmake} may invoke the compiler on source files from different
3948 projects. The Project Manager will use the appropriate project file to
3949 determine the @code{Compiler} package for each source file being compiled.
3950 Likewise for the @code{Binder} and @code{Linker} packages.
3951
3952 As an example, consider the following package in a project file:
3953
3954 @smallexample @c projectfile
3955 @group
3956 project Proj1 is
3957    package Compiler is
3958       for ^Default_Switches^Default_Switches^ ("Ada")
3959           use ("^-g^-g^");
3960       for Switches ("a.adb")
3961           use ("^-O1^-O1^");
3962       for Switches ("b.adb")
3963           use ("^-O2^-O2^",
3964                "^-gnaty^-gnaty^");
3965    end Compiler;
3966 end Proj1;
3967 @end group
3968 @end smallexample
3969
3970 @noindent
3971 If @command{gnatmake} is invoked with this project file, and it needs to
3972 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
3973 @file{a.adb} will be compiled with the ^switch^switch^
3974 @option{^-O1^-O1^},
3975 @file{b.adb} with ^switches^switches^
3976 @option{^-O2^-O2^}
3977 and @option{^-gnaty^-gnaty^},
3978 and @file{c.adb} with @option{^-g^-g^}.
3979
3980 The following example illustrates the ordering of the ^switches^switches^
3981 contributed by different packages:
3982
3983 @smallexample @c projectfile
3984 @group
3985 project Proj2 is
3986    package Builder is
3987       for Switches ("main.adb")
3988           use ("^-g^-g^",
3989                "^-O1^-)1^",
3990                "^-f^-f^");
3991    end Builder;
3992 @end group
3993
3994 @group
3995    package Compiler is
3996       for Switches ("main.adb")
3997           use ("^-O2^-O2^");
3998    end Compiler;
3999 end Proj2;
4000 @end group
4001 @end smallexample
4002
4003 @noindent
4004 If you issue the command:
4005
4006 @smallexample
4007     gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
4008 @end smallexample
4009
4010 @noindent
4011 then the compiler will be invoked on @file{main.adb} with the following
4012 sequence of ^switches^switches^
4013
4014 @smallexample
4015    ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
4016 @end smallexample
4017
4018 @noindent
4019 with the last @option{^-O^-O^}
4020 ^switch^switch^ having precedence over the earlier ones;
4021 several other ^switches^switches^
4022 (such as @option{^-c^-c^}) are added implicitly.
4023
4024 The ^switches^switches^
4025 @option{^-g^-g^}
4026 and @option{^-O1^-O1^} are contributed by package
4027 @code{Builder},  @option{^-O2^-O2^} is contributed
4028 by the package @code{Compiler}
4029 and @option{^-O0^-O0^} comes from the command line.
4030
4031 The @option{^-g^-g^}
4032 ^switch^switch^ will also be passed in the invocation of
4033 @command{Gnatlink.}
4034
4035 A final example illustrates switch contributions from packages in different
4036 project files:
4037
4038 @smallexample @c projectfile
4039 @group
4040 project Proj3 is
4041    for Source_Files use ("pack.ads", "pack.adb");
4042    package Compiler is
4043       for ^Default_Switches^Default_Switches^ ("Ada")
4044           use ("^-gnata^-gnata^");
4045    end Compiler;
4046 end Proj3;
4047 @end group
4048
4049 @group
4050 with "Proj3";
4051 project Proj4 is
4052    for Source_Files use ("foo_main.adb", "bar_main.adb");
4053    package Builder is
4054       for Switches ("foo_main.adb")
4055           use ("^-s^-s^",
4056                "^-g^-g^");
4057    end Builder;
4058 end Proj4;
4059 @end group
4060
4061 @group
4062 -- Ada source file:
4063 with Pack;
4064 procedure Foo_Main is
4065    @dots{}
4066 end Foo_Main;
4067 @end group
4068 @end smallexample
4069
4070 @noindent
4071 If the command is
4072 @smallexample
4073 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
4074 @end smallexample
4075
4076 @noindent
4077 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
4078 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
4079 @option{^-gnato^-gnato^} (passed on the command line).
4080 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
4081 are @option{^-g^-g^} from @code{Proj4.Builder},
4082 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
4083 and @option{^-gnato^-gnato^} from the command line.
4084
4085 When using @command{gnatmake} with project files, some ^switches^switches^ or
4086 arguments may be expressed as relative paths. As the working directory where
4087 compilation occurs may change, these relative paths are converted to absolute
4088 paths. For the ^switches^switches^ found in a project file, the relative paths
4089 are relative to the project file directory, for the switches on the command
4090 line, they are relative to the directory where @command{gnatmake} is invoked.
4091 The ^switches^switches^ for which this occurs are:
4092 ^-I^-I^,
4093 ^-A^-A^,
4094 ^-L^-L^,
4095 ^-aO^-aO^,
4096 ^-aL^-aL^,
4097 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
4098 ^switch^switch^
4099 ^-o^-o^, object files specified in package @code{Linker} or after
4100 -largs on the command line). The exception to this rule is the ^switch^switch^
4101 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
4102
4103 @c ---------------------------------------------
4104 @node Specifying Configuration Pragmas
4105 @subsection Specifying Configuration Pragmas
4106 @c ---------------------------------------------
4107
4108 @noindent
4109 When using @command{gnatmake} with project files, if there exists a file
4110 @file{gnat.adc} that contains configuration pragmas, this file will be
4111 ignored.
4112
4113 Configuration pragmas can be defined by means of the following attributes in
4114 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
4115 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
4116
4117 Both these attributes are single string attributes. Their values is the path
4118 name of a file containing configuration pragmas. If a path name is relative,
4119 then it is relative to the project directory of the project file where the
4120 attribute is defined.
4121
4122 When compiling a source, the configuration pragmas used are, in order,
4123 those listed in the file designated by attribute
4124 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main